---
title: "Verify a payment method"
method: POST
path: "/gateways/{gateway_token}/verify"
tags: ["verify"]
---

# Verify a payment method

`POST /gateways/{gateway_token}/verify`

Determine if a credit card is a [chargeable card and available for purchases](https://developer.spreedly.com/docs/using-payment-methods#verifying-a-card). The `retain_on_success` request parameter will automatically retain the card if it’s successfully verified.

Also used by Ebanx Gateway customers as part of the enrollment process for Mercado Pago recurring payments. To learn more about this visit [Ebanx Gateway](https://developer.spreedly.com/docs/ebanx-gateway-guide).

## Path parameters

- `gateway_token` string, required

## Request body

- Verify
  - `transaction` object
    - `payment_method_token` string, required — The token of the payment method to verify
    - `attempt_network_token` boolean — `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` boolean — `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.
    - `retain_on_success` boolean — If the card is verified, retain it so it can be used for future transactions
    - `currency_code` string — 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.
    - `ip` string — If the gateway requires an allowed IP address
    - `sub_merchant_key` string — 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_authentication_token` string — The token received in response body of SCA Authenticate endpoints 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)
    - `sca_provider_key` string — [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` string — 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.
    - `gateway_specific_fields` object — 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.
    - `protection_provider_key` string — The token of the [Protection Provider](https://developer.spreedly.com/reference/create-protection-provider). Triggers a protection check.
    - `protection_parameters` ProtectionParameters — 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.
      - `test_scenario` object — The protection test scenario
        - `scenario` 'protect_approved' | 'protect_sca_recommended_challenge' | 'protect_sca_recommended_authenticated' | 'protect_sca_recommended_not_authenticated' | 'protect_declined' — The test scenario to run
      - `fraud_token` string — 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` string — 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` string — Customer's User agent
      - `cart_items` object[], required — A list of all items purchased and shipping details
        - `name` string, required — Item name
        - `quantity` number, required — Item quantity
        - `type` 'TANGIBLE' | 'NON_TANGIBLE', required — TANGIBLE if physical item, NON_TANGIBLE if any other product
        - `price` string, required — Final amount due for purchase, after all discounts and promotions
      - `delivery_type` 'PHYSICAL' | 'DIGITAL', required — Type of delivery: PHYSICAL for any type of shipped goods, DIGITAL for non-shipped goods (services, gift cards etc.)
      - `delivery_method` string, required — Delivery method chosen by customer such as postal service, email, in game transfer, etc.
      - `customer_account_id` string — Customer's account UID in merchant's site (leave empty if guest)
      - `customer_account_type` 'GUEST' | 'PRIVATE' | 'BUSINESS' | 'VIP' | 'MERCHANT_OPERATED' | 'TRIAL' | 'MERCHANT_EMPLOYEE' | 'PREMIUM_PAID' | 'SMALL_BUSINESS' | 'AGENT' | 'BUSINESS_PRIVATE' | 'BUSINESS_PREMIUM_PAID' — Customer account type
      - `customer_account_creation_date` number — Customer account creation date in seconds since unix epoch (UTC, Jan 1, 1970)
      - `billing_name` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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.

## Response `200`

OK

- VerifyResponse
  - `transaction` object
    - `on_test_gateway` string — `true` if the transaction took place on a test gateway
    - `created_at` string — The time the purchase token was created
    - `updated_at` string — The time the purchase token was last updated
    - `succeeded` boolean — `true` if the transaction request was successfully executed, `false` otherwise
    - `state` string — The current state of the transaction
    - `token` string — The token uniquely identifying this transaction at Spreedly
    - `transaction_type` string — The type of transaction, e.g., Authorization, Capture, Credit
    - `order_id` string — The merchant specified order id. If not provided, the Spreedly transaction token will be used.
    - `ip` string — 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".
    - `sub_merchant_key` string — The token of the sub-merchant associated with the transaction.
    - `description` string — A human readable description of the transaction which will be passed to the gateway if it's supported
    - `email` string — Override the customer email address associated with the payment method for this transaction
    - `merchant_name_descriptor` string — A human readable description of the merchant
    - `merchant_location_descriptor` string — A human readable description of the merchant location
    - `gateway_specific_fields` string[] — The list of gateway specific fields that can be specified in supported gateway transactions
    - `gateway_specific_response_fields` object — A hash containing unique optional fields that a gateway may return based on certain customized options.
    - `gateway_transaction_id` string — The id of the transaction *at the gateway*. To be used when corresponding with the gateway or reconciling transactions
    - `gateway_latency_ms` string — The time it took the gateway to respond to Spreedly
    - `currency_code` string — 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.
    - `retain_on_success` boolean — 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` string — 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
    - `message_key` string — A machine-parseable string indicating the result of the transaction
    - `message` string — A human-readable string indicating the result of the transaction
    - `gateway_token` string — The token of the gateway to executed against
    - `gateway_type` string — The type (short name) of the gateway
    - `response` object — 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
    - `shipping_address` object — Override the customer shipping address associated with the payment method for this transaction
    - `payment_method` PaymentMethod
      - `token` string — The token identifying the payment method in the Spreedly vault
      - `created_at` string — The time the payment method token was created
      - `updated_at` string — The time the payment method token was last updated
      - `email` string — The email address of the customer associated with this credit card
      - `storage_state` string — The `storage_state` (retained, redacted, cached, used) of the payment method
      - `test` boolean — `true` if this payment method is a test payment method and cannot be used against real gateways or receivers
      - `metadata` object — 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` string — 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` string — The last four digits of the credit card number. This can be displayed to the user.
      - `first_six_digits` string — The first six digits of the credit card number. This can be displayed to the user.
      - `card_type` string — 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` string — The first name of the cardholder
      - `last_name` string — The last name of the cardholder
      - `month` string — The expiration month
      - `year` string — The expiration year
      - `address1` string — The first line of the billing address
      - `address2` string — The second line of the billing address
      - `city` string — The city of the billing address
      - `state` string — The state of the billing address
      - `zip` string — The zip code of the billing address
      - `country` string — The country code of the billing address
      - `phone_number` string — The phone number of the billing address
      - `company` string — The company of the cardholder
      - `full_name` string — The full name of the cardholder.
      - `eligible_for_card_updater` string — `true` if this payment method should be included in Account Updater
      - `shipping_address1` string — The first line of the shipping address
      - `shipping_address2` string — The second line of the shipping address
      - `shipping_city` string — The city of the shipping address
      - `shipping_state` string — The state of the shipping address
      - `shipping_zip` string — The zip code of the shipping address
      - `shipping_country` string — The country code of the shipping address
      - `issuer_identification_number` string — The numbers of the PAN required to identify the card issuer.
      - `click_to_pay` string — `true` if the card was tokenized using Click to Pay
      - `managed` string — The value indicating the payment method's management status.
      - `payment_method_type` string — The type of this payment method, e.g., `credit_card`, `bank_account`, `apple_pay`, `google_pay`, `third_party_token`, etc…
      - `errors` string — If the payment method is invalid (missing required fields, etc…), there will be associated error messages here
      - `fingerprint` string — An identifying string that will match all cards in the environment with the same PAN
      - `verification_value` string — The obscured verification value (CVV), e.g., XXX or XXXX
      - `number` string — The obscured credit card number, e.g., XXXX-XXXX-XXXX-4444
      - `bin_metadata` object — 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.
        - `card_brand` string
        - `card_category` string
        - `card_type` string
        - `issuing_bank` string
        - `issuing_country_iso_number` string
        - `issuing_country_iso_a2_code` string
        - `issuing_country_iso_a3_code` string
        - `issuing_country_iso_name` string
        - `issuing_bank_phone_number` string
        - `issuing_bank_website` string
        - `bin_type` string
        - `regulated` string
        - `max_pan_length` string
        - `message` string
      - `subscribed_to_mastercard_abu` boolean — `true` if this payment method is subscribed to Mastercard ABU updating service
      - `last_successfully_used` string, date-time, nullable — The time (UTC) the payment method was last successfully transacted with. The following transaction types are considered: Authorization, Purchase, Verification, GeneralCredit, OffsiteVerification, or OffsitePurchase
    - `protection_provider_key` string — The token of the Protection Provider that was used for this transaction.
    - `protection_parameters` ProtectionParameters — 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.
      - `test_scenario` object — The protection test scenario
        - `scenario` 'protect_approved' | 'protect_sca_recommended_challenge' | 'protect_sca_recommended_authenticated' | 'protect_sca_recommended_not_authenticated' | 'protect_declined' — The test scenario to run
      - `fraud_token` string — 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` string — 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` string — Customer's User agent
      - `cart_items` object[], required — A list of all items purchased and shipping details
        - `name` string, required — Item name
        - `quantity` number, required — Item quantity
        - `type` 'TANGIBLE' | 'NON_TANGIBLE', required — TANGIBLE if physical item, NON_TANGIBLE if any other product
        - `price` string, required — Final amount due for purchase, after all discounts and promotions
      - `delivery_type` 'PHYSICAL' | 'DIGITAL', required — Type of delivery: PHYSICAL for any type of shipped goods, DIGITAL for non-shipped goods (services, gift cards etc.)
      - `delivery_method` string, required — Delivery method chosen by customer such as postal service, email, in game transfer, etc.
      - `customer_account_id` string — Customer's account UID in merchant's site (leave empty if guest)
      - `customer_account_type` 'GUEST' | 'PRIVATE' | 'BUSINESS' | 'VIP' | 'MERCHANT_OPERATED' | 'TRIAL' | 'MERCHANT_EMPLOYEE' | 'PREMIUM_PAID' | 'SMALL_BUSINESS' | 'AGENT' | 'BUSINESS_PRIVATE' | 'BUSINESS_PREMIUM_PAID' — Customer account type
      - `customer_account_creation_date` number — Customer account creation date in seconds since unix epoch (UTC, Jan 1, 1970)
      - `billing_name` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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` string — 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.
    - `protect_fraud_check` ProtectFraudCheckResponse — 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).
      - `updated_at` string — The time the fraud check was last updated
      - `created_at` string — The time the fraud check was created
      - `protection_provider_key` string — The token of the Protection Provider used for this check
      - `succeeded` boolean — Whether the fraud check request was successfully executed
      - `state` string — The current state of the fraud check
      - `token` string — The token uniquely identifying this fraud check at Spreedly
      - `message` string — A human-readable message describing the result (if applicable)
      - `amount` number — The transaction amount checked
      - `currency_code` string — The currency of the funds in ISO format (e.g., USD)
      - `ip` string — The IP address associated with the transaction
      - `email` string — The email address associated with the transaction
      - `transaction_type` string — The type of transaction
      - `gateway_transaction_key` string — The Spreedly transaction token of the parent gateway transaction
      - `callback_url` string — The URL where Spreedly will attempt delivery of asynchronous results (if provided)
      - `test_scenario` string — The test scenario used
      - `acquiring_bank_fraud_rate` string — The threshold for bank fraud rate used for exemption requests
      - `exemption_type` string — The type of exemption requested (if applicable)
      - `warning` string — Any warning messages from the fraud check
      - `managed_order_token` string — The token of the fraud check returned by the fraud check provider
      - `fraud_decision` string — The fraud decision outcome (e.g., approve, decline, review)
      - `fraud_recommendation` string — Additional recommendation information from the fraud provider
      - `fraud_decision_reason` string — Reason for the fraud decision
      - `vendor_response` object — Detailed response from the fraud protection vendor
        - `forterDecision` string — The decision returned by Forter
        - `recommendation` string — Recommended action from the vendor
        - `verificationMethod` object — Methods used to verify the transaction
        - `decisionReason` string — Reason for the vendor's decision
        - `merchantPolicyId` string — Merchant policy identifier used to make the decision
        - `orderId` string — Order identifier in the vendor's system
        - `linkToEventInDashboard` string — URL to view the transaction details in the vendor's dashboard
    - `network_tokenization` NetworkTokenization — The network tokenization details for the transaction
      - `provisioned` boolean — Indicates if the network tokenization was successfully provisioned
      - `token_status` string — The status of the network token
      - `token_reference` string — The unique reference key for the network token
      - `token_first_six_digits` string — The first six digits of the network token's DPAN
      - `token_last_four_digits` string — The last four digits of the network token's DPAN
      - `token_created_at` string — The timestamp when the network token was created
      - `token_updated_at` string — The timestamp when the network token was last updated
      - `attempted` boolean — Indicates if the transaction attempted to use a network token
      - `errors` object[] — An array of errors that occurred during the network tokenization process
        - `key` string — The error key
        - `message` string — The error message
        - `action` string — The action taken which lead to the error

## Other responses

- `401` — Unauthorized
- `404` — Not Found
- `422` — Unprocessable Entity

---

[API](https://skmtc.dev/spreedly/apis/spreedly-api-v1.md) · [All operations](https://skmtc.dev/spreedly/apis/spreedly-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/spreedly/spreedly-api-v1/revisions/72ba4e23e65c/schema)