---
title: "Create a verify with workflows"
method: POST
path: "/transactions/verify"
tags: ["composer"]
---

# Create a verify with workflows

`POST /transactions/verify`

Spreedly's workflow service will determine which gateway the transaction will be processed based on the workflow evoked and send normalized fields depending on what the gateway supports. A `workflow_key` should be sent in the request body or left as null to evoke the Default Workflow set in your Spreedly environment.

To learn more about how to enable workflows, please contact Spreedly at support@spreedly.com.

Determine if a credit card is chargeable card and available for purchases. The `retain_on_success` request parameter will automatically retain the card if it’s successfully verified.

**Tokenized payment method:** Charge a _tokenized_ payment method (already stored in the Spreedly environment) the specified amount. The payment method can be of any type (credit card, bank account, Apple Pay, etc…), as long as it exists in the specified environment.

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 verify 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.

**SCA Authenticated:** Charge an SCA Authenticated payment method (already stored in the Spreedly environment) the specified amount.

The `sca_authentication_token` field of the transaction request is required.

**Default workflow:** Use the default workflow for the environment that is set in app.spreedly.com

The `workflow_key` field is not required to be passed in for this type of request.

## Request body

- VerifyComposer
  - `transaction` object — Root request element
    - `order_id` string — The merchant specified order id. If not provided, the Spreedly transaction token will be used.
    - `description` string — A human readable description of the transaction which will be passed to the gateway if it's supported
    - `retain_on_success` string — If the card is verified, retain it so it can be used for future transactions
    - `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".
    - `browser_info` string — Please refer to our [Spreedly 3DS2 Global Integration Guide for Web](https://developer.spreedly.com/docs/3ds2-global-integration-guide-web), to learn how to include our `Lifecycle.js` library and gather the browser info data using `Spreedly.ThreeDS.serialize` method.
    - `email` string — Override the customer email address associated with the payment method for this transaction
    - `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.
    - `stored_credential_initiator` string — Who is initiating this request, `merchant` or `cardholder`
    - `stored_credential_reason_type` string — What kind of transaction is the payment method being used for. e.g. `recurring`, `unscheduled`, or `installment`
    - `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_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/spreedly-3ds2-global-guide) for more info.
    - `sca_authentication_parameters` object — 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/spreedly-3ds2-global-guide) to learn more.
      - `three_ds_requestor_challenge_ind` string — Indicates whether a challenge is being requested for a 3DS2 Global transaction.
      - `test_scenario` boolean — `true` if this is a test scenario
      - `exemption_type` unknown[] — Type of exemption request to reduce likelihood of a transaction being challenged. The two exemptions currently supported are `low_value_exemption` and `transaction_risk_analysis_exemption`. See our [exemption guide](https://developer.spreedly.com/docs/spreedly-3ds2-global-guide#requesting-exemptions) to learn more
        - unknown
      - `acquiring_bank_fraud_rate` string — Additional field required if requesting a `transaction_risk_analysis_exemption` that details threshold for bank fraud rate. See our [exemption guide](https://developer.spreedly.com/docs/spreedly-3ds2-global-guide#requesting-exemptions) to learn more
    - `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`)
    - `callback_format` string — 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` object — Override the customer shipping address associated with the payment method for this transaction
      - `name` string — Customer's name in the shipping address
      - `address1` string — Customer's shipping address, line 1
      - `address2` string — Customer's shipping address, line 2
      - `city` string — Customer's shipping city
      - `state` string — Customer's shipping state/province
      - `zip` string — Customer's shipping zip
      - `country` string — Customer's shipping country
      - `phone_number` string — Customer's shipping phone
    - `billing_address` object — Override the customer billing address associated with the payment method for this transaction. To send a nil value, the respective parameter(s) must be set to "omit". Note: Any values that you do not override will be set based on the existing value on the payment method.
      - `name` string — Customer's name in the billing address
      - `address1` string — Customer's billing address, line 1
      - `address2` string — Customer's billing address, line 2
      - `city` string — Customer's billing city
      - `state` string — Customer's billing state/province
      - `zip` string — Customer's billing zip
      - `country` string — Customer's billing country
      - `phone_number` string — Customer's billing phone
    - `ignore_failed_authentication_result` string — Complete 3DS2 Global transaction when authentication fails.
    - `workflow_key` string — The key of the Spreedly workflow to use for this transaction. Spreedly will use the environment's default workflow_key if no value is provided. Only available via composer on the /transactions resource.
    - `order_data` object — Optional fields related to the order that are to be passed to the gateway if the gateway supports it. Please see our [normalized request guide](https://developer.spreedly.com/docs/normalized-request-and-response-fields) for more info. Only available via composer on the /transactions resource.
    - `customer_data` object — Optional fields related to the cardholder that are to be passed to the gateway if the gateway supports it. Please see our [normalized request guide](https://developer.spreedly.com/docs/normalized-request-and-response-fields) for more info. Only available via composer on the /transactions resource.
    - `risk_data` object — Optional fields related to risk data that are to be passed to the gateway if the gateway supports it. Please see our [normalized request guide](https://developer.spreedly.com/docs/normalized-request-and-response-fields) for more info. Only available via composer on the /transactions resource.
    - `merchant_metadata` object — Optional fields related to the merchant that are to be passed to the gateway if the gateway supports it. Please see our [normalized request guide](https://developer.spreedly.com/docs/normalized-request-and-response-fields) for more info. Only available via composer on the /transactions resource.
    - `payment_method_token` string — The token of the payment method to use
    - `credit_card` CreditCard — Credit card element
      - `first_name` string, required — The first name of the cardholder
      - `last_name` string, required — The last name of the cardholder
      - `full_name` string — 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` string, required — The full card number
      - `verification_value` string — The verification value (CVV/CVC) of the card
      - `month` string, required — The expiration month of the card
      - `year` string, required — The 4 digit expiration year of the card
      - `company` string — The company name associated with the credit card
      - `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
      - `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
      - `shipping_phone_number` string — The phone number of the shipping address
    - `bank_account` BankAccount
      - `first_name` string, required — The first name of the account owner
      - `last_name` string, required — The last name of the account owner
      - `bank_routing_number` string, required — The account routing number
      - `bank_account_number` string, required — The account number
      - `bank_account_type` 'checking' | 'savings' — The type of account. Can be one of `checking` or `savings`.
      - `bank_account_holder_type` 'business' | 'personal' — The account holder type. Can be one `business` or `personal`.
      - `full_name` string — The full name of the account owner. If provided, will be parsed to determine first_name and last_name. Note: optional: either full_name or both first_name and last_name are required
    - `apple_pay` ApplePay
      - `payment_data` object, required — 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)
        - `version` unknown
        - `data` unknown
        - `signature` unknown
        - `header` object
          - `ephemeralPublicKey` unknown
          - `transactionId` unknown
          - `publicKeyHash` unknown
      - `test_card_number` unknown
    - `google_pay` GooglePay
      - `payment_data` object, required — The JSON serialized [paymentData](https://developers.google.com/pay/api/web/guides/resources/payment-data-cryptography#payment-method-token-structure)
        - `signature` string — Verifies that the message came from Google. Base64-encoded. Created using ECDSA.
        - `protocolVersion` string — 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` string — A serialized JSON string containing the `encryptedMessage`, `ephemeralPublicKey` and `tag`. Serialized to simplify the signature verification process.
      - `test_card_number` string — 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` string — The first name of the cardholder
      - `last_name` string — The last name of the cardholder
      - `address_1` string — Cardholder's address, line 1
      - `address_2` string — Cardholder's address, line 2
      - `city` string — Cardholder's city
      - `state` string — Cardholder's state
      - `zip` string — Cardholder's zip
      - `country` string — Cardholder's country
    - `sca_authentication_token` string — 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)

## Response `200`

Created

- VerifyComposerResponse
  - `transaction` VerifyParameters — Root element
    - `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".
    - `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
    - `merchant_profile_key` string — The token of the Merchant Profile associated with the gateway used for the transaction
    - `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
    - `sub_merchant_key` string — The token of the sub-merchant associated with the transaction.
    - `gateway_latency_ms` string — The time it took the gateway to respond to Spreedly
    - `warning` string — Provides a human readable warning message if passed back by the gateway
    - `application_id` string — Customer provided application_id
    - `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
    - `stored_credential_initiator` string — Who is initiating this request, `merchant` or `cardholder`
    - `stored_credential_reason_type` string — What kind of transaction is the payment method being used for. e.g. `recurring`, `unscheduled`, or `installment`
    - `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
    - `attempt_3dsecure` string — `true` if 3dsecure transaction was attempted
    - `payment_method` object — The payment method used in this transaction
    - `workflow_key` string — The key of the Spreedly workflow to use for this transaction. Spreedly will use the environment's default workflow_key if no value is provided. Only available via composer on the /transactions resource.
    - `order_data` object — Optional fields related to the order that are to be passed to the gateway if the gateway supports it. Please see our [normalized request guide](https://developer.spreedly.com/docs/normalized-request-and-response-fields) for more info. Only available via composer on the /transactions resource.
    - `customer_data` object — Optional fields related to the cardholder that are to be passed to the gateway if the gateway supports it. Please see our [normalized request guide](https://developer.spreedly.com/docs/normalized-request-and-response-fields) for more info. Only available via composer on the /transactions resource.
    - `risk_data` object — Optional fields related to risk data that are to be passed to the gateway if the gateway supports it. Please see our [normalized request guide](https://developer.spreedly.com/docs/normalized-request-and-response-fields) for more info. Only available via composer on the /transactions resource.
    - `merchant_metadata` object — Optional fields related to the merchant that are to be passed to the gateway if the gateway supports it. Please see our [normalized request guide](https://developer.spreedly.com/docs/normalized-request-and-response-fields) for more info. Only available via composer on the /transactions resource.
    - `gateway_response` object — A hash containing normalized fields from various gateways. Please see our [normalized response field documentation](https://developer.spreedly.com/docs/normalized-request-and-response-fields#response-fields) for more info. Only available via composer on the /transactions resource.
    - `pan_retry` boolean — `true` if the transaction is a retry that uses PAN after a failed attempt with a network token. Only available via composer on the /transactions resource.
    - `payment_snapshot` PaymentSnapshot — 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).
      - `gateway_tokens` string[] — List of all gateway tokens on which the transaction could be attempted. Includes the primary gateway token and all Recover gateway tokens.
      - `attempts` integer — Number of times the transaction has been attempted.
      - `messages` object — 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` string — The Recover mode used, either `standard` or `outage_only`.
      - `custom_error_used` boolean — `true` if the transaction used a custom error in the recovery decision process.
      - `override_default_error_codes` boolean — `true` if the custom error configuration was used instead of Spreedly's default error configuration.
      - `created_at` string — The time the payment_snapshot was created.
      - `updated_at` string — The time the payment_snapshot was updated.
      - `payment_token` string — The token corresponding to the Payment object, containing all information about the Recover chain.
      - `previous_transaction_tokens` string[] — List of all previous transactions associated with the Recover attempt.

## Other responses

- `401` — Unauthorized
- `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)