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

Supported payment types:

Credit Card

3D Secure 1 Supported

Yes

3D Secure 2 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.

Adding

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`

Optional Gateway specific request 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>
          </checkout_v2>
        </gateway_specific_fields>
      </transaction>'


<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2018-04-27T19:34:06Z</created_at>
  <updated_at type="dateTime">2018-04-27T19:34:06Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>Nu8wW5ySEcxSeUGaTBWRSkmRnx3</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"/>
  <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>
    </checkout_v2>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>44</gateway_transaction_id>
  <gateway_latency_ms type="integer">3</gateway_latency_ms>
  <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>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>ESkKCzXVwkdZnZ7Y5ed9cbSR7D4</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name>Kory Hauck</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2018-04-27T19:34:06Z</created_at>
    <updated_at type="dateTime">2018-04-27T19:34:06Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>XNEtlBSKOyvIpL96euioRt8F9FX</token>
    <created_at type="dateTime">2018-04-25T14:40:02Z</created_at>
    <updated_at type="dateTime">2018-04-27T19:29:32Z</updated_at>
    <email nil="true"/>
    <data nil="true"/>
    <storage_state>retained</storage_state>
    <test type="boolean">true</test>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Kory</first_name>
    <last_name>Hauck</last_name>
    <month type="integer">4</month>
    <year type="integer">2020</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>Kory Hauck</full_name>
    <eligible_for_card_updater nil="true"/>
    <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 nil="true"/>
  </payment_method>
</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 authorizated. 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 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>
     </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).