Go to home page

Guides

E-commerce

Developing with an AI agent?

Try using our Centrapay e-commerce integration skill to help guide your implementation.

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 e-commerce payment flows.

Before You Begin

Contact integrations@centrapay.com to configure your business for e-commerce. If you decide to use the redirect flow, you will need to inform us of allowed domains for redirect URLs.

Centrapay will configure your business to accept test payments and provide you with the following resources 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.

Once you have confirmed your integration needs, we will also provide you with a customized integration checklist. 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.

Backend Server

Both the redirect and popup methods require a backend server to securely call the Centrapay API using your API key. The client-side examples in this guide call this server at /api/payment-requests, which proxies the request to Centrapay so your API key is never exposed to the browser.

All Centrapay API requests are made against the base URL https://service.centrapay.com. There is no separate sandbox host — test and live payments use the same URL and are determined by the credentials Centrapay issues you. A test merchant API key is available for creating test Payment Requests.

Terminal window
import express from 'express';
import fetch from 'node-fetch';


const { CENTRAPAY_MERCHANT_API_KEY, CENTRAPAY_MERCHANT_CONFIG_ID } = process.env;
const centrapayBaseUrl = 'https://service.centrapay.com/api';


const app = express();
app.use(express.json());


app.post('/api/payment-requests', async (req, res) => {
  try {
    const response = await fetch(`${centrapayBaseUrl}/payment-requests`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': CENTRAPAY_MERCHANT_API_KEY,
      },
      body: JSON.stringify({
        configId: CENTRAPAY_MERCHANT_CONFIG_ID,
        ...req.body,
      }),
    });
    const json = await response.json();
    res.status(response.status).json(json);
  } catch (error) {
    console.error('Failed to create payment request:', error);
    res.status(500).json({ error: 'Failed to create payment request.' });
  }
});


app.get('/api/payment-requests/:paymentRequestId', async (req, res) => {
  try {
    const response = await fetch(
      `${centrapayBaseUrl}/payment-requests/${req.params.paymentRequestId}`,
      { headers: { 'X-Api-Key': CENTRAPAY_MERCHANT_API_KEY } },
    );
    const json = await response.json();
    res.status(response.status).json(json);
  } catch (error) {
    console.error('Failed to get payment request:', error);
    res.status(500).json({ error: 'Failed to get payment request.' });
  }
});

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, 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.

    Terminal window
    const response = await fetch('/api/payment-requests', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        value: { amount: '100', currency: 'NZD' }, // amount in cents ($1.00)
        redirectPaidUrl: 'https://example.com/paid',
        redirectCancelUrl: 'https://example.com/cancel',
      }),
    });
    const paymentRequest = await response.json();
    if (!response.ok) {
      throw new Error(paymentRequest.message);
    }
    window.location.replace(paymentRequest.url);

    See Create a Payment Request for the full list of parameters and error codes.

  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() {
          const response = await fetch('/api/payment-requests', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
              value: { amount: '100', currency: 'NZD' }, // amount in cents ($1.00)
            }),
          });
          const paymentRequest = await response.json();
          if (!response.ok) {
            throw new Error(paymentRequest.message);
          }
          return paymentRequest;
        },
        async onComplete(data) {
          const response = await fetch(`/api/payment-requests/${data.paymentRequestId}`);
          const paymentRequest = await response.json();
          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.

      See Create a Payment Request for the full list of parameters and error codes.

    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 .