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 nameDescriptionPossible values
environmentThe Catch environment in which you’re making the request.See Authentication.

Top Level Parameters

Parameter nameNecessityFormatDescription
amountsrequiredobjectContains details of the order total.
billingrequiredobjectContains details of the billing contact.
shippingrequiredobjectContains details of the shipping contact.
shipping_methodoptionalstringThe name of the shipping method (e.g., "express").
itemsrequiredarrayContains details of the order's items.
merchant_checkout_idrequiredstringThe 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_idrequiredstring or nullThe 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_urlrequiredstringThe URL to direct the customer's browser to in the event that they don't successfully confirm their checkout with Catch.
redirect_confirm_urlrequiredstringThe URL to direct the customer's browser to in the event that they successfully confirm their checkout with Catch.
platformoptionalobjectContains the name and version of the platform in use (e.g., Shopify).
user_cohortsrequiredarrayA user cohort that this checkout should be associated with. More details on user cohorts can be found here.

Amounts object

Parameter nameNecessityFormatDescription
totalrequired integer (in cents)The total amount to charge the consumer after all promotions, discounts, and fees are applied.
subtotalrequired integer (in cents)The subtotal that should be displayed to the consumer.
taxrequired integer (in cents)The amount of tax on the order.
shippingrequiredinteger (in cents)The amount of shipping cost on the order.
discount_totaloptionalinteger (in cents)The discount total that should be displayed to the consumer.
currencyrequiredstring (ISO 4217)The currency in which the amounts are represented.

Billing object

Parameter nameNecessityFormatDescription
namerequiredstringThe name of the person to bill for the order.
address_1requiredstringThe street address of the billing contact.
address_2optionalstringThe optional apartment, suite, unit, etc. of the billing contact.
cityrequiredstringThe city of billing contact
areaoptionalstringFor international addresses where needed, such as name of the suburb for NZ or village for UK.
zone_coderequiredstringThe state or province abbreviation for the billing contact, such as 'NY' or 'CA'.
country_coderequiredstringThe country code for the billing contact.
postal_coderequiredstringThe postal code of the billing contact.
phone_numberoptionalstringThe phone number associated with the order's billing contact. Format: "+12223334444"

Shipping object

Parameter nameNecessityFormatDescription
namerequiredstringThe name of the person receiving the shipment of the order.
address_1requiredstringThe street address where the order will be shipped.
address_2optionalstringThe optional apartment, suite, unit, etc. where the order will be shipped.
cityrequiredstringThe city of the shipping address.
areaoptionalstringFor international addresses where needed, such as name of the suburb for NZ or village for UK.
zone_coderequiredstringThe state or province abbreviation for the shipping contact, such as 'NY' or 'CA'.
country_coderequiredstringThe country code for the shipping address, such as 'US'.
postal_coderequiredstringThe postal code of the shipping address.
phone_numberoptionalstringThe phone number associated with the shipment. Format: "+12223334444"

Items array

Parameter nameNecessityFormatDescription
namerequiredstringThe name of the item.
skurequiredstringThe SKU of the item.
pricerequiredobjectThe price of the item.
quantityrequiredintegerThe quantity of the item.
categoryoptionalarrayArray 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_urlrequiredstringThe image of the item.

Price object

Parameter nameNecessityFormatDescription
amountrequiredintegerThe unit price of the item.
currencyrequiredstring (ISO 4217)The currency that the price of the item is in.

Platform object

Parameter nameNecessityFormatDescription
platform_typeoptionalstringName of the platform the merchant is on (e.g., "Shopify").
platform_versionoptionalstringVersion of the platform the merchant is on.

User Cohorts array

Parameter nameNecessityFormatDescription
N/ArequiredstringA user cohort that this checkout should be associated with. More details on user cohorts can be found here.

Example request

{
    "amounts":{
       "total":121562,
       "subtotal":120670,
       "tax":585,
       "shipping":307,
       "currency":"USD"
    },
    "billing":{
        "name":"Alice Jones",
        "address_1":"123 East St.",
        "address_2":"Apt. D",
        "city":"New York",
        "zone_code": "NY",
        "postal_code":"90210",
        "country_code": "US",
        "phone_number": "+15554443333"
     },
    "shipping":{
        "name":"Alice Jones",
        "address_1":"123 East St.",
        "address_2":"Apt. D",
        "city":"New York",
        "zone_code": "NY",
        "postal_code":"90210",
        "country_code": "US",
        "phone_number": "+15554443333"
     },
    "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"
    },
    "user_cohorts": [
         "platinum",
         "newsletter_subscribers",
         "club_members"
    ]
 }

Success 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 identifer (ID) for each order, we recommend using this as the value.