Go to home page
Docs API Reference

Guides

eCommerce

Centrapay enables businesses to process payments with connected Centrapay assets online. To process online payments, businesses need to integrate with one of our redirect or popup eCommerce payment flows.

Know before you code

Please get in touch with Centrapay to configure your business for eCommerce. If you decide to use the redirect flow, you will need to inform us of allowed domains for redirect URLs.

Centrapay will provide you with the following resources to allow you to start creating Payment Requests .

  1. API Key.
  2. Merchant ID.
  3. Merchant Config ID.

We strongly recommend Centrapay APIs are invoked from your backend where your API key is securely stored.

Centrapay will configure your business to accept test payments before you can accept live payments. Accepting live payments requires you to meet our certification requirements.

Centrapay Checkout Sample

A sample Centrapay e-commerce application is available. It includes demos of both the redirect method and the popup method. Please refer to the README.md file for configuration instructions.

Redirect Method

The Redirect Method is the standard method used by most merchants. This method redirects the customer away from your website to Centrapay to complete the payment. The customer is redirected back to your website at the end of the process.

Overview

    sequenceDiagram
autonumber
  participant Consumer
  participant MP as Merchant Site
  participant MS as Merchant Server
  participant CP as Centrapay

  Consumer->>MP: Pay with Centrapay
  MP->>+MS: Create Payment Request
  MS->>+CP: Create Payment Request
  CP-->>-MS: Payment Request created
  MS-->>-MP: Payment Request created
  MP->>CP: Redirect to Payment Request url
  Note over CP: Show Payment Request details
  Consumer->>CP: Complete payment
  alt ✅ Success
  CP->>MP: Redirect to redirectPaidUrl
  else
  CP->>MP: Redirect to redirectCancelUrl
  end
  MP->>+MS: Get Payment Request
  MS->>+CP: Get Payment Request
  CP-->>-MS: Return Payment Request
  MS-->>-MP: Return Payment Request
  opt Payment Request has status 'new'
	MP->>+MS: Void Payment Request
  MS->>+CP: Void Payment Request
  CP-->>-MS: Return Payment Request
  MS-->>-MP: Return Payment Request
  end
  MP-->>CP: Return
  Note over MP: Checkout complete ✅

Implementation

Your merchant must be configured with allowed domains for your redirect URLs.

  1. Display Centrapay as a payment option on checkout.

  2. When the customer places an order using the Centrapay payment option, you are expected to Create a Payment Request . You must define a redirectPaidUrl and a redirectCancelUrl.

    Our payment protocol supports several optional extensions. Please review the extensions below and determine which ones you need for your integration.

    Centrapay will return a url which you are expected to redirect the customer to.

  3. The customer will be redirected to your site at the end of the payment process.

    • If the Payment Request is paid, they are redirected to the redirectPaidUrl with the paymentRequestId appended as a HTTP query parameter.
    • If the Payment Request is cancelled, expired, or new, they are redirected to the redirectCancelUrl with the paymentRequestId appended as a HTTP query parameter.
    • If the Payment Request is new, you are responsible for voiding the Payment Request .

Access the Centrapay SDK

The Centrapay SDK enables acceptance of Centrapay payments on your website using the popup method. It handles displaying the Centrapay button, launching the Centrapay checkout, and triggering callbacks.

Production: https://sdk.centrapay.com/ecommerce/centrapay.js?merchantId={merchantId}

Overview

You can use the Popup Method to open the Centrapay Checkout in a new browser window.

For desktop applications, the Centrapay Checkout window appears as an overlay on top of the merchant website. For mobile applications, the Centrapay Checkout opens in a new browser tab.

    sequenceDiagram
autonumber
  participant Consumer
  participant MP as Merchant Site
  participant MS as Merchant Server
  participant CP as Centrapay

  Consumer->>MP: Visit checkout
  MP->>CP: Initialise Centrapay SDK
  CP->>MP: Render 'Pay with Centrapay' button
  Consumer->>CP: Click 'Pay with Centrapay' button
  Note over CP: Open Centrapay Checkout popup
  CP->>+MP: onClick() callback
  activate MP
  MP->>MS: Create Payment Request
  MS->>CP: Create Payment Request
  CP-->>MS: Payment Request created
  MS-->>MP: Payment Request created
  MP-->>-CP: Return Payment Request
  Note over CP: Show Payment Request details
  Consumer->>CP: Complete payment
  Note over CP: Close Centrapay Checkout popup
  CP->>+MP: onComplete() callback
  MP->>MS: Get Payment Request
  MS->>CP: Get Payment Request
  CP-->>MS: Return Payment Request
  MS-->>MP: Return Payment Request
  opt Payment Request has status 'new'
	MP->>MS: Void Payment Request
  MS->>CP: Void Payment Request
  CP-->>MS: Return Payment Request
  MS-->>MP: Return Payment Request
  end
  MP-->>-CP: Return
  Note over MP: Display confirmation ✅

Implementation

Terminal window
<html>
  <head>
    <script src="https://sdk.centrapay.com/ecommerce/centrapay.js?merchantId={merchantId}"></script>
  </head>
  <body>
    <div id="centrapay-button-container"></div>
    <script type="text/javascript">
      window.centrapay({
        async onClick() {
          // Create Payment Request
          // Return Payment Request
        },
        async onComplete(data) {
          // Get Payment Request with data.paymentRequestId
          if (paymentRequest.status === 'new') {
            // Void Payment Request
          }
        }
      });
    </script>
  </body>
</html>
  1. Set up the SDK.
    1. Import the Centrapay SDK using a <script> tag. This script fetches the necessary JavaScript to access the Centrapay button in the window object. Your Merchant ID must be in the query string for SDK retrieval.
    2. Add a div with the id centrapay-button-container to render the ‘Pay with Centrapay’ button.
  2. Render the Centrapay button and implement the required callbacks.

    1. onClick

      This callback is triggered when the customer clicks the ‘Pay with Centrapay’ button.

      The callback is expected to Create a Payment Request and return the Payment Request. Our payment protocol supports several optional extensions. Please review the extensions below and determine which ones you need for your integration.

    2. onComplete

      This callback is triggered when the checkout process finishes or the customer closes the payment popup. Your callback will receive a data object containing the Payment Request ID. You are expected to get the Payment Request and act on its status.

      • If the Payment Request is paid, you can redirect the customer to the order confirmation page.
      • If the Payment Request is cancelled or expired, the payment was not completed.
      • If the Payment Request is new, you are responsible for voiding the Payment Request .

Contact Us

Contact  integrations@centrapay.com  to configure your business for eCommerce.

Once you have confirmed your integration needs, we will provide you with a customized integration checklist for certification. Accepting live payments requires you to meet our certification requirements.