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
- 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:
-
Andorra
-
United Arab Emirates
-
Argentina
-
Austria
-
Australia
-
Belgium
-
Bulgaria
-
Bahrain
-
Brazil
-
Switzerland
-
Chile
-
China
-
Colombia
-
Cyprus
-
Czech Republic
-
Germany
-
Denmark
-
Estonia
-
Egypt
-
Spain
-
Finland
-
France
-
United Kingdom
-
Greece
-
Hong Kong
-
Croatia
-
Hungary
-
Ireland
-
Iceland
-
Italy
-
Jordan
-
Japan
-
Kuwait
-
Liechtenstein
-
Lithuania
-
Luxembourg
-
Latvia
-
Monaco
-
Malta
-
Mexico
-
Malaysia
-
Netherlands
-
Norway
-
New Zealand
-
Oman
-
Peru
-
Poland
-
Portugal
-
Qatar
-
Romania
-
Saudi Arabia
-
Sweden
-
Singapore
-
Slovenia
-
Slovakia
-
San Marino
-
Turkey
-
United States
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 totrue
since Spreedly stores the card details before sending to Checkout.com. Specifyfalse
to override this field.transaction_indicator
: The type of transaction being authorized. By default this field is set to1
, a regular transaction.2
can be specified for recurring or3
for MOTO.previous_charge_id
: Used to reference either the previous transaction or the opening transaction of a payment plan. Theprevious_charge_id
is thechargeId
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 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
).