Checkout.com Gateway Guide

Services and Compatibility

Payment Gateway Company Name:

Checkout.com

Services that work with Spreedly:

Checkout.com

Supported operations:

Purchase, Authorize, Capture, Refund, Void, Verify, Store, General Credit

Supported payment types:

Credit Card, Google Pay, Apple Pay

Spreedly 3DS2 Global Supported

Yes

Gateway Specific 3DS2 Supported

Yes

Populate MIT GSF Support

Regions:

Asia Pacific, Europe, Latin America, Middle East, North America

API endpoint URL:

https://api.checkout.com

Authentication and Security

Specific names for credentials:: default mode:
Public Key, Secret Key; oauth mode:
Client Id, Client Secret

Onboarding Merchants in:

Don’t see your preferred region? Contact Us

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 v2 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_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>


env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.add_gateway(:checkout_v2, secret_key: "Your secret_key")


#<Spreedly::Gateway:0x007fe332a6afc8
@token="OIzbaOclvusFsqhWvCs2dcVUSuf",
@created_at="2017-07-27T17:48:20Z",
@updated_at="2017-07-27T17:48:20Z",
@gateway_type="checkout_v2",
@state="retained",
@name="Checkout V2",
@credentials={}>

Adding a Checkout v2 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_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>

Adding a Checkout v2 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 3D Secure 2 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 third-party 3DS2 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 seamless 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.

Please refer to using a payment method for more information on how to send GSFs

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>
            <metadata>
              <coupon_code>NY2018</coupon_code>
              <partner_id>123989</partner_id>
            </metadata>
          </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>
      <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>
      <merchant_initiated_transaction_id>ABC123</merchant_initiated_transaction_id>
      <idempotency_key>key</idempotency_key>
      <metadata>
        <coupon_code>NY2018</coupon_code>
        <partner_id>123989</partner_id>
      </metadata>
    </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>joey@example.com</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.

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.

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.

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