Checkout.com Gateway Guide

Checkout.com fact sheet

Additional notes
This Spreedly gateway was formerly referred to as “Checkout V2”. When the original Checkout.com API was deprecated, it was removed from Spreedly, and this gateway now uses that name.
When using the `purchase` transaction type via Spreedly, the intention is that an authorization (payment) occurs and will be auto-captured by Checkout. It is important to note that Checkout’s flagging risk rules may trigger payments to remain in an `authorized` state until manually reviewed by the merchant.
Merchants should work with Checkout to ensure risk rules are disabled or configured as to avoid orders not being captured before the authorization expires.
Incremental authorization and general credit is only supported in `oauth` mode.

Adding a Checkout.com gateway using default mode

You can add a Checkout.com gateway using just your secret_key like so:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>checkout_v2</gateway_type>
        <secret_key>Your secret_key</secret_key>
      </gateway>'

<gateway>
  <token>7zB6OYqdc1bCWEZXnNxskbEqjhv</token>
  <gateway_type>checkout_v2</gateway_type>
  <name>Checkout.com</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
    <supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>descriptor_city</gateway_specific_field>
    <gateway_specific_field>descriptor_name</gateway_specific_field>
    <gateway_specific_field>card_on_file</gateway_specific_field>
    <gateway_specific_field>transaction_indicator</gateway_specific_field>
    <gateway_specific_field>previous_charge_id</gateway_specific_field>
    <gateway_specific_field>attempt_n3d</gateway_specific_field>
    <gateway_specific_field>metadata</gateway_specific_field>
    <gateway_specific_field>capture_type</gateway_specific_field>
    <gateway_specific_field>authorization_type</gateway_specific_field>
    <gateway_specific_field>challenge_indicator</gateway_specific_field>
    <gateway_specific_field>exemption</gateway_specific_field>
    <gateway_specific_field>processing_channel_id</gateway_specific_field>
    <gateway_specific_field>incremental_authorization</gateway_specific_field>
    <gateway_specific_field>execute_threed</gateway_specific_field>
    <gateway_specific_field>funds_transfer_type</gateway_specific_field>
    <gateway_specific_field>account_holder_type</gateway_specific_field>
    <gateway_specific_field>source_type</gateway_specific_field>
    <gateway_specific_field>source_id</gateway_specific_field>
    <gateway_specific_field>merchant_initiated_transaction_id</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>phone_country_code</gateway_specific_field>
    <gateway_specific_field>instruction_purpose</gateway_specific_field>
    <gateway_specific_field>destination</gateway_specific_field>
    <gateway_specific_field>sender</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>google_pay</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2023-02-08T17:57:57Z</created_at>
  <updated_at type="dateTime">2023-02-08T17:57:57Z</updated_at>
</gateway>

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. For gateways not included in the Marketplace, review the steps below.

Create a gateway

Visit your Connections area to review all gateways and add new ones. When creating your gateways, select the gateway name and authentication mode (if prompted) before completing required fields. Select ☑️Sandbox to create a gateway in Sandbox mode, for processing test card data and transactions in your Spreedly environment.

Supply your secret_key to create a Checkout.com gateway in Default mode. Public key is optional.

Adding a Checkout.com gateway using oauth mode

You can add a Checkout.com gateway using your full credentials, client_id and client_secret.

client_id and client_secret correspond to the Access Key Identifier and the Access Key Secret. For more information see managing API Keys for Oauth in Checkout’s documentation.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>checkout_v2</gateway_type>
        <mode>oauth</mode>
        <client_id>your_client_id</client_id>
        <client_secret>your_client_secret</client_secret>
      </gateway>'

<gateway>
  <token>2jwxeyikytIv1FM1zi4yxc6hCv2</token>
  <gateway_type>checkout_v2</gateway_type>
  <name>Checkout.com</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">false</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
    <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
    <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_3dsecure_purchase type="boolean">true</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
    <supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>descriptor_city</gateway_specific_field>
    <gateway_specific_field>descriptor_name</gateway_specific_field>
    <gateway_specific_field>card_on_file</gateway_specific_field>
    <gateway_specific_field>transaction_indicator</gateway_specific_field>
    <gateway_specific_field>previous_charge_id</gateway_specific_field>
    <gateway_specific_field>attempt_n3d</gateway_specific_field>
    <gateway_specific_field>metadata</gateway_specific_field>
    <gateway_specific_field>capture_type</gateway_specific_field>
    <gateway_specific_field>authorization_type</gateway_specific_field>
    <gateway_specific_field>challenge_indicator</gateway_specific_field>
    <gateway_specific_field>exemption</gateway_specific_field>
    <gateway_specific_field>processing_channel_id</gateway_specific_field>
    <gateway_specific_field>incremental_authorization</gateway_specific_field>
    <gateway_specific_field>execute_threed</gateway_specific_field>
    <gateway_specific_field>funds_transfer_type</gateway_specific_field>
    <gateway_specific_field>account_holder_type</gateway_specific_field>
    <gateway_specific_field>source_type</gateway_specific_field>
    <gateway_specific_field>source_id</gateway_specific_field>
    <gateway_specific_field>merchant_initiated_transaction_id</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>phone_country_code</gateway_specific_field>
    <gateway_specific_field>instruction_purpose</gateway_specific_field>
    <gateway_specific_field>destination</gateway_specific_field>
    <gateway_specific_field>sender</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>google_pay</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>oauth</mode>
  <created_at type="dateTime">2023-02-08T17:49:35Z</created_at>
  <updated_at type="dateTime">2023-02-08T17:49:35Z</updated_at>
</gateway>

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. For gateways not included in the Marketplace, review the steps below.

Create a gateway

OAuth mode requires client_id and client_secret. Theclient_id and client_secret correspond to the Access Key Identifier and the Access Key Secret. For more information see managing API Keys for Oauth in Checkout’s documentation.

Adding a Checkout.com gateway to use store

To use Third Party Vaulting via the Store operation use your secret_key and public_key credentials in the default mode. Spreedly requires the public key in order to access the Tokens Endpoint for Checkout.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>checkout_v2</gateway_type>
        <secret_key>Your secret_api_key</secret_key>
        <public_key>Your public_api_key</public_key>
      </gateway>'

The unstore (remove) is available with any authentication mode (default/oauth).

Third-party 3DS2 auth data

Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to Checkout.com. For more information about how to use this feature, see the 3DS2 third-party authentication guide. Spreedly fields map to the relevant Checkout.com fields as described in the following table. Please see Checkout.com’s documentation for detailed descriptions of each of these fields and when to use them.

Spreedly field	Checkout.com field
`three_ds_version`	`version`
`ecommerce_indicator`	`eci`
`authentication_value`	`cryptogram`
`directory_server_transaction_id`	`xid`

Stored credential regulations

For Checkout.com, sending stored credential fields can be done using Spreedly’s first class support. Sending stored crendential data is simple. For any Authorize or Purchase request, you need to include two fields which tell Spreedly a little bit more about the nature of the transaction:

stored_credential_initator
stored_credential_reason_type

Learn more about how Spreedly enables use of stored credentials by reviewing our Stored Credentials guide. Alternatively you can use GSFs to take control and manage the MIT framework yourself.

Checkout.com allows you to specify multiple fields to assist in satisfying requirements set by both Visa and Mastercard. The details on these requirements can be found on Checkout.com’s documentation site.

card_on_file: By default this field is set to true since Spreedly stores the card details before sending to Checkout.com. Specify false to override this field.
transaction_indicator: The type of transaction being authorized. This gets mapped to the payment_type field. By default this field is set to 1, a regular transaction. If the stored_credential_reason_type is either recurring or installment the transaction_indicator will be set to 2. Passing in a GSF will override any logic, 2 can be specified for recurring or 3 for MOTO.
previous_charge_id: Used to reference either the previous transaction or the opening transaction of a payment plan. The previous_charge_id is the chargeId issued after the authorization of the relevant payment. By default this field is not sent to Checkout.com.

Syncing transactions

Spreedly supports updating the status of transactions that have been initiated at the Checkout.com gateway. Checkout.com currently supports using gateway_transaction_id for updates. The gateway_transaction_id would be the payment unique identifier. See our documentation for more information.

Gateway specific fields

When interacting with a Checkout.com gateway to run transactions, there are a number of gateway specific fields you can specify. See the details below the example for more information on select fields.

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/authorize.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <gateway_specific_fields>
          <checkout_v2>
            <descriptor_name>TheName</descriptor_name>
            <descriptor_city>Wanaque</descriptor_city>
            <card_on_file>true</card_on_file>
            <transaction_indicator>1</transaction_indicator>
            <previous_charge_id>charge_12345</previous_charge_id>
            <attempt_n3d>true</attempt_n3d>
            <authorization_type>Estimated</authorization_type>
            <challenge_indicator>trusted_listing</challenge_indicator>
            <exemption>no_preference</exemption>
            <processing_channel_id>pc_ovo75iz4hdyudnx6tu74mum3fq</processing_channel_id>
            <incremental_authorization>pay_obb2wabkwzskjdw6dnyy7kerni</incremental_authorization>
            <execute_threed>true</execute_threed>
            <merchant_initiated_transaction_id>ABC123</merchant_initiated_transaction_id>
            <idempotency_key>key</idempotency_key>
            <funds_transfer_type>FD</funds_transfer_type>
            <account_holder_type>individual</account_holder_type>
            <source_type>example</source_type>
            <source_id>abc123</source_id>
            <instruction_purpose>leisure</instruction_purpose>
            <destination>
              <account_holder>
                <email>[email protected]</email>
                <date_of_birth>1989-10-31</date_of_birth>
                <identification>
                  <type>passport</type>
                  <number>123456abcdef</number>
              </identification>
              </account_holder>
            </destination>
            <sender>
              <type>type</type>
              <dob>YYYY-MM-DD</dob>
              <zip>zip</zip>
              <first_name>John</first_name>
              <last_name>Doe</last_name>
              <address>
                <address_line1>address 1</address_line1>
                <address_line2>address 2</address_line2>
                <city>city</city>
                <state>state</state>
                <zip>zip</zip>
                <country>country</country>
              </address>
              <reference>12345</reference>
              <identification>
                <type>id-type</type>
                <number>12345</number>
                <issuing_country>12345</issuing_country>
              </identification>
            </sender>
            <metadata>
              <coupon_code>NY2018</coupon_code>
              <partner_id>123989</partner_id>
            </metadata>
            <recipient>
              <dob>YYYY-MM-DD</dob>
              <account_number>12345</account_number>
              <zip>zip</zip>
              <first_name>John</first_name>
              <last_name>Doe</last_name>
              <address>
                <address_line1>addess 1</address_line1>
                <address_line2>address 2</address_line2>
                <city>city</city>
                <state>state</state>
                <zip>zip</zip>
                <country>country</country>
              </address>
            </recipient>
            <processing>
              <aft>true</aft>
              <preferred_scheme>cartes_bancaires</preferred_scheme>
            </processing>
            <risk>
              <enabled>true</enabled>
              <device_session_id>session_id</device_session_id>
            </risk>
          </checkout_v2>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2023-03-22T18:15:51Z</created_at>
  <updated_at type="dateTime">2023-03-22T18:15:51Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>BXFkin0newBwha6lzmcbpW7nbPn</token>
  <transaction_type>Authorization</transaction_type>
  <order_id nil="true"/>
  <ip nil="true"/>
  <description nil="true"/>
  <email nil="true"/>
  <merchant_name_descriptor nil="true"/>
  <merchant_location_descriptor nil="true"/>
  <merchant_profile_key nil="true"/>
  <gateway_specific_fields>
    <checkout_v2>
      <descriptor_name>TheName</descriptor_name>
      <descriptor_city>Wanaque</descriptor_city>
      <card_on_file>true</card_on_file>
      <transaction_indicator>1</transaction_indicator>
      <previous_charge_id>charge_12345</previous_charge_id>
      <attempt_n3d>true</attempt_n3d>
      <authorization_type>Estimated</authorization_type>
      <challenge_indicator>trusted_listing</challenge_indicator>
      <exemption>no_preference</exemption>
      <processing_channel_id>pc_ovo75iz4hdyudnx6tu74mum3fq</processing_channel_id>
      <incremental_authorization>pay_obb2wabkwzskjdw6dnyy7kerni</incremental_authorization>
      <execute_threed>true</execute_threed>
      <merchant_initiated_transaction_id>ABC123</merchant_initiated_transaction_id>
      <idempotency_key>key</idempotency_key>
      <funds_transfer_type>FD</funds_transfer_type>
      <account_holder_type>individual</account_holder_type>
      <source_type>example</source_type>
      <source_id>abc123</source_id>
      <instruction_purpose>leisure</instruction_purpose>
      <destination>
        <account_holder>
          <email>[email protected]</email>
          <date_of_birth>1989-10-31</date_of_birth>
          <identification>
            <type>passport</type>
            <number>123456abcdef</number>
          </identification>
        </account_holder>
      </destination>
      <sender>
        <type>type</type>
        <dob>YYYY-MM-DD</dob>
        <zip>zip</zip>
        <first_name>John</first_name>
        <last_name>Doe</last_name>
        <address>
          <address_line1>address 1</address_line1>
          <address_line2>address 2</address_line2>
          <city>city</city>
          <state>state</state>
          <zip>zip</zip>
          <country>country</country>
        </address>
        <reference>12345</reference>
        <identification>
          <type>id-type</type>
          <number>12345</number>
          <issuing_country>12345</issuing_country>
        </identification>
      </sender>
      <metadata>
        <coupon_code>NY2018</coupon_code>
        <partner_id>123989</partner_id>
      </metadata>
      <recipient>
        <dob>YYYY-MM-DD</dob>
        <account_number>12345</account_number>
        <zip>zip</zip>
        <first_name>John</first_name>
        <last_name>Doe</last_name>
        <address>
          <address_line1>addess 1</address_line1>
          <address_line2>address 2</address_line2>
          <city>city</city>
          <state>state</state>
          <zip>zip</zip>
          <country>country</country>
        </address>
      </recipient>
      <processing>
        <aft>true</aft>
        <preferred_scheme>cartes_bancaires</preferred_scheme>
      </processing>
      <risk>
        <enabled>true</enabled>
        <device_session_id>session_id</device_session_id>
      </risk>
    </checkout_v2>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>50</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <warning nil="true"/>
  <application_id nil="true"/>
  <amount type="integer">100</amount>
  <local_amount nil="true"/>
  <currency_code>USD</currency_code>
  <retain_on_success type="boolean">false</retain_on_success>
  <payment_method_added type="boolean">false</payment_method_added>
  <smart_routed type="boolean">false</smart_routed>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name>Newfirst Newlast</name>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
  </shipping_address>
  <response>
    <success type="boolean">true</success>
    <message>Successful authorize</message>
    <avs_code nil="true"/>
    <avs_message nil="true"/>
    <cvv_code nil="true"/>
    <cvv_message nil="true"/>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2023-03-22T18:15:51Z</created_at>
    <updated_at type="dateTime">2023-03-22T18:15:51Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2023-03-10T21:27:28Z</updated_at>
    <email>[email protected]</email>
    <data>
      <my_payment_method_identifier>448</my_payment_method_identifier>
      <extra_stuff>
        <some_other_things>Can be anything really</some_other_things>
      </extra_stuff>
    </data>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <metadata>
      <key>string value</key>
    </metadata>
    <callback_url nil="true"/>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Newfirst</first_name>
    <last_name>Newlast</last_name>
    <month type="integer">3</month>
    <year type="integer">2032</year>
    <address1 nil="true"/>
    <address2 nil="true"/>
    <city nil="true"/>
    <state nil="true"/>
    <zip nil="true"/>
    <country nil="true"/>
    <phone_number nil="true"/>
    <company nil="true"/>
    <full_name>Newfirst Newlast</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"/>
    <shipping_address2 nil="true"/>
    <shipping_city nil="true"/>
    <shipping_state nil="true"/>
    <shipping_zip nil="true"/>
    <shipping_country nil="true"/>
    <shipping_phone_number nil="true"/>
    <issuer_identification_number nil="true"/>
    <click_to_pay type="boolean">false</click_to_pay>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
    <stored_credential_usage>
      <test>
        <original_network_transaction_id>37be5367d6dbe4a88c9d</original_network_transaction_id>
        <network_transaction_id>37be5367d6dbe4a88c9d</network_transaction_id>
      </test>
    </stored_credential_usage>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

To perform a partial capture, the capture_type gateway specific field should be passed with the value 'NonFinal'.

To perform an incremental authorization, the incremental_authorization gateway specific field should be passed with the gateway transaction id from the referenced authorize transaction. Note that Checkout only allows incremental authorizations for referenced authorize transactions that were originally created with the authorization_type set to 'Estimated'. Also note that Incremental authorization is only available in oauth mode.

To perform a retry request, the idempotency_key gateway specific field should be passed with a key. See Checkout’s documentation to learn more about how to use API idempotency.

When using the merchant_initiated_transaction_id field, a merchant will have the option to provide a previous network transaction id from the CheckoutV2 gateway. It is the merchant’s responsibility to store and manage these network transaction ids. When a value is present, this value should override the existing stored credential logic and add the stored credential values to the transaction request.

When performing an Account Funding Transaction (AFT), please refer to this Checkout guide for more details as there are varying specific requirements.

Descriptors

Checkout.com allows you to specify a descriptor_name and descriptor_city. These descriptors will be shown on a customer’s credit card statement. Please note that they are codependent; if you provide one of these fields, a value for the other is required or Checkout.com will fail the transaction.

Payouts via General Credit

Performing payouts on Checkout can be done using the General Credit transaction type. Your gateway must be created in oauth mode to successfully initiate a General Credit or payout.

Checkout offers two types of card payouts :

Money Transfer
Direct Funds Disbursement

Checkout requires different fields to be sent depending on the payout type, so please refer to their documentation for your specific use case.

The field payout must be set to true at the top level of the Spreedly transaction request body to enable sender and destination to be sent as objects within the gateway_specific_fields of your General Credit payout request.

When you initiate a payout through Spreedly, and the destination is a card that is tokenized at Spreedly, the destination type will be set to card automatically with the existing back end logic and does not need to be sent. The destination card number, expiry month, expiry year, name, and address fields will also be automatically populated with data stored on the payment method token. The following fields are required but can only be passed along in the request if they are added when the card is tokenized:

expiry_month
expiry year
first_name
last_name
company_name (This is only relevant if the destination is a business or government entity. If the account_holder_type is set to corporate or government, the name data from the payment method stored at Spreedly and used for the payout destination will be mapped to company_name.)

If there is data missing on the stored payment method, please take advantage of the option to update a card’s non-sensitive data via our API.

processing is an object that may contain many different subfields. Please visit the Checkout documentation for examples on how to structure these subfields.

<transaction>
  <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
  <amount>100</amount>
  <currency_code>USD</currency_code>
  <payout>true</payout>
  <gateway_specific_fields>
    <checkout_v2>
      <processing_channel_id>pc_ovo75iz4hdyudnx6tu74mum3fq</processing_channel_id>
      <source-type>currency_account</source-type>
      <source-id>ca_spwmped4qmqenai7hcghquqle4</source-id>
      <funds-transfer-type>FD</funds-transfer-type>
      <instruction-purpose>leisure</instruction-purpose>
      <destination>
        <account-holder>
          <phone>
            <number>9108675309</number>
            <country-code>1</country-code>
          </phone>
          <identification>
            <type>passport</type>
            <number>12345788848438</number>
            <issuing_country>US</issuing_country>
            <date_of_expiry>2029-12-31</date_of_expiry>
          </identification>
          <email>[email protected]</email>
          <date_of_birth>1989-12-31</date_of_birth>
          <country_of_birth>US</country_of_birth>
        </account-holder>
      </destination>
      <sender>
        <type>individual</type>
        <first-name>Jane</first-name>
        <middle-name>Middle</middle-name>
        <last-name>Doe</last-name>
        <address>
          <address1>123 Main St</address1>
          <address2>Apt G</address2>
          <city>Narnia</city>
          <state>ME</state>
          <zip>12345</zip>
          <country>US</country>
        </address>
        <reference>012345</reference>
        <reference-type>other</reference-type>
        <source-of-funds>debit</source-of-funds>
        <identification>
          <type>passport</type>
          <number>ABC123</number>
          <issuing-country>US</issuing-country>
          <date-of-expiry>2027-12-31</date-of-expiry>
        </identification>
        <date_of_birth>1979-12-31</date_of_birth>
        <country_of_birth>US</country_of_birth>
        <nationality>US</nationality>
      </sender>
      <recipient>
        <dob>YYYY-MM-DD</dob>
        <account_number>12345</account_number>
        <zip>zip</zip>
        <first_name>John</first_name>
        <last_name>Doe</last_name>
        <address>
          <address_line1>addess 1</address_line1>
          <address_line2>address 2</address_line2>
          <city>city</city>
          <state>state</state>
          <zip>zip</zip>
          <country>country</country>
        </address>
      </recipient>
      <processing>
        <aft>true</aft>
        <preferred_scheme>cartes_bancaires</preferred_scheme>
      </processing>
    </checkout_v2>
  </gateway_specific_fields>
</transaction>

The optional risk field is an object that can contain the enabled and device_session_id subfields. The device_session_id must be included if the enabled field is set to true. More information can be found on the Checkout's documentation.

Gateway specific response fields

A response from Checkout.com may contain a source_id field or a 3ds object when using 3DS authentication. A response may also contain a response_message field that presents risk response messages. Additionally, the partner_merchant_advice_code can be returned on failing transactions if your merchant account is configured for this. Please visit Checkout's documentation for more details.

You can find this information in gateway_specific_response_fields. For example, a transaction could have something like the following:

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
     <checkout_v2>
       <response_message>Card velocity - Monthly - All transactions</response_message>
       <issuer_country>GB</issuer_country>
       <3ds>
        <downgraded>false</downgraded>
        <enrolled>N</enrolled>
      </3ds>
     </checkout_v2>
  </gateway_specific_response_fields>
</transaction>

3DS exemptions

Checkout.com has systems in place to ensure that correct transaction types and exemption scenarios are flagged. However, there are some circumstances where particular fields need to be sent, as outlined below:

MOTO

Set transaction_indicator to 3 to mark your transaction as MOTO or set three_ds_exemption_type to moto.

MIT

Spreedly offers two ways to request MIT exemptions. See the Stored credential regulations for more information.