Spreedly Composer API

openapi: 3.2.0
info:
  title: Spreedly API V1 Composer 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: composer
paths:
  /transactions/authorize:
    post:
      summary: Create an authorization with workflows
      tags:
      - composer
      security:
      - basic_auth: []
      operationId: composer.authorize
      description: '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.


        Pass a credit card payment method directly into the authorize request. If the card is valid, it will automatically be tokenized at Spreedly before sending to the gateway. No funds are taken with an authorize - a follow-up capture transaction is required to actually move the funds.


        **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 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 in to 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:** 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.

        '
      parameters: []
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/purchase_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/purchase_response'
        '401':
          description: Unauthorized
          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/purchase'
            examples:
              Payment method token:
                summary: Payment method token
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    workflow_key: ''
                    currency_code: USD
              Pass in credit card:
                summary: Pass in credit card
                value:
                  transaction:
                    amount: 100
                    currency_code: USD
                    workflow_key: ''
                    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
                    workflow_key: ''
                    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
                    workflow_key: ''
                    google_pay:
                      payment_data:
                        signature: ''
                        protocolVersion: ''
                        signedMessage: '{}'
                      test_card_number: '4111111111111111'
              SCA Authenticated:
                summary: SCA Authenticated
                value:
                  transaction:
                    sca_authentication_token: ''
                    amount: 1122
                    currency_code: USD
                    workflow_key: ''
              Default workflow:
                summary: Default workflow
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    currency_code: USD
          application/xml:
            schema:
              $ref: '#/components/schemas/purchase'
            examples:
              Payment method token:
                summary: Payment method token
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    workflow_key: ''
                    currency_code: USD
              Pass in credit card:
                summary: Pass in credit card
                value:
                  transaction:
                    amount: 100
                    currency_code: USD
                    workflow_key: ''
                    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
                    workflow_key: ''
                    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
                    workflow_key: ''
                    google_pay:
                      payment_data:
                        signature: ''
                        protocolVersion: ''
                        signedMessage: '{}'
                      test_card_number: '4111111111111111'
              SCA Authenticated:
                summary: SCA Authenticated
                value:
                  transaction:
                    sca_authentication_token: ''
                    amount: 1122
                    currency_code: USD
                    workflow_key: ''
              Default workflow:
                summary: Default workflow
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    currency_code: USD
  /transactions/purchase:
    post:
      summary: Create a purchase with workflows
      tags:
      - composer
      security:
      - basic_auth: []
      operationId: composer.purchase
      description: '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.


        Charge a payment method a specific amount at the target gateway. One of the following payment methods must be included in the request:


        **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 purchase 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 in to the purchase 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 purchase 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:** 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.

        '
      parameters: []
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/purchase_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/purchase_response'
        '401':
          description: Unauthorized
          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/purchase'
            examples:
              Payment method token:
                summary: Payment method token
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    workflow_key: ''
                    currency_code: USD
              Pass in credit card:
                summary: Pass in credit card
                value:
                  transaction:
                    amount: 100
                    currency_code: USD
                    workflow_key: ''
                    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
                    workflow_key: ''
                    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
                    workflow_key: ''
                    google_pay:
                      payment_data:
                        signature: ''
                        protocolVersion: ''
                        signedMessage: '{}'
                      test_card_number: '4111111111111111'
              SCA Authenticated:
                summary: SCA Authenticated
                value:
                  transaction:
                    sca_authentication_token: ''
                    amount: 1122
                    currency_code: USD
                    workflow_key: ''
              Default workflow:
                summary: Default workflow
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    currency_code: USD
          application/xml:
            schema:
              $ref: '#/components/schemas/purchase'
            examples:
              Payment method token:
                summary: Payment method token
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    workflow_key: ''
                    currency_code: USD
              Pass in credit card:
                summary: Pass in credit card
                value:
                  transaction:
                    amount: 100
                    currency_code: USD
                    workflow_key: ''
                    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
                    workflow_key: ''
                    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
                    workflow_key: ''
                    google_pay:
                      payment_data:
                        signature: ''
                        protocolVersion: ''
                        signedMessage: '{}'
                      test_card_number: '4111111111111111'
              SCA Authenticated:
                summary: SCA Authenticated
                value:
                  transaction:
                    sca_authentication_token: ''
                    amount: 1122
                    currency_code: USD
                    workflow_key: ''
              Default workflow:
                summary: Default workflow
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    currency_code: USD
  /transactions/verify:
    post:
      summary: Create a verify with workflows
      tags:
      - composer
      security:
      - basic_auth: []
      operationId: composer.verify
      description: '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.

        '
      parameters: []
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verify_composer_response'
            application/xml:
              schema:
                $ref: '#/components/schemas/verify_composer_response'
        '401':
          description: Unauthorized
          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/verify_composer'
            examples:
              Payment method token:
                summary: Payment method token
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    workflow_key: ''
                    currency_code: USD
              Pass in credit card:
                summary: Pass in credit card
                value:
                  transaction:
                    amount: 100
                    currency_code: USD
                    workflow_key: ''
                    credit_card:
                      first_name: Joe
                      last_name: Smith
                      number: 4111111111111111
                      verification_value: 123
                      month: 12
                      year: 2030
              SCA Authenticated:
                summary: SCA Authenticated
                value:
                  transaction:
                    sca_authentication_token: ''
                    amount: 1122
                    currency_code: USD
                    workflow_key: ''
              Default workflow:
                summary: Default workflow
                value:
                  transaction:
                    payment_method_token: ''
                    retain_on_success: true
          application/xml:
            schema:
              $ref: '#/components/schemas/verify_composer'
            examples:
              Payment method token:
                summary: Payment method token
                value:
                  transaction:
                    payment_method_token: ''
                    amount: 100
                    workflow_key: ''
                    currency_code: USD
              Pass in credit card:
                summary: Pass in credit card
                value:
                  transaction:
                    amount: 100
                    currency_code: USD
                    workflow_key: ''
                    credit_card:
                      first_name: Joe
                      last_name: Smith
                      number: 4111111111111111
                      verification_value: 123
                      month: 12
                      year: 2030
              SCA Authenticated:
                summary: SCA Authenticated
                value:
                  transaction:
                    sca_authentication_token: ''
                    amount: 1122
                    currency_code: USD
                    workflow_key: ''
              Default workflow:
                summary: Default workflow
                value:
                  transaction:
                    payment_method_token: ''
                    retain_on_success: true
components:
  schemas:
    purchase_request:
      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: string
          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".
        browser_info:
          type: string
          description: 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:
          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/spreedly-3ds2-global-guide) 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/spreedly-3ds2-global-guide) to learn more.
          properties:
            three_ds_requestor_challenge_ind:
              type: string
              description: Indicates whether a challenge is being requested for a 3DS2 Global transaction.
            test_scenario:
              type: boolean
              description: '`true` if this is a test scenario'
            exemption_type:
              type: array
              description: 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
            acquiring_bank_fraud_rate:
              type: string
              description: 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:
          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
          description: Override the customer shipping address associated with the payment method for this transaction
          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
          description: '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.'
          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
        ignore_failed_authentication_result:
          type: string
          description: Complete 3DS2 Global transaction when authentication fails.
        workflow_key:
          type: string
          description: 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:
          type: object
          description: 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:
          type: object
          description: 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:
          type: object
          description: 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:
          type: object
          description: 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:
          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 

# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spreedly/refs/heads/main/openapi/spreedly-composer-api-openapi.yml