openapi: 3.2.0 info: title: Spreedly API V1 Authorize API version: v1 description: An OpenAPI specification file for V1 of the Spreedly Core Transactional API servers: - url: https://core.spreedly.com/v1 tags: - name: authorize paths: /gateways/{gateway_token}/authorize: post: summary: Authorize a payment method token tags: - authorize security: - basic_auth: [] operationId: authorize description: 'Authorize a payment method to be charged a specific amount at the target gateway. No funds are taken with an authorize – a follow-up [capture](https://developer.spreedly.com/reference/capture-transaction) transaction is required to actually move the funds. The referenced gateway must exist in the environment whose environment key is being used to authenticate the API call. **Tokenized payment method:** Authorize a Payment Method Token (already stored in the Spreedly environment) to be charged a specific amount. The `payment_method_token` field of the transaction request is required. **Pass-in credit card:** Pass a credit card payment method directly in to the authorize request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `credit_card` field of the transaction request is required. **Pass-in Apple Pay:** Pass an Apple Pay payment method directly into the authorize request. If the Apple Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `apple_pay` field of the transaction request is required. **Pass-in Google Pay:** Pass a Google Pay payment method directly in to the authorize request. If the Google Pay data is valid, it will automatically be tokenized at Spreedly before sending to the gateway. The `google_pay` field of the transaction request is required. **SCA Authenticated:** Authorize an SCA Authenticated payment method (already stored in the Spreedly environment) to be charged a specific amount. The `sca_authentication_token` field of the transaction request is required. ' parameters: - $ref: '#/components/parameters/gateway_token' responses: '200': description: OK content: Network Token Provisioned: examples: application/json: value: transaction: token: 3iUAv9hUqP7x0bMxVtQKXlayFx0 succeeded: true message: Succeeded! gateway_transaction_id: '63' retain_on_success: false payment_method_added: false response: success: true message: Successful authorize avs_code: null avs_message: null cvv_code: null cvv_message: null pending: false result_unknown: false error_code: null error_detail: null cancelled: false fraud_review: null created_at: '2018-11-07T15:05:08Z' updated_at: '2018-11-07T15:05:08Z' payment_method: token: 1rpKvP8zOUhj4Y9EDrIoIYQzzD5 created_at: '2017-06-26T17:04:38Z' updated_at: '2018-11-07T15:05:07Z' email: joey@example.com data: my_payment_method_identifier: '448' extra_stuff: some_other_things: Can be anything really storage_state: retained test: true metadata: key: string value another_key: 123 final_key: true last_four_digits: '1111' first_six_digits: '411111' card_type: visa first_name: Newfirst last_name: Newlast month: 3 year: 2032 address1: null address2: null city: null state: null zip: null country: null phone_number: null company: null full_name: Newfirst Newlast eligible_for_card_updater: null shipping_address1: null shipping_address2: null shipping_city: null shipping_state: null shipping_zip: null shipping_country: null shipping_phone_number: null payment_method_type: credit_card bin_metadata: card_brand: DISCOVER card_category: PERSONAL card_type: CREDIT issuing_bank: DISCOVER BANK issuing_country_iso_number: '840' issuing_country_iso_a2_code: US issuing_country_iso_a3_code: USA issuing_country_iso_name: UNITED STATES issuing_bank_phone_number: 1 (800) 347-7000 issuing_bank_website: HTTPS://WWW.DISCOVER.COM/ bin_type: PERSONAL regulated: Y max_pan_length: 19 message: Successful errors: [] fingerprint: e3cef43464fc832f6e04f187df25af497994 verification_value: '' number: XXXX-XXXX-XXXX-1111 sub_merchant_key: null gateway_specific_response_fields: {} network_tokenization: provisioned: true token_status: active token_reference: DWSP01234567890ABCDEF0123456789AB token_first_six_digits: '411111' token_last_four_digits: '1234' token_created_at: '2024-01-15T10:30:00Z' token_updated_at: '2024-01-15T10:30:00Z' application/xml: value: "\n\n 3iUAv9hUqP7x0bMxVtQKXlayFx0\n true\n Succeeded!\n 63\n false\n false\n \n true\n Successful authorize\n \n \n \n \n false\n false\n \n \n false\n \n 2018-11-07T15:05:08Z\n 2018-11-07T15:05:08Z\n \n \n 1rpKvP8zOUhj4Y9EDrIoIYQzzD5\n 2017-06-26T17:04:38Z\n 2018-11-07T15:05:07Z\n joey@example.com\n \n 448\n \n Can be anything really\n \n \n retained\n true\n \n string value\n 123\n true\n \n 1111\n 411111\n visa\n Newfirst\n Newlast\n 3\n 2032\n \n \n \n \n \n \n \n \n Newfirst Newlast\n \n \n \n \n \n \n \n \n credit_card\n \n DISCOVER\n PERSONAL\n CREDIT\n DISCOVER BANK\n 840\n US\n USA\n UNITED STATES\n 1 (800) 347-7000\n HTTPS://WWW.DISCOVER.COM/\n PERSONAL\n Y\n 19\n Successful\n \n \n e3cef43464fc832f6e04f187df25af497994\n \n XXXX-XXXX-XXXX-1111\n \n \n \n \n \n true\n active\n DWSP01234567890ABCDEF0123456789AB\n 411111\n 1234\n 2024-01-15T10:30:00Z\n 2024-01-15T10:30:00Z\n \n\n" Network Token Provision Failed: examples: application/json: value: transaction: token: 3iUAv9hUqP7x0bMxVtQKXlayFx0 succeeded: true message: Succeeded! gateway_transaction_id: '63' retain_on_success: false payment_method_added: false response: success: true message: Successful authorize avs_code: null avs_message: null cvv_code: null cvv_message: null pending: false result_unknown: false error_code: null error_detail: null cancelled: false fraud_review: null created_at: '2018-11-07T15:05:08Z' updated_at: '2018-11-07T15:05:08Z' payment_method: token: 1rpKvP8zOUhj4Y9EDrIoIYQzzD5 created_at: '2017-06-26T17:04:38Z' updated_at: '2018-11-07T15:05:07Z' email: joey@example.com data: my_payment_method_identifier: '448' extra_stuff: some_other_things: Can be anything really storage_state: retained test: true metadata: key: string value another_key: 123 final_key: true last_four_digits: '1111' first_six_digits: '411111' card_type: visa first_name: Newfirst last_name: Newlast month: 3 year: 2032 address1: null address2: null city: null state: null zip: null country: null phone_number: null company: null full_name: Newfirst Newlast eligible_for_card_updater: null shipping_address1: null shipping_address2: null shipping_city: null shipping_state: null shipping_zip: null shipping_country: null shipping_phone_number: null payment_method_type: credit_card bin_metadata: card_brand: DISCOVER card_category: PERSONAL card_type: CREDIT issuing_bank: DISCOVER BANK issuing_country_iso_number: '840' issuing_country_iso_a2_code: US issuing_country_iso_a3_code: USA issuing_country_iso_name: UNITED STATES issuing_bank_phone_number: 1 (800) 347-7000 issuing_bank_website: HTTPS://WWW.DISCOVER.COM/ bin_type: PERSONAL regulated: Y max_pan_length: 19 message: Successful errors: [] fingerprint: e3cef43464fc832f6e04f187df25af497994 verification_value: '' number: XXXX-XXXX-XXXX-1111 sub_merchant_key: null gateway_specific_response_fields: {} network_tokenization: provisioned: false token_status: null errors: - key: invalidParameter message: Your request does not have valid set of parameters required to process the business function. action: provision_network_token application/xml: value: "\n\n 3iUAv9hUqP7x0bMxVtQKXlayFx0\n true\n Succeeded!\n 63\n false\n false\n \n true\n Successful authorize\n \n \n \n \n false\n false\n \n \n false\n \n 2018-11-07T15:05:08Z\n 2018-11-07T15:05:08Z\n \n \n 1rpKvP8zOUhj4Y9EDrIoIYQzzD5\n 2017-06-26T17:04:38Z\n 2018-11-07T15:05:07Z\n joey@example.com\n \n 448\n \n Can be anything really\n \n \n retained\n true\n \n string value\n 123\n true\n \n 1111\n 411111\n visa\n Newfirst\n Newlast\n 3\n 2032\n \n \n \n \n \n \n \n \n Newfirst Newlast\n \n \n \n \n \n \n \n \n credit_card\n \n DISCOVER\n PERSONAL\n CREDIT\n DISCOVER BANK\n 840\n US\n USA\n UNITED STATES\n 1 (800) 347-7000\n HTTPS://WWW.DISCOVER.COM/\n PERSONAL\n Y\n 19\n Successful\n \n \n e3cef43464fc832f6e04f187df25af497994\n \n XXXX-XXXX-XXXX-1111\n \n \n \n \n \n false\n \n \n \n invalidParameter\n Your request does not have valid set of parameters required to process the business function.\n provision_network_token\n \n \n \n\n" Network Token Attempted: examples: application/json: value: transaction: token: 3iUAv9hUqP7x0bMxVtQKXlayFx0 succeeded: true message: Succeeded! gateway_transaction_id: '63' retain_on_success: false payment_method_added: false response: success: true message: Successful authorize avs_code: null avs_message: null cvv_code: null cvv_message: null pending: false result_unknown: false error_code: null error_detail: null cancelled: false fraud_review: null created_at: '2018-11-07T15:05:08Z' updated_at: '2018-11-07T15:05:08Z' payment_method: token: 1rpKvP8zOUhj4Y9EDrIoIYQzzD5 created_at: '2017-06-26T17:04:38Z' updated_at: '2018-11-07T15:05:07Z' email: joey@example.com data: my_payment_method_identifier: '448' extra_stuff: some_other_things: Can be anything really storage_state: retained test: true metadata: key: string value another_key: 123 final_key: true last_four_digits: '1111' first_six_digits: '411111' card_type: visa first_name: Newfirst last_name: Newlast month: 3 year: 2032 address1: null address2: null city: null state: null zip: null country: null phone_number: null company: null full_name: Newfirst Newlast eligible_for_card_updater: null shipping_address1: null shipping_address2: null shipping_city: null shipping_state: null shipping_zip: null shipping_country: null shipping_phone_number: null payment_method_type: credit_card bin_metadata: card_brand: DISCOVER card_category: PERSONAL card_type: CREDIT issuing_bank: DISCOVER BANK issuing_country_iso_number: '840' issuing_country_iso_a2_code: US issuing_country_iso_a3_code: USA issuing_country_iso_name: UNITED STATES issuing_bank_phone_number: 1 (800) 347-7000 issuing_bank_website: HTTPS://WWW.DISCOVER.COM/ bin_type: PERSONAL regulated: Y max_pan_length: 19 message: Successful errors: [] fingerprint: e3cef43464fc832f6e04f187df25af497994 verification_value: '' number: XXXX-XXXX-XXXX-1111 sub_merchant_key: null gateway_specific_response_fields: {} network_tokenization: attempted: true token_status: active token_reference: DWSP01234567890ABCDEF0123456789AB token_first_six_digits: '411111' token_last_four_digits: '1234' token_created_at: '2024-01-15T10:30:00Z' token_updated_at: '2024-01-15T10:30:00Z' application/xml: value: "\n\n 3iUAv9hUqP7x0bMxVtQKXlayFx0\n true\n Succeeded!\n 63\n false\n false\n \n true\n Successful authorize\n \n \n \n \n false\n false\n \n \n false\n \n 2018-11-07T15:05:08Z\n 2018-11-07T15:05:08Z\n \n \n 1rpKvP8zOUhj4Y9EDrIoIYQzzD5\n 2017-06-26T17:04:38Z\n 2018-11-07T15:05:07Z\n joey@example.com\n \n 448\n \n Can be anything really\n \n \n retained\n true\n \n string value\n 123\n true\n \n 1111\n 411111\n visa\n Newfirst\n Newlast\n 3\n 2032\n \n \n \n \n \n \n \n \n Newfirst Newlast\n \n \n \n \n \n \n \n \n credit_card\n \n DISCOVER\n PERSONAL\n CREDIT\n DISCOVER BANK\n 840\n US\n USA\n UNITED STATES\n 1 (800) 347-7000\n HTTPS://WWW.DISCOVER.COM/\n PERSONAL\n Y\n 19\n Successful\n \n \n e3cef43464fc832f6e04f187df25af497994\n \n XXXX-XXXX-XXXX-1111\n \n \n \n \n \n true\n active\n DWSP01234567890ABCDEF0123456789AB\n 411111\n 1234\n 2024-01-15T10:30:00Z\n 2024-01-15T10:30:00Z\n \n\n" Network Token Attempted Error: examples: application/json: value: transaction: token: 3iUAv9hUqP7x0bMxVtQKXlayFx0 succeeded: true message: Succeeded! gateway_transaction_id: '63' retain_on_success: false payment_method_added: false response: success: true message: Successful authorize avs_code: null avs_message: null cvv_code: null cvv_message: null pending: false result_unknown: false error_code: null error_detail: null cancelled: false fraud_review: null created_at: '2018-11-07T15:05:08Z' updated_at: '2018-11-07T15:05:08Z' payment_method: token: 1rpKvP8zOUhj4Y9EDrIoIYQzzD5 created_at: '2017-06-26T17:04:38Z' updated_at: '2018-11-07T15:05:07Z' email: joey@example.com data: my_payment_method_identifier: '448' extra_stuff: some_other_things: Can be anything really storage_state: retained test: true metadata: key: string value another_key: 123 final_key: true last_four_digits: '1111' first_six_digits: '411111' card_type: visa first_name: Newfirst last_name: Newlast month: 3 year: 2032 address1: null address2: null city: null state: null zip: null country: null phone_number: null company: null full_name: Newfirst Newlast eligible_for_card_updater: null shipping_address1: null shipping_address2: null shipping_city: null shipping_state: null shipping_zip: null shipping_country: null shipping_phone_number: null payment_method_type: credit_card bin_metadata: card_brand: DISCOVER card_category: PERSONAL card_type: CREDIT issuing_bank: DISCOVER BANK issuing_country_iso_number: '840' issuing_country_iso_a2_code: US issuing_country_iso_a3_code: USA issuing_country_iso_name: UNITED STATES issuing_bank_phone_number: 1 (800) 347-7000 issuing_bank_website: HTTPS://WWW.DISCOVER.COM/ bin_type: PERSONAL regulated: Y max_pan_length: 19 message: Successful errors: [] fingerprint: e3cef43464fc832f6e04f187df25af497994 verification_value: '' number: XXXX-XXXX-XXXX-1111 sub_merchant_key: null gateway_specific_response_fields: {} network_tokenization: attempted: false token_status: active errors: - key: cryptogram_error message: Cryptogram could not be successfully retrieved for Network Token. action: attempt_network_token application/xml: value: "\n\n 3iUAv9hUqP7x0bMxVtQKXlayFx0\n true\n Succeeded!\n 63\n false\n false\n \n true\n Successful authorize\n \n \n \n \n false\n false\n \n \n false\n \n 2018-11-07T15:05:08Z\n 2018-11-07T15:05:08Z\n \n \n 1rpKvP8zOUhj4Y9EDrIoIYQzzD5\n 2017-06-26T17:04:38Z\n 2018-11-07T15:05:07Z\n joey@example.com\n \n 448\n \n Can be anything really\n \n \n retained\n true\n \n string value\n 123\n true\n \n 1111\n 411111\n visa\n Newfirst\n Newlast\n 3\n 2032\n \n \n \n \n \n \n \n \n Newfirst Newlast\n \n \n \n \n \n \n \n \n credit_card\n \n DISCOVER\n PERSONAL\n CREDIT\n DISCOVER BANK\n 840\n US\n USA\n UNITED STATES\n 1 (800) 347-7000\n HTTPS://WWW.DISCOVER.COM/\n PERSONAL\n Y\n 19\n Successful\n \n \n e3cef43464fc832f6e04f187df25af497994\n \n XXXX-XXXX-XXXX-1111\n \n \n \n \n \n false\n active\n \n \n cryptogram_error\n Cryptogram could not be successfully retrieved for Network Token.\n attempt_network_token\n \n \n \n\n" application/json: schema: $ref: '#/components/schemas/authorize_response' application/xml: schema: $ref: '#/components/schemas/authorize_response' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/errors' application/xml: schema: $ref: '#/components/schemas/errors' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/errors' application/xml: schema: $ref: '#/components/schemas/errors' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/errors' application/xml: schema: $ref: '#/components/schemas/errors' requestBody: content: application/json: schema: $ref: '#/components/schemas/authorize_request' examples: Payment method token: summary: Payment method token value: transaction: payment_method_token: '' amount: 100 currency_code: USD With Recover: summary: With Recover value: transaction: payment_method_token: '' amount: 100 currency_code: USD retry: gateway_tokens: - '' - '' mode: '' custom_errors: gateway_type: override_error_codes: false messages: - '' - '' SCA Authenticated: summary: SCA Authenticated value: transaction: sca_authentication_token: '' amount: 1122 currency_code: USD Pass in credit card: summary: Pass in credit card value: transaction: amount: 100 currency_code: USD credit_card: first_name: Joe last_name: Smith number: 4111111111111111 verification_value: 123 month: 12 year: 2030 Pass in Apple Pay: summary: Pass in Apple Pay value: transaction: amount: 100 currency_code: USD apple_pay: payment_data: version: '' data: '' signature: '' header: ephemeralPublicKey: '' transactionId: '' publicKeyHash: '' test_card_number: '4111111111111111' Pass in Google Pay: summary: Pass in Google Pay value: transaction: amount: 1122 currency_code: USD google_pay: payment_data: signature: '' protocolVersion: '' signedMessage: '{}' test_card_number: '4111111111111111' With Protection parameters: summary: With Protection parameters value: transaction: amount: 1000 currency_code: USD payment_method_token: 4EGlSI8da0wgSe7KDMR7dQrttQt protection_provider_token: 5TT6BS9GA9RE3AHPH3AEPPE0G6 protection_parameters: test_scenario: scenario: '' forter_mobile_uid: e520-ba9a-367-60b fraud_token: dsjhsudeu user_agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36 cart_items: - name: White GenericBrand handbag quantity: 1 type: TANGIBLE price: '1000' - name: White GenericBrand handbag quantity: 1 type: TANGIBLE price: '1000' delivery_type: PHYSICAL delivery_method: FedEx customer_account_id: '1234567' customer_account_type: BUSINESS customer_account_creation_date: 1234567 billing_name: Firstname Lastname billing_first_name: Firstname billing_last_name: Lastname email: email@email.com billing_country: US billing_address1: 123 Fake St billing_address2: '' billing_city: Durham billing_zip: '01435' billing_phone_number: '1234567890' shipping_name: Same Name shipping_first_name: Same shipping_last_name: Name shipping_email: email@email.com shipping_address1: 321 Real St shipping_address2: '' shipping_city: Orlando shipping_state: FL shipping_phone_number: 0987654321 Provision Network Token: summary: Attempt to Provision Network Token value: transaction: payment_method_token: '' amount: 100 currency_code: USD retain_on_success: true provision_network_token: true Attempt Network Token: summary: Attempt to Transact with Network Token value: transaction: payment_method_token: '' amount: 100 currency_code: USD attempt_network_token: true application/xml: schema: $ref: '#/components/schemas/authorize_request' examples: Payment method token: summary: Payment method token value: transaction: payment_method_token: '' amount: 100 currency_code: USD With Recover: summary: With Recover value: transaction: payment_method_token: '' amount: 100 currency_code: USD retry: gateway_tokens: - '' - '' mode: '' custom_errors: gateway_type: override_error_codes: false messages: - '' - '' SCA Authenticated: summary: SCA Authenticated value: transaction: sca_authentication_token: '' amount: 1122 currency_code: USD Pass in credit card: summary: Pass in credit card value: transaction: amount: 100 currency_code: USD credit_card: first_name: Joe last_name: Smith number: 4111111111111111 verification_value: 123 month: 12 year: 2030 Pass in Apple Pay: summary: Pass in Apple Pay value: transaction: amount: 100 currency_code: USD apple_pay: payment_data: version: '' data: '' signature: '' header: ephemeralPublicKey: '' transactionId: '' publicKeyHash: '' test_card_number: '4111111111111111' Pass in Google Pay: summary: Pass in Google Pay value: transaction: amount: 1122 currency_code: USD google_pay: payment_data: signature: '' protocolVersion: '' signedMessage: '{}' test_card_number: '4111111111111111' With Protection parameters: summary: With Protection parameters value: transaction: amount: 1000 currency_code: USD payment_method_token: 4EGlSI8da0wgSe7KDMR7dQrttQt protection_provider_token: 5TT6BS9GA9RE3AHPH3AEPPE0G6 protection_parameters: test_scenario: scenario: '' forter_mobile_uid: e520-ba9a-367-60b fraud_token: dsjhsudeu user_agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.73 Safari/537.36 cart_items: - name: White GenericBrand handbag quantity: 1 type: TANGIBLE price: '1000' - name: White GenericBrand handbag quantity: 1 type: TANGIBLE price: '1000' delivery_type: PHYSICAL delivery_method: FedEx customer_account_id: '1234567' customer_account_type: BUSINESS customer_account_creation_date: 1234567 billing_name: Firstname Lastname billing_first_name: Firstname billing_last_name: Lastname email: email@email.com billing_country: US billing_address1: 123 Fake St billing_address2: '' billing_city: Durham billing_zip: '01435' billing_phone_number: '1234567890' shipping_name: Same Name shipping_first_name: Same shipping_last_name: Name shipping_email: email@email.com shipping_address1: 321 Real St shipping_address2: '' shipping_city: Orlando shipping_state: FL shipping_phone_number: 0987654321 Provision Network Token: summary: Attempt to Provision Network Token value: transaction: payment_method_token: '' amount: 100 currency_code: USD retain_on_success: true provision_network_token: true Attempt Network Token: summary: Attempt to Transact with Network Token value: transaction: payment_method_token: '' amount: 100 currency_code: USD attempt_network_token: true components: schemas: protect_fraud_check_response: type: object description: When a Fraud Check is attempted, provides an overview of the results at the time of the current transaction. For more information on Protection Fraud Checks, see [the guide](https://developer.spreedly.com/docs/protect). properties: updated_at: type: string description: The time the fraud check was last updated created_at: type: string description: The time the fraud check was created protection_provider_key: type: string description: The token of the Protection Provider used for this check succeeded: type: boolean description: Whether the fraud check request was successfully executed state: type: string description: The current state of the fraud check token: type: string description: The token uniquely identifying this fraud check at Spreedly message: type: string description: A human-readable message describing the result (if applicable) amount: type: number description: The transaction amount checked currency_code: type: string description: The currency of the funds in ISO format (e.g., USD) ip: type: string description: The IP address associated with the transaction email: type: string description: The email address associated with the transaction transaction_type: type: string description: The type of transaction gateway_transaction_key: type: string description: The Spreedly transaction token of the parent gateway transaction callback_url: type: string description: The URL where Spreedly will attempt delivery of asynchronous results (if provided) test_scenario: type: string description: The test scenario used acquiring_bank_fraud_rate: type: string description: The threshold for bank fraud rate used for exemption requests exemption_type: type: string description: The type of exemption requested (if applicable) warning: type: string description: Any warning messages from the fraud check managed_order_token: type: string description: The token of the fraud check returned by the fraud check provider fraud_decision: type: string description: The fraud decision outcome (e.g., approve, decline, review) fraud_recommendation: type: string description: Additional recommendation information from the fraud provider fraud_decision_reason: type: string description: Reason for the fraud decision vendor_response: type: object description: Detailed response from the fraud protection vendor properties: forterDecision: type: string description: The decision returned by Forter recommendation: type: string description: Recommended action from the vendor verificationMethod: type: object description: Methods used to verify the transaction decisionReason: type: string description: Reason for the vendor's decision merchantPolicyId: type: string description: Merchant policy identifier used to make the decision orderId: type: string description: Order identifier in the vendor's system linkToEventInDashboard: type: string description: URL to view the transaction details in the vendor's dashboard payment_method: type: object properties: token: type: string description: The token identifying the payment method in the Spreedly vault created_at: type: string description: The time the payment method token was created updated_at: type: string description: The time the payment method token was last updated email: type: string description: The email address of the customer associated with this credit card storage_state: type: string description: The `storage_state` (retained, redacted, cached, used) of the payment method test: type: boolean description: '`true` if this payment method is a test payment method and cannot be used against real gateways or receivers' metadata: type: object description: metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types callback_url: type: string description: 'The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by `callback_format` if provided or XML if `callback_format` is not present or null. (default: `null`)' last_four_digits: type: string description: The last four digits of the credit card number. This can be displayed to the user. first_six_digits: type: string description: The first six digits of the credit card number. This can be displayed to the user. card_type: type: string description: The [type](https://developer.spreedly.com/docs/supported-payment-methods), or brand, of the card. Please see the `card_type_mapping` function below for more detail. first_name: type: string description: The first name of the cardholder last_name: type: string description: The last name of the cardholder month: type: string description: The expiration month year: type: string description: The expiration year address1: type: string description: The first line of the billing address address2: type: string description: The second line of the billing address city: type: string description: The city of the billing address state: type: string description: The state of the billing address zip: type: string description: The zip code of the billing address country: type: string description: The country code of the billing address phone_number: type: string description: The phone number of the billing address company: type: string description: The company of the cardholder full_name: type: string description: The full name of the cardholder. eligible_for_card_updater: type: string description: '`true` if this payment method should be included in Account Updater' shipping_address1: type: string description: The first line of the shipping address shipping_address2: type: string description: The second line of the shipping address shipping_city: type: string description: The city of the shipping address shipping_state: type: string description: The state of the shipping address shipping_zip: type: string description: The zip code of the shipping address shipping_country: type: string description: The country code of the shipping address issuer_identification_number: type: string description: The numbers of the PAN required to identify the card issuer. click_to_pay: type: string description: '`true` if the card was tokenized using Click to Pay' managed: type: string description: The value indicating the payment method's management status. payment_method_type: type: string description: The type of this payment method, e.g., `credit_card`, `bank_account`, `apple_pay`, `google_pay`, `third_party_token`, etc… errors: type: string description: If the payment method is invalid (missing required fields, etc…), there will be associated error messages here fingerprint: type: string description: An identifying string that will match all cards in the environment with the same PAN verification_value: type: string description: The obscured verification value (CVV), e.g., XXX or XXXX number: type: string description: The obscured credit card number, e.g., XXXX-XXXX-XXXX-4444 bin_metadata: type: object description: BIN metadata is available in the response if the card is enrolled in Advanced Vault. See [BIN metadata](https://developer.spreedly.com/docs/bin-metadata) for more information. properties: card_brand: type: string card_category: type: string card_type: type: string issuing_bank: type: string issuing_country_iso_number: type: string issuing_country_iso_a2_code: type: string issuing_country_iso_a3_code: type: string issuing_country_iso_name: type: string issuing_bank_phone_number: type: string issuing_bank_website: type: string bin_type: type: string regulated: type: string max_pan_length: type: string message: type: string subscribed_to_mastercard_abu: type: boolean example: false description: '`true` if this payment method is subscribed to Mastercard ABU updating service' last_successfully_used: type: string format: date-time nullable: true description: 'The time (UTC) the payment method was last successfully transacted with. The following transaction types are considered: Authorization, Purchase, Verification, GeneralCredit, OffsiteVerification, or OffsitePurchase' authorize_response: type: object properties: transaction: type: object properties: token: type: string description: The token uniquely identifying this transaction at Spreedly succeeded: type: boolean description: '`true` if the transaction request was successfully executed, `false` otherwise' message: type: string description: A human-readable string indicating the result of the transaction gateway_transaction_id: type: string description: The id of the transaction at the gateway. To be used when corresponding with the gateway or reconciling transactions retain_on_success: type: boolean description: If the payment method was set to be retained on successful completion of the transaction. To determine if the payment method was actually retained, see the `payment_method/storage_state` field payment_method_added: type: string description: If the payment method was added as part of this transaction (i.e. a direct pass-in of the payment information) vs. using an already tokenized payment method response: type: object description: Unmodified details of the gateway response, including the `message` and `error_code`, if applicable. For failed transactions these fields can help determine the root cause payment_method: $ref: '#/components/schemas/payment_method' merchant_profile_key: type: string description: The token of the Merchant Profile associated with the gateway used for the transaction sub_merchant_key: type: string description: The token of the sub-merchant associated with the transaction. gateway_specific_response_fields: type: object description: A hash containing unique optional fields that a gateway may return based on certain customized options. transaction_metadata: type: object description: The hash of key/value pairs that was included in the transaction request body. sca_authentication: type: string description: The details of the SCA Authentication transaction created if performing a Spreedly Global 3DS2 transaction. See the [SCA Authentication Show](https://developer.spreedly.com/reference/authenticate) details for more information on this object. payment_snapshot: $ref: '#/components/schemas/payment_snapshot' protection_provider_key: type: string description: The token of the Protection Provider that was used for this transaction. protection_parameters: $ref: '#/components/schemas/protection_parameters' protect_fraud_check: $ref: '#/components/schemas/protect_fraud_check_response' network_tokenization: $ref: '#/components/schemas/network_tokenization' sca_authenticated: type: object properties: sca_authentication_token: type: string description: The token received in response body of SCA Authenticate endpoint when performing an SCA Authentication on a specified payment method. See [instructions to obtain](https://developer.spreedly.com/docs/3ds-solutions#how-to-utilize-your-sca-provider-key) amount: type: integer description: The amount to request, as an integer. E.g., `1000` for $10.00. currency_code: type: string description: The currency of the funds, as [ISO 4217 alpha currency codes](https://en.wikipedia.org/wiki/ISO_4217#Active_codes), e.g., `USD` for US dollars. required: - sca_authentication_token - amount - currency_code google_pay: type: object required: - payment_data properties: payment_data: description: The JSON serialized [paymentData](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography#payment-method-token-structure) type: object properties: signature: type: string description: Verifies that the message came from Google. Base64-encoded. Created using ECDSA. protocolVersion: type: string description: Identifies the encryption/signing scheme under which the message was created. Allows the protocol to evolve over time, if needed. If it's not set, assume `ECv0`. signedMessage: type: string description: A serialized JSON string containing the `encryptedMessage`, `ephemeralPublicKey` and `tag`. Serialized to simplify the signature verification process. test_card_number: type: string description: Specify a [test card number](https://developer.spreedly.com/docs/test-data#credit-cards) in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Google Pay payment data. first_name: type: string description: The first name of the cardholder last_name: type: string description: The last name of the cardholder address_1: type: string description: Cardholder's address, line 1 address_2: type: string description: Cardholder's address, line 2 city: type: string description: Cardholder's city state: type: string description: Cardholder's state zip: type: string description: Cardholder's zip country: type: string description: Cardholder's country network_tokenization: type: object description: The network tokenization details for the transaction properties: provisioned: type: boolean default: false description: Indicates if the network tokenization was successfully provisioned token_status: type: string description: The status of the network token token_reference: type: string description: The unique reference key for the network token token_first_six_digits: type: string description: The first six digits of the network token's DPAN token_last_four_digits: type: string description: The last four digits of the network token's DPAN token_created_at: type: string description: The timestamp when the network token was created token_updated_at: type: string description: The timestamp when the network token was last updated attempted: type: boolean default: false description: Indicates if the transaction attempted to use a network token errors: type: array description: An array of errors that occurred during the network tokenization process items: type: object properties: key: type: string description: The error key message: type: string description: The error message action: type: string description: The action taken which lead to the error required: false apple_pay: type: object required: - payment_data properties: payment_data: description: The JSON serialized [`paymentData` property of an Apple Pay PKPaymentToken](https://developer.apple.com/library/ios/documentation/PassKit/Reference/PaymentTokenJSON/PaymentTokenJSON.html#//apple_ref/doc/uid/TP40014929-CH8-SW2) type: object properties: version: {} data: {} signature: {} header: type: object properties: ephemeralPublicKey: {} transactionId: {} publicKeyHash: {} test_card_number: description: Apple Pay does not provide a way to create a test payment token. To mark this as a test Apple Pay payment method, specify a [test card number](https://developer.spreedly.com/docs/test-data#credit-cards) in this field. Doing so will prevent this payment method from being used against a production gateway, while still verifying the submitted Apple Pay payment data. authorize_request: type: object properties: transaction: type: object properties: amount: type: integer description: The amount to request, as an integer. E.g., `1000` for $10.00. currency_code: type: string description: The currency of the funds, as [ISO 4217 alpha currency codes](https://en.wikipedia.org/wiki/ISO_4217#Active_codes), e.g., `USD` for US dollars. order_id: type: string description: The merchant specified order id. If not provided, the Spreedly transaction token will be used. description: type: string description: A human readable description of the transaction which will be passed to the gateway if it’s supported retain_on_success: type: boolean description: If the card is verified, retain it so it can be used for future transactions ip: type: string description: The IP address of the end-user customer. If one is not provided, this will default to `127.0.0.1`. To actually send a `nil` value, this parameter must be set to `"omit"`. email: type: string description: Override the customer email address associated with the payment method for this transaction gateway_specific_fields: type: object description: Unique optional fields that a gateway may require for certain customized options. To send a GSF it should be nested under `gateway_specific_fields` and under the gateway’s name, i.e. `gateway_type`. Please refer to [using a payment method](https://developer.spreedly.com/docs/using-payment-methods#gateway-specific-fields) for more info. stored_credential_initiator: type: string description: Who is initiating this request, `merchant` or `cardholder` stored_credential_reason_type: type: string description: What kind of transaction is the payment method being used for. e.g. `recurring`, `unscheduled`, or `installment` sub_merchant_key: type: string description: The token of the [sub-merchant](https://developer.spreedly.com/reference/create-sub-merchant) to associate with the current transaction. If an invalid `sub_merchant_key` is passed through, the value defaults to `null` sca_provider_key: type: string description: '[SCA Provider](https://developer.spreedly.com/reference/create-sca-provider) token that performs a Spreedly 3DS2 Global authentication before attempting the gateway transaction. Please see our [Spreedly 3DS2 Global Guide](https://developer.spreedly.com/docs/3ds-solutions) for more info.' sca_authentication_parameters: type: object description: Additional fields that are accepted by the SCA Authentication, including a `test_scenario` object to indicate valid 3DS2 test flow options and an `exemption_type` field to request an exemption. Please refer to our [3DS2 Global Guide](https://developer.spreedly.com/docs/3ds-solutions) to learn more. properties: three_ds_requestor_challenge_ind: type: string description: Indicates whether a challenge is being requested for a 3DS2 Global transaction. callback_url: type: string description: 'The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by `callback_format` if provided or XML if `callback_format` is not present or null. (default: `null`)' callback_format: type: string description: 'The format in which Spreedly will deliver asynchronous results for 3DS and offsite transactions to the specified `callback_url`. If provided, the value must be one of `json` or `xml`. (default: `xml`)' shipping_address: type: object properties: name: type: string description: Customer’s name in the shipping address address1: type: string description: Customer’s shipping address, line 1 address2: type: string description: Customer’s shipping address, line 2 city: type: string description: Customer’s shipping city state: type: string description: Customer’s shipping state/province zip: type: string description: Customer’s shipping zip country: type: string description: Customer’s shipping country phone_number: type: string description: Customer’s shipping phone billing_address: type: object properties: name: type: string description: Customer’s name in the billing address address1: type: string description: Customer’s billing address, line 1 address2: type: string description: Customer’s billing address, line 2 city: type: string description: Customer’s billing city state: type: string description: Customer’s billing state/province zip: type: string description: Customer’s billing zip country: type: string description: Customer’s billing country phone_number: type: string description: Customer’s billing phone transaction_metadata: type: object description: Metadata key-value pairs used for Smart Routing. Keys must be unique and are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types. credit_card: $ref: '#/components/schemas/credit_card' apple_pay: $ref: '#/components/schemas/apple_pay' google_pay: $ref: '#/components/schemas/google_pay' sca_authenticated: $ref: '#/components/schemas/sca_authenticated' payment_method_token: type: string description: The token of the payment method to use attempt_network_token: type: boolean description: '`true` if this transaction should use a network token if able. `false` or omit this element to not use a network token for this transaction. Please see our [network tokenization guide](https://developer.spreedly.com/docs/network-tokenization#transacting-with-network-tokens) for more details on Network Token logic checks.' provision_network_token: $ref: '#/components/schemas/provision_network_token' retry: $ref: '#/components/schemas/recover_params' protection_provider_key: type: string description: The token of the [Protection Provider](https://developer.spreedly.com/reference/create-protection-provider). Triggers a protection check. protection_parameters: $ref: '#/components/schemas/protection_parameters' allow_blank_name: type: boolean description: '`true` if this payment method should skip the name validation requirement during Pass-in Credit Card transactions' allow_expired_date: type: boolean description: '`true` if this payment method should skip the expired date validation requirement during Pass-in Credit Card transactions' allow_blank_date: type: boolean description: '`true` if this payment method should skip the expiration date validation requirement during Pass-in Credit Card transactions' required: - amount - currency_code payment_snapshot: type: object description: When Recover is attempted, provides an overview of the results at the time of the current transaction. For more information on Recover, see [the guide](https://developer.spreedly.com/docs/recover). properties: gateway_tokens: type: array description: List of all gateway tokens on which the transaction could be attempted. Includes the primary gateway token and all Recover gateway tokens. items: type: string attempts: type: integer description: Number of times the transaction has been attempted. messages: type: object description: Optional field used to communicate information about different Recover situations, for example, falling back to outage only mode if a gateway is primary gateway is unsupported. mode: type: string description: The Recover mode used, either `standard` or `outage_only`. custom_error_used: type: boolean description: '`true` if the transaction used a custom error in the recovery decision process.' override_default_error_codes: type: boolean description: '`true` if the custom error configuration was used instead of Spreedly''s default error configuration.' created_at: type: string description: The time the payment_snapshot was created. updated_at: type: string description: The time the payment_snapshot was updated. payment_token: type: string description: The token corresponding to the Payment object, containing all information about the Recover chain. previous_transaction_tokens: type: array description: List of all previous transactions associated with the Recover attempt. items: type: string errors: type: array items: type: object properties: attribute: type: string description: Which attribute(s) have an error key: type: string description: Error Key message: type: string description: Error Message required: - key - message protection_parameters: description: Additional fields that are accepted by the Protection provider, including a `test_scenario` object to indicate valid Protect test flow options. Please refer to our [Protect guide](https://developer.spreedly.com/docs/protect) to learn more. type: object properties: test_scenario: type: object description: The protection test scenario properties: scenario: type: string description: The test scenario to run enum: - protect_approved - protect_sca_recommended_challenge - protect_sca_recommended_authenticated - protect_sca_recommended_not_authenticated - protect_declined default: protect_approved fraud_token: type: string description: Forter fraud token. Emitted when running a fraud lifecycle from [the Spreedly iFrame](https://developer.spreedly.com/docs/iframe-api-lifecycle). Required for web transactions only. forter_mobile_uid: type: string description: Mobile UID. The device identifier such as IMEI in android or identifier for vendor in iOS. This should match the deviceId sent via the mobile events API. Required for mobile transactions only. user_agent: type: string description: Customer's User agent cart_items: type: array description: A list of all items purchased and shipping details items: type: object properties: name: type: string description: Item name maxLength: 500 quantity: type: number description: Item quantity type: type: string description: TANGIBLE if physical item, NON_TANGIBLE if any other product enum: - TANGIBLE - NON_TANGIBLE default: TANGIBLE price: type: string description: Final amount due for purchase, after all discounts and promotions required: - name - quantity - type - price delivery_type: type: string description: 'Type of delivery: PHYSICAL for any type of shipped goods, DIGITAL for non-shipped goods (services, gift cards etc.)' enum: - PHYSICAL - DIGITAL default: PHYSICAL delivery_method: type: string description: Delivery method chosen by customer such as postal service, email, in game transfer, etc. maxLength: 50 customer_account_id: type: string description: Customer's account UID in merchant's site (leave empty if guest) customer_account_type: type: string description: Customer account type enum: - GUEST - PRIVATE - BUSINESS - VIP - MERCHANT_OPERATED - TRIAL - MERCHANT_EMPLOYEE - PREMIUM_PAID - SMALL_BUSINESS - AGENT - BUSINESS_PRIVATE - BUSINESS_PREMIUM_PAID default: BUSINESS customer_account_creation_date: type: number description: Customer account creation date in seconds since unix epoch (UTC, Jan 1, 1970) billing_name: type: string description: The customer full name. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_first_name: type: string description: The customer first name. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_last_name: type: string description: The customer last name. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. email: type: string description: The customer email address. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_country: type: string description: The customer billing country. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_address1: type: string description: The customer billing address line 1. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_address2: type: string description: The customer billing address line 2. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_city: type: string description: The customer billing city. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_zip: type: string description: The customer billing zip code. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_state: type: string description: The customer billing state. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. billing_phone_number: type: string description: The customer billing phone number. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_name: type: string description: The customer's full name for shipping. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_first_name: type: string description: The customer's first name for shipping. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_last_name: type: string description: The customer's last name for shipping. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_email: type: string description: The customer's email address for shipping. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_country: type: string description: The customer shipping country. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_address1: type: string description: The customer shipping address line 1. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_address2: type: string description: The customer shipping address line 2. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_city: type: string description: The customer shipping city. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_zip: type: string description: The customer shipping zip code. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_state: type: string description: The customer shipping state. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. shipping_phone_number: type: string description: The customer shipping phone number. If available, this value will be pulled from the payment_method associated with this transaction. Otherwise, it should be provided here. required: - delivery_method - delivery_type - cart_items provision_network_token: type: boolean description: '`true` if this transaction should attempt to provision a network token. `false` or omit this element to not provision a network token for this transaction. Please see our [network tokenization guide](https://developer.spreedly.com/docs/network-tokenization#provisioning-network-tokens) for more details.' recover_params: type: object description: When attempting Recover, the following parameters may be used. For more information on Recover, see [the guide](https://developer.spreedly.com/docs/recover). properties: gateway_tokens: type: array description: List of all Recover gateway tokens on which a failed transaction could be attempted. items: type: string mode: type: string description: The Recover mode to use, either `standard` or `outage_only`. Default is `standard`. custom_errors: type: object description: Field to use custom error codes when using Recover. See [the guide](https://developer.spreedly.com/docs/recover#how-to-use-custom-error-codes) for more information. properties: error_codes: type: array description: List of custom error codes to use instead of/in addition to Spreedly designated codes. items: type: string messages: type: array description: List of custom error messages to use instead of/in addition to Spreedly designated codes. items: type: string additional_data: type: array description: List of custom additional data to use instead of/in addition to Spreedly designated codes. items: type: string override_default_error_codes: type: boolean description: '`true` to use the customer errors instead of, or `false` to use in addition to, Spreedly''s default error configuration. Default is `true`.' required: - gateway_tokens credit_card: type: object description: Credit card element properties: first_name: type: string description: The first name of the cardholder last_name: type: string description: The last name of the cardholder full_name: type: string description: The full name of the cardholder. If provided, `full_name` will be parsed to determine `first_name` and `last_name`. If “full_name” is entered with only a single name, “first_name” will be populated with “Not Provided” and “last_name” will be populated with the provided name. number: type: string description: The full card number verification_value: type: string description: The verification value (CVV/CVC) of the card month: type: string description: The expiration month of the card year: type: string description: The 4 digit expiration year of the card company: type: string description: The company name associated with the credit card address1: type: string description: The first line of the billing address address2: type: string description: The second line of the billing address city: type: string description: The city of the billing address state: type: string description: The state of the billing address zip: type: string description: The zip code of the billing address country: type: string description: The country code of the billing address phone_number: type: string description: The phone number of the billing address shipping_address1: type: string description: The first line of the shipping address shipping_address2: type: string description: The second line of the shipping address shipping_city: type: string description: The city of the shipping address shipping_state: type: string description: The state of the shipping address shipping_zip: type: string description: The zip code of the shipping address shipping_country: type: string description: The country code of the shipping address shipping_phone_number: type: string description: The phone number of the shipping address required: - number - month - year - first_name - last_name parameters: gateway_token: name: gateway_token description: The token of the gateway to execute against in: path required: true schema: type: string securitySchemes: basic_auth: type: http scheme: basic description: "Unless otherwise noted, all calls to the Spreedly API use [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) over HTTPS.\n Use the [environment key](https://developer.spreedly.com/docs/the-spreedly-app#environment-key) of the Spreedly environment you wish to execute against as the HTTP basic user, and one of your organization's [access secrets](https://developer.spreedly.com/docs/the-spreedly-app#access-secrets) as the HTTP basic password." x-explorer-enabled: false