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.
Note
This endpoint only accepts card payments (including Mada).
The request
Endpoint
In addition to card payments the v3 endpoint also allows payments via saved cards for uses who are logged in.
Replace example.com in the following endpoint URL with your store's domain name. The URL can be http or https.
Use the valid public key of your Checkout.com account. You can find this in the Hub.
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.
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."
1
{
2
"success":true,
3
"orderID":"000000028"
4
}
Once 3DS authentication is completed, you will receive a session_id from our payment gateway. You can pass this session_id to our get payment details endpoint to determine whether the payment was approved, or to get more information about it.
The v2 endpoint is only available for plugin version 2.2.6 and above.
Replace example.com in the following endpoint URL with your store's domain name. The URL can be http or https.
post
https://example.com/checkout_com/api/v2
Header parameters
Header
Value
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_token
string
required
The Checkout.com payment token.
Use Frames, or another of our integration methods, to tokenize customers' cards.
quote_id
string
required
The shopping cart identifier.
card_bin
string
optional
The bank identification number (BIN) of a card.
Required if the payment is made with a Mada card.
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.
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."
Once 3DS authentication is completed, you will receive a session_id from our payment gateway. You can pass this session_id to our get payment details endpoint to determine whether the payment was approved, or to get more information about it.
Replace example.com in the following endpoint URL with your store's domain name. The URL can be http or https.
post
https://example.com/checkout_com/api/v1
Header
Value
Authorization
required
public key
Use the valid public key of your Checkout.com account. You can find this in the Hub.
Field name
Description
payment_token
string
required
The Checkout.com payment token.
Use Frames, or another of our integration methods, to tokenize customers' cards.
quote_id
string
required
The shopping cart identifier.
card_bin
string
optional
The bank identification number (BIN) of a card.
Required if the payment is made with a Mada card.
1
{
2
"payment_token":"tok_4gzeau5o2uqubbk6fufs3m7p54",
3
"quote_id":12345,
4
"card_bin":"424242"
5
}
If you get a response with "success": true, your order was successful.
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."