POST Checkout

Create a new Catch Checkout.

When the consumer clicks to complete their order with Catch selected as their payment method, make a server-side request to Catch’s POST Checkout endpoint. Catch responds with a Checkout ID that uniquely identifies the consumer’s Catch payment session.

Path

POST https://<environment>.getcatch.com/v1/checkouts

Variable name	Description	Possible values
environment	The Catch environment in which you’re making the request.	See Authentication.

Top Level Parameters

Parameter name	Necessity	Format	Description
amounts	required	object	Contains details of the order total.
billing	required	object	Contains details of the billing contact.
shipping	required	object	Contains details of the shipping contact.
shipping_method	optional	string	The name of the shipping method (e.g., "express").
items	required	array	Contains details of the order's items.
merchant_checkout_id	required	string	The ID of this checkout in the merchant's system which Catch will store for shared identification purposes. This ID should be unique per checkout.
merchant_user_id	required	string or null	The ID of the consumer in the merchant's system which Catch will store for shared identification purposes. (While this field is required, the value null may be explicitly passed if the consumer is anonymous and doesn't have an ID. However, it is recommended to provide an ID wherever possible).
redirect_cancel_url	required	string	The URL to direct the customer's browser to in the event that they don't successfully confirm their checkout with Catch.
redirect_confirm_url	required	string	The URL to direct the customer's browser to in the event that they successfully confirm their checkout with Catch.
platform	optional	object	Contains the name and version of the platform in use (e.g., Shopify).

Amounts object

Parameter name	Necessity	Format	Description
total	required	integer (in cents)	The order total inclusive of tax, shipping, and merchant discounts.
subtotal	required	integer (in cents)	The subtotal that should be displayed to the consumer.
tax	required	integer (in cents)	The amount of tax on the order.
shipping	required	integer (in cents)	The amount of shipping cost on the order.
discount_total	optional	integer (in cents)	The discount total that should be displayed to the consumer.
currency	required	string (ISO 4217)	The currency in which the amounts are represented.

Address object

Parameter name	Necessity	Format	Description
name	required	string	The name of the person for the order.
address_1	required	string	The street address.
address_2	optional	string	The optional apartment, suite, unit, etc.
city	required	string	The city.
zone_code	required	string	The state or province abbreviation, such as 'NY' or 'CA'.
country_code	required	string	The country code.
postal_code	required	string	The postal code.
phone_number	optional	string	The phone number associated with the order's contact. Format: "[phone]"

Items array

Parameter name	Necessity	Format	Description
name	required	string	The name of the item.
sku	required	string	The SKU of the item.
price	required	object	The price of the item.
quantity	required	integer	The quantity of the item.
category	optional	array	Array of arrays containing category strings, e.g. "electronics" or "shoes". Optionally, a single array can be interpreted as a hierarchical path with the top-level parent category at index zero.
image_url	required	string	The image of the item.

Price object

Parameter name	Necessity	Format	Description
amount	required	integer	The unit price of the item.
currency	required	string (ISO 4217)	The currency that the price of the item is in.

Platform object

Parameter name	Necessity	Format	Description
platform_type	optional	string	Name of the platform the merchant is on (e.g., "Shopify").
platform_version	optional	string	Version of the platform the merchant is on.

Example request

Example POST checkout

{
    "amounts":{
       "total":121582,
       "subtotal":120670,
       "tax":585,
       "shipping":307,
       "discount_total":20,
       "currency":"USD"
    },
    "billing":{
        "name":"Alice Jones",
        "address_1":"123 East St.",
        "address_2":"Apt. D",
        "city":"New York",
        "area":"New York",
        "zone_code": "NY",
        "postal_code":"90210",
        "country_code": "US",
        "phone_number": "[phone]"
     },
    "shipping":{
        "name":"Alice Jones",
        "address_1":"123 East St.",
        "address_2":"Apt. D",
        "city":"New York",
        "area":"New York",
        "zone_code": "NY",
        "postal_code":"90210",
        "country_code": "US",
        "phone_number": "[phone]"
     },
    "shipping_method": "overnight",
    "items":[
        {
           "name":"straight_leg_jean",
           "sku":"4db3ifnl",
           "price":{
              "amount":15019,
              "currency":"USD"
           },
           "quantity":2,
           "image_url":"test://url-0",
           "category": [["clothing","jeans"]]
        },
        {
           "name":"wide_leg_jean",
           "sku":"syt9r0ub",
           "price":{
              "amount":19472,
              "currency":"USD"
           },
           "quantity":3,
           "image_url":"test://url-1",
           "category": [["clothing","jeans"]]
        },
        {
           "name":"cropped_jean",
           "sku":"r84qlsok",
           "price":{
              "amount":16108,
              "currency":"USD"
           },
           "quantity":2,
           "image_url":"test://url-2",
           "category": [["clothing","jeans"],["sale"]]
        }
    ],
    "merchant_checkout_id":"4b718371-a466-4270-bc97-ece09d256443",
    "merchant_user_id": "1234",
    "redirect_confirm_url":"https://merchant.com/redirect",
    "redirect_cancel_url":"https://merchant.com/cancel",
    "platform": {
        "platform_type": "magento",
        "platform_version": "1.3"
    }
 }

Success Response

Example POST checkout response

201 Created
{
  "id":"ch-49b03b7d-6bfd-4286-9afb-7f51a8f39491"
}

Notes

• All request parameters are required unless otherwise indicated.
• merchant_checkout_id is required for platform integrations. If there is a platform-provided unique identifier (ID) for each order, we recommend using this as the value.