API quickstart

The Checkout.com API is constructed around a RESTful structure. By using familiar and predictable URLs, our API works with HTTP response codes to define and signal errors. HTTP methods (or verbs as they are commonly called) are used to determine the action of a request. API responses and errors return in JSON or XML format, and our API libraries can be used to convert responses to required language-specific objects.

API libraries

Our official API libraries are stored and maintained on GitHub for various programming languages and platforms.

API structure

Authentication

To initiate a request to any of Checkout.com’s endpoints, the Authorization field of your HTTPS header must include either your public key or secret key. Use your secret key for server-to-server requests and your public key for requests initiated from the client side. We'll help you with this, as all examples in the documentation indicate which key to use.

Use HTTPS for all API requests, HTTP requests will not be successful.

Example header

curl "https://API_endpoint_here"
-H "Authorization: pk_test_6ff46046-30af-41d9-bf58-929022d2cd14"

You can use your API keys in either Sandbox or Live mode, but we require a different set of keys for each business channel.

Request and response

Checkout.com's Merchant API supports content negotiation; this means you can specify the format of your requests and responses as either JSON or XML.

The examples below demonstrate how to send and receive requests and responses in the same format. However, it is also possible to send a JSON request and receive an XML response, or vice versa.

JSON example

To send a JSON payload to the server and receive a JSON response, set the header to Content-Type:application/json and Accept:application/json.

curl https://api2.checkout.com/v2/tokens/payment
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -H "Accept:application/json"
    -X POST
    -d '{"value":"2867", "currency":"USD", "chargeMode": "1"}'
{
      "id": "pay_tok_5a010daa-4a30-4171-a8e9-8ae0c6de1c68",
      "liveMode": false
}

Use the tabs to alternate between the request and the response.

XML example

To send an XML payload to the server and receive an XML response, set the header to Content-Type:application/xml and Accept:application/xml.

curl https://api2.checkout.com/v2/tokens/card
    -H "Authorization: pk_test_6ff46046-30af-41d9-bf58-929022d2cd14"
    -H "Content-Type:application/xml;charset=UTF-8"
    -H "Accept:application/xml"
    -X POST
    -d '<data>
            <value>2326</value>
            <currency>USD</currency>
            <chargeMode>1</chargeMode>
        </data>'
<data xmlns:json="http://www.checkout.com/apis/json">
    <id>pay_tok_F445293C-CB60-4A9F-90ED-85374E164DEF</id>
    <liveMode>false</liveMode>
</data>

Use the tabs to alternate between the request and the response.

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.