Skip to content

Storefront integration

Last updated: 29th June 2022

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

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

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.

    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

    HeaderValue

    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 nameDescription

    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.

    This is only for card payments.

    public_hash

    number
    required

    For Vault payments

    The Vault public hash.

    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.

    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
      3
      4
      5
      6
      7
      8
      {
      "paymentRequest": {
      "payment_method": "checkoutcom_card_payment",
      "payment_token": "tok_4gzeau5o2uqubbk6fufs3m7p54",
      "quote_id": 799,
      "save_card": true
      }
      }

      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
        3
        4
        {
        "success": true,
        "orderID": 000000028
        }