Checkout.com Gateway Guide

close

Services and Compatibility

Payment Gateway Company Name:
Checkout.com
Services that work with Spreedly:
  • Checkout.com
Supported operations:
Purchase, Authorize, Capture, Refund, Void, Verify
Supported payment types:
Third Party Token
Spreedly 3DS2 Global Supported
Yes
Gateway Specific 3DS1 Supported
Yes
Gateway Specific 3DS2 Supported
Yes
Regions:
Asia Pacific, Europe, Latin America, Middle East, North America
API endpoint URL:
https://api.checkout.com

Authentication and Security

Specific names for credentials:
Secret Key

Onboarding Merchants in:

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.

Adding a Checkout v2 gateway

To add a Checkout.com gateway:


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>Zhzdow5zrddOtb8u7dBhRhT0QX9</token>
  <gateway_type>checkout_v2</gateway_type>
  <name>Checkout V2</name>
  <description 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_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_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
    <supports_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_disburse type="boolean">false</supports_disburse>
  </characteristics>
  <credentials>
  </credentials>
  <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_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="dateTime">2018-06-19T17:07:49Z</created_at>
  <updated_at type="dateTime">2018-06-19T17:07:49Z</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={}>

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.

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


curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.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>
            <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">2021-06-25T20:00:00Z</created_at>
  <updated_at type="dateTime">2021-06-25T20:00:00Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>BXRDQ2z7AjrtZLYtVnF8mlaSdfX</token>
  <transaction_type>Purchase</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>
      <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>54</gateway_transaction_id>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <warning nil="true"/>
  <application_id nil="true"/>
  <amount type="integer">100</amount>
  <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 purchase</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">2021-06-25T20:00:00Z</created_at>
    <updated_at type="dateTime">2021-06-25T20:00:00Z</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">2021-06-25T20:00:00Z</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"/>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

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.

Card on file requirements

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. By default this field is set to 1, a regular transaction. 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.

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.

MIT

Set transaction_indicator to 2 to mark your transaction as recurring. Also send the previous_charge_id, corresponding to either the previous transaction or the opening transaction of the payment series (e.g. pay_B41BEAAC175U76BD3EE1).