Online EFTPOS Integration Guide

API Overview ¶

Our API provides a set of endpoints to enable secure and reliable payment processing. Below is a high-level summary of the key endpoints required for integration.

Open API Specification ¶

Please refer to the Open API Sepcification file for a complete API definition including request schema definition.

Download Open API Specification (Swagger file)

Note:

• Ensure your integration is configured to include the correct API version in the base URL.

• Example v2 in /oe/transactions/v2/payments/create-intent.

Authentication ¶

Payments ¶

Refunds ¶

Generate API Key and Secret ¶

Go to the Integration page in the portal and generate your API key and secret. You will use these credentials to obtain a Bearer Token for making server-to-server calls from your website’s backend to our APIs.

Authentication ¶

All requests to our API must be authenticated using a Bearer Token provided in the Authorization HTTP header. This token-based mechanism allows you to access and use our APIs. Our server will validate this token before continuing to process your request.

To obtain a Bearer Token you must exchange your API Key and Secret with our authorisation server. These credentials can be generated from the Integration page in the Merchant Portal.

Step-by-Step Process ¶

1. Generate a Basic Authorization Token
   Concatenate your API Key and API Secret with a colon (:) separator:

APIKey:APISecret

Then, base64 encode this string. This becomes your Basic Authorization Token.

2. Request a Bearer Token
   Make a POST request to the token endpoint using the Basic Authorization Token in the Authorization header, and include grant_type=client_credentials in the request body.

Create Payment Intents ¶

First step in the payment flow is to create a payment intent. A payment intent captures the details for the payment and indicates to us that you have a customer who is wanting to pay for some goods or service.

The create payment intent call must be made by your back-end server, supplying the Bearer Token you obtained in the previous step. This is to ensure that the payment intent details are created in a secure manner and free from tampering through the front-end.

The key information to send in the create payment intent request will be the amount you are wanting to charge your customer, your merchantId, and also the reference and description (optional) for the payment.

Hosted Page Integration ¶

When using the Hosted Page integration, you will only need to redirect your customer to the paymentUrl received in the response of the create payment intent request.

There, they will be able to complete the payment. Upon completing the payment the customer will be redirected back to your website through the redirectUrl supplied in the create payment intent request.

Please refer to Receive Payment Status for how to retrieve the processed payment’s details.

Custom Page Integration ¶

For Custom Page integration you will need to embed the payment plugin in your checkout page. To render the plugin, you’ll need to use the paymentId returned from the create payment intent API response. The plugin is loaded into your page via a script tag and mounted to a container element of your choosing.

Embed the Plugin ¶

This section outlines how to embed the plugin, initialise it, and handle key lifecycle events to guide your customer through the payment process.

Update Content Security Policy (CSP)
Ensure seamless integration of the embedded plugin by including the following mandatory Content Security Policy directive in your payment page:

Content-Security-Policy: frame-src *;

Add Target Div and Add JavaScript
Place the following HTML where you want the plugin to render (e.g., checkout form, modal, or sidebar):

<!-- Primary Embed Container (Required) -->
<div id="plugin-container" class="plugin-embed">
  <!-- Plugin will load here dynamically -->
</div>

Add the following HTML if you wish to use your own custom Next button:

<button id="nextBtn">Next</button>

Include the plugin script:

<script src="https://open.demo.worldline.co.nz/plugin.js"></script>

Initialise Plugin ¶

Initialize the plugin using a paymentId from the URL and bind the Next button:

Required fields:

• elementId (string):
  The ID of the HTML element that will be replaced by the plugin UI.

• paymentId (string):
  The unique ID returned when creating the payment intent.

• merchantUrl (string):
  The merchant’s URL - this should match the merchant.url used when the payment intent was created.

• hasCustomButton (boolean):
  Set to true if you’re providing your own custom button to trigger the plugin’s submission (e.g., a “Next” or “Submit” button). If false, the plugin will render its own default button.

<script>
    window.addEventListener("load", () => {
        const nextBtn = document.getElementById("nextBtn");
        const divContainer = document.getElementById("divId");
        const urlParams = new URLSearchParams(window.location.search);
        const paymentId = urlParams.get("paymentId");
        const merchantUrl = urlParams.get("merchantUrl");
        // ✅ Initialize plugin
        window.plugin.init({
            elementId: "divId",
            paymentId: paymentId,
            merchantUrl: merchantUrl,
            hasCustomButton: true,
        });
        // ✅ Submit handler
        nextBtn.addEventListener("click", (e) => {
            window.plugin.submit(e);
        });
    });
</script>

Plugin API Reference ¶

Below is a detailed breakdown of the plugin methods and supported configuration parameters. Always ensure window.plugin is available before calling any methods.

Supported init(config) Parameters

Events ¶

If you’re using the Custom Page integration, your system can listen for payment lifecycle events emitted directly by the plugin. These events notify your application in real time when the payment reaches key states, including when a payment is processed. These notifications allow you to dynamically update the UI to create an optimal customer experience.

Plugin event listening is only available for a Custom Page integration. If you are using a Hosted Page integration, you must use webhook notifications or poll the API.

Considerations ¶

• Events are useful for internal logic and feedback loops but are not a substitute for verifying the processed payment outcome via webhook notification or polling

• Ensure your event handlers are resilient to retries, deduplicated, and error-tolerant.

Event Types The plugin emits the following events:

1. payment_bank_selector – Triggered when the user interacts with the bank selector.
2. payment_input – Triggered when the user enteres mobile number, will return if number is valid or not.
3. payment_status – Provides the current status of the payment. The data.status field will contain one of the following:
   • SUBMITTED - The payment has been submitted to the customer’s bank app for authorisation
   • AUTHORISED - The payment has been AUTHORISED
   • ERROR - An error has occured in the payment process
   • NEW - Plugin awaiting customer’s payment details
   • DECLINED - The payment was declined
   • EXPIRED - The payment expired

Implementation Example (React) ¶

import { useEffect } from "react";
import { useRouter } from "next/router";
import {
  PaymentEvent,
  PaymentEventType,
  PaymentStatus,
} from "./types"; // adjust the import path as needed

const PaymentListener = ({
  setPaymentSessionStarted,
  setPaymentSubmitted,
  setShowPaymentButton,
  setShowRestartButton,
  setPaymentFailed,
}) => {
  const router = useRouter();

  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      const message = event.data as PaymentEvent;

      if (!message?.event) return;

      switch (message.event) {
        case PaymentEventType.paymentStatus:
          switch (message.data.status) {
            case "SUBMITTED":
              setPaymentSessionStarted(true);
              setPaymentSubmitted(true);
              break;
            case "AUTHORISED":
              if (message.data?.type === "REDIRECT" && message.data.redirectUrl) {
                router.push(message.data.redirectUrl);
              }
              break;
            case "EXPIRED":
              setShowPaymentButton(false);
              setShowRestartButton(true);
              break;
            case "DECLINED":
            case "ERROR":
              setPaymentFailed(true);
              break;
          }
          break;

        case PaymentEventType.paymentBankSelector:
          // Handle bank selector logic here if needed
          break;

        case PaymentEventType.paymentInput:
          // Handle input interaction if needed
          break;

        default:
          break;
      }
    };

    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, []);

  return null;
};

Receive Payment Status ¶

When a payment reaches a processed state (e.g. AUTHORISED, DECLINED, ERROR, EXPIRED), your system can be notified or you can retrieve the processed status using the following methods:

1. Webhook Notification (Recommended):
   We send a callback to your notificationUrl with a signed JWT containing the payment details.

2. GET oe/transactions/v2/payment/{paymentId}:
   You can poll our API to check the current status of the payment by its ID.

We recommend webhook notifications as the primary and most secure way to receive real-time status updates, with the other two methods serving as fallbacks or for specific platform needs.

Webhook Notification ¶

This is the main mechanism to rely on for receiving updates about the status of a payment. Once a payment is processed, we will send an HTTP callback (webhook) to the notificationUrl you provided when creating the payment intent.

This callback contains a JSON Web Token (JWT) in the body, which includes a claim with the details of the payment (e.g., paymentId, status, transactionTime, etc).

The JWT is digitally signed using our private key to ensure the integrity and authenticity of the callback. You must verify the signature of the JWT using our published JSON Web Key Set (JWKS).

This helps ensure:

• The message is authentic (sent by Worldline).

• The contents have not been tampered with.

• The JWT is valid (not expired, and matches the expected claims).

Download Notification JWT Sample

How to Verify the JWT

1. Fetch the JWKS
   We publish our public keys at the following endpoint:

https://apitest.paymark.nz/worldlinejwks/OETransaction

Sample response:

{
  "keys": [
    {
      "crv": "P-521",
      "kid": "5322fb2d-0580-4122-b23b-5e3055bac347",
      "kty": "EC",
      "x": "AXbhzIBbyax0GicdVl_HAaJi-b9nkkMDhGmtObXXwx48D_Evnt3G7BVgeU-98L8f1o3u4Olxc-kN-PlrwzH-T5ee",
      "y": "AIj6gTTj0Qo9i5f2CA583hjwfjyf6YeZXyWXCY8M_T_hGsQiwGYybB_nC30QN1fgYaePpWY3-iTsgCjQ4B71K6YI"
    }
  ]
}

2. Decode the JWT
   Extract the algorithm (alg) and key ID (kid)

3. Select the Right Public Key
   Use the kid (Key ID) field in the JWT header to find the matching key in the JWKS. You’ll use that key to verify the signature.

4. Verify the Signature
   Use a JWT library that supports the algorithm. Supply:

• The raw JWT.

• The public key from the JWKS.

• Optionally: expected claims (iss, aud, etc.).

Polling ¶

Polling should only be performed:

• As a fallback if your notification server is down or delayed as part of your clean up process.

• For manual status checks, retries, or debugging.

If you decide to poll the API for processed payment status, we recommend the following best practices:

• Start polling only after the payment has been created and you are awaiting a processed payment.

• Poll using our recommended strategy else, with exponential backoff or fixed intervals — e.g. every 10 seconds initially, gradually increasing to 20-30 seconds.

• Stop polling once a final status is received:

  • AUTHORISED, DECLINED, EXPIRED, or ERROR

• Timeout gracefully after a max polling duration (e.g., 2-5 minutes) to avoid indefinite loops.

• Respect API rate limits — high-frequency polling could lead to throttling or errors.

Polling should be used sparingly. When possible, rely on webhook notifications as your primary integration path.

Recommended Polling Strategy
To efficiently check for a processed payment status without overloading the system, we recommend the following polling intervals:

• Start polling 60 seconds after the payment is created.

• Poll every 10 seconds for the next 60 seconds.

• Then, poll every 20 seconds for the next 60 seconds.

• Then, poll every 30 seconds for the next 120 seconds.

• After that, poll every 45 seconds until a processed payment status is received (AUTHORISED, DECLINED, ERROR, or EXPIRED).

Polling via GET /oe/transactions/v2/payments/{paymentId}
You can actively retrieve the latest status of a payment by making a GET request to the payment endpoint using its paymentId.

Make a Refund ¶

You can refund a payment using one of two methods:

1. Merchant Portal – For manual or customer-service driven refunds.
2. Refund API – For programmatic refunds as part of your integration flow.

When issuing a refund, note the following:

• Refunds are only allowed on payments that have an AUTHORISED or REFUNDED (if payment has been partially refunded) status.

• You can perform full or partial refunds by specifying the amount.

• The refund request is processed immediately, and the response includes the final result.

• Refunds will settle overnight into your customers account.

Merchant Portal ¶

The merchant portal provides an easy-to-use interface for initiating refunds without requiring code.

How to Refund

1. Log in to the Merchant Portal
2. Navigate to the Transactions page.
3. Locate and select the payment you want to refund.
4. Click Refund and confirm the amount and an optional description.
5. Submit the request.

Features:

• Refund status is tracked in the Merchant Portal.

• Ideal for manual workflows, customer support, or when you don’t want to handle refunds programmatically.

Refund API ¶

Test Scenarios ¶

Environment URLs ¶

Refer to the table below for configuring your systems to use the desired environments.

Merchant Portal Overview ¶

The Merchant Portal is your central dashboard for managing day-to-day payment operations, team access, and account settings. It’s designed to give you visibility and control over transactions, user permissions, and business reporting — all in one place.

Whether you’re a single-store merchant or part of a larger, multi-level organisation, the portal supports flexible account structures and access levels to match your business needs.

User Roles and Access Control ¶

Access to data in the portal is controlled through role-based access control (RBAC). Give your team members the right role so they have the access they need.

Choose the level of access required for individual members based on the hierarchy table below. You may need a more privileged role with less restrictions to change your current role.

Admin Roles

View Only Role

Merchant Account Hierarchy ¶

Connect and manage your accounts with support for up to three levels of hierarchy.

If your organisation requires multiple levels of account management — for example, a head office overseeing regional offices, which in turn manage individual stores — a three-level structure may be suitable.

To set up a multi-level account structure, please consult with our sales team.

Hierarchy Levels

Note:

• A 2-level hierarchy involves a Root Parent (Top-Level) Account and one or more Child-Level Accounts directly beneath it.

• A 3-level hierarchy introduces Parent (Mid-Level) Accounts to group and manage multiple Child (Child-Level) Accounts.

Creating a New Account To create a new merchant account, please contact our Sales or Support team. They’ll guide you through the setup process and ensure your account is configured correctly.

Updating an Existing Account To update an existing account, reach out to our Support team with the field name(s) and the new information you’d like applied. They’ll assist you with making the necessary changes.

Portal Pages and Functions ¶

Use the navigation menu to access key sections of the merchant portal. Each page provides specific capabilities based on user roles.

Navigation Menu

Go Live ¶

Go-Live Checklist ¶

Below checklist is designed to assist in preparing your production integration to be ready for use by your customers. Perform these checks as your Go Live readiness check

• Production Account Configured

  • Apply for your production account by completing the Online EFTPOS Production Registration form. You can obtain a copy from our Sales team.
  • Your production API credentials (key and secret) have been generated and stored securely.
  • Portal users and account hierarchy (if applicable) are confirmed and configured.

• Integration Completed

  • Your production environment is fully configured with live API credentials and points to the production endpoints.
  • Payment intent creation and payment flow are working end-to-end as per your implemented integration mode.
  • Your system and checkout experience handles success scenarios and gracefully handles error scenarios.
  • Your reference field (max 12 characters) is unique to serve as an additional identifier to distinguish individual payments within your system.

• Payment Status Handling

  • Your notification URL is receiving and verifying payment notifications (JWTs).
  • Notification URL is publicly accessible.
  • Clean up process in place to use polling in the event of webhook notification failures.
  • With Custom Page integration, event listeners are used solely for managing visual UI cues and not for determining the final payment status.

• Refund Support

  • If refunding through the API, your system correctly handles refund responses.

• Testing Complete

  • Payment scenarios tested successfully in sandbox (AUTHORISED, DECLINED, EXPIRED, ERROR).
  • Payment status and refund flows validated.

• Ready for Production

  • Team is trained on portal access and support processes.
  • Final checklist reviewed with the Sales Team.