Go to home page

Guides

E-commerce

Developing with an AI agent?

Try using ourCentrapay e-commerce integration skillto 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.

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.

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
  Note over CP: Check Payment Request status
  alt Payment Request has status 'paid'
  CP->>MP: Redirect to redirectPaidUrl
  else Payment Request has status 'cancelled' or 'expired'
  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
  Note over MP: Checkout complete ✅

Implementation

  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.

    When you add your E-commerce merchant site in the Business Portal, enter your website in the Website field, and select Add another website for any other domains. Your redirectPaidUrl and redirectCancelUrl must use one of these domains.

    The Add a Merchant Site form with the E-commerce merchant site type selected and a website entered

    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 or expired, they are redirected to the redirectCancelUrl with the paymentRequestId appended as a HTTP query parameter.

  4. On your redirect pages, read the paymentRequestId query parameter and Get the Payment Request to confirm its status.

    • If the Payment Request is paid, you can show the customer the order confirmation page.
    • If the Payment Request is cancelled or expired, the payment was not completed.
    • If the Payment Request is still new, the payment was not completed and 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. 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.

Interface Guidelines

Use the Centrapay Logos when building the UI for Centrapay payments. If you need Centrapay colours for your design, use the Centrapay brand orange.

Option Title

The title of the payment option can only be Centrapay, with no extra content. If your website uses the same wording for all payment options, you can follow it, for example Pay with Centrapay.

A checkout page with Centrapay as the payment option title

Display the Centrapay brand logo so customers can easily recognise it. Depending on your website's design and layout, you can:

  1. Use the full brand logo as the option title.

    A checkout payment option using the full Centrapay logo as its title

  2. Display the Centrapay mark logo as a supplementary element.

    A checkout payment option with the Centrapay mark logo next to its title

  3. Show the full brand logo in the expanded section of the option.

    A checkout payment option with the full Centrapay logo in its expanded section

Payment Method Icons (If Applicable)

Choose a size and placement for the payment method logos that suits your page design and layout, for example:

  1. To the right of the payment option.

    Payment method icons to the right of the Centrapay payment option

  2. Inside the expanded option body.

    Payment method icons inside the expanded Centrapay payment option

Centrapay Introduction (If Applicable)

If needed, add a brief description below Centrapay, or a link to centrapay.com for customers to learn more.

A short Centrapay description below the payment option

Payment Button

Choose a button style that matches your website's design. Don't render the button with the Centrapay logo in other colours.

Pay with Centrapay button styles