/ / /

Storefront integration

Last updated: April 29, 2022

Information

Follow this guide if you're building a storefront on top of a headless Magento 2 backend.

Once you've set up our Magento 2 plugin in the Magento back end, you're ready to start accepting payments through your own storefront.

To get started, follow Magento's checkout tutorial until you get to step 9. Then, instead of following steps 9 and 10, use our request payment endpoint below to complete the order.

Request payment

Note

Currently, this endpoint only accepts card payments (including Mada). We will add further functionality in due course.

The request

Endpoint

Note

In addition to card payments the v3 endpoint also allows payments via saved cards for uses who are logged in.

Information

Replace example.com in the following endpoint URL with your store's domain name. The URL can be http or https.

Logged in customers

post

https://www.example.com/rest/default/v1/checkout_com/mine/api/v3

Guest checkout

post

https://www.example.com/rest/default/v1/checkout_com/guest/api/v3

Header parameters

Header Value

Header	Value
`Authorization` required For logged in customers only	`Bearer customer_token` See Magento documentation to generate a customer token.
`Cko-Authorization` required	`public key` Use the valid public key of your Checkout.com account. You can find this in the Hub.

Authorization

required

For logged in customers only

Bearer customer_token

See Magento documentation to generate a customer token.

Cko-Authorization

required

public key

Use the valid public key of your Checkout.com account. You can find this in the Hub.

Body parameters

Field name	Description
`payment_method` string required	The payment method. `checkoutcom_card_payment` / `checkoutcom_vault`
`quote_id` number required	The shopping cart identifier.
`payment_token` string required For card payments	The Checkout.com payment token. Use Frames, or another of our integration methods, to tokenize customers' cards. Information This is only for card payments.
`public_hash` number required For Vault payments	The Vault public hash. Information This is only for payments through Vault.
`card_bin` string optional	The bank identification number (BIN) of a card. Required if the payment is made with a Mada card.
`card_cvv` number optional	The card verification value (CVV) of a card. Information This is only for card payments and users who are logged in.
`save_card` boolean optional For card payment and logged in users	Save card option for `checkoutcom_card_payment`.
`success_url` string optional	The URL to which the customer is redirected following a successful payment. Allows you to have a different redirection URL for the storefront from the one on your Magento 2 instance. If not provided, your existing `success_url` will be used.
`failure_url` string optional	The URL to which the customer is redirected following a failed payment. Allows you to have a different redirection URL for the storefront from the one on your Magento 2 instance. If not provided, your existing `failure_url` will be used.

Request example

1{
2    "paymentRequest": {
3        "payment_method": "checkoutcom_card_payment",
4        "payment_token": "tok_4gzeau5o2uqubbk6fufs3m7p54",
5        "quote_id": 799,
6        "save_card": true
7    }
8}

The response

If you get a response with "success": true, your order was successful.

If the payment was made with 3D Secure (3DS) authentication, you will get a 200 response containing a redirect link that the customer will need to complete in order to finalize the transaction.

If unsuccessful, you will get one of the following error messages:

Status code 422 – "The request is invalid."
Status code 500 – "The order could not be created."
Status code 422 – "The payment request was declined by the gateway."

Success response example

1{
2  "success": true,
3  "orderID": "000000028"
4}