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 Intent ¶

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.

1. 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 *;

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

3. Include the Plugin Script

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

4. Add Custom Buttons

For the Custom Page integration, you have the option to use your own buttons for triggering different functions in the plugin. This is so that you can use your own custom styling. Please refer to Custom Buttons for more information and how to use them.

Initialise Plugin ¶

Initialize the plugin supplying the necessary values for the parameters below:

Supported init(config) Parameters:

Additional Parameters for Trusted:
See Trusted for more information.

Example:

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

Custom Buttons ¶

The Custom integration lets you use your own buttons to trigger plugin functions, so you can style them to match your website’s design. There are two main sets of buttons you can supply — the Next/Pay button and the Navigate button. The Pay button and the Navigate button are only relevant for Trusted.

Next/Pay Button

These buttons are used to call the plugin.submit(event) method:

1. Next Button on the Bank Selection page

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

2. Pay Button on the Trust Selection page

<button id="payBtn">Pay ${amount.toFixed(2)}</button>

Navigate Button

These buttons are used to call the plugin.navigateTrusted(event) method:

1. Pay with a saved account button on the Bank Selection page.
2. Use another account button on the Trust Selection page.

<button id="navBtn">{label}</button>

Button Visibility

To control which buttons are shown or hidden in the plugin, use visibility flags when calling plugin.init(). These flags allow you to hide the default plugin buttons and replace them with your own custom buttons.

Example: Hide All Default Plugin Buttons

window.plugin.init({
  elementId: "plugin-container",
  paymentId: "c5192016-8cb4-4542-9eca-b65280ddfe1c",
  merchantUrl: window.location.origin,
  hasCustomButton: true,
  hasCustomTrustedButton: true,
  hasCustomTrustedNavigationButton: true
});

Example: Detect Which Custom Buttons to Show

Use plugin.getCustomPageSettings() and plugin.getPaymentStatus() to determine what buttons to render:

window.addEventListener("message", checkButtonVisibility);

function checkButtonVisibility() {
  const nextBtn = document.getElementById("nextBtn");
  const payBtn = document.getElementById("payBtn");
  const trustNavigateBtn = document.getElementById("trustNavigateBtn");
  
  const settings = window.plugin?.getCustomPageSettings?.();
  const status = window.plugin?.getPaymentStatus?.();
  
  if (!settings || !status) return;
  
  // Show Next only when showCustomButton is true
  nextBtn.style.display = settings.showCustomButton ? "inline-block" : "none";
  
  // Show Pay only when showCustomTrustedButton is true
  payBtn.style.display = settings.showCustomTrustedButton ? "inline-block" : "none";
  
  // Show Navigation if allowed
  trustNavigateBtn.style.display =
    settings.showCustomTrustedNavigationButton
      ? "inline-block"
      : "none";
  
  // Change Navigation text, showCustomTrustedButton can only be true in Trust Selection Page
  trustNavigateBtn.textContent = settings.showCustomTrustedButton
      ? "Use another account"
      : "Pay with a saved account";
}

Example: Trigger Plugin Actions from Custom Buttons

// Submit action (Next or Pay)
nextBtn.addEventListener("click", (e) => {
  window.plugin.submit(e);
});

payBtn.addEventListener("click", (e) => {
  window.plugin.submit(e);
});

// Navigate Trusted action
trustNavigateBtn.addEventListener("click", (e) => {
  window.plugin.navigateTrusted(e);
}

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
4. custom_page_settings – Return the settings to give context for rendering page elements.
   • showCustomButton – A flag that returns true if the Next button should be displayed for the Bank Selection page, or false if it should be hidden.
   • showCustomTrustedButton – A flag that returns true if the Pay button should be displayed for the Trust Selection page, or false if it should be hidden.
   • showCustomTrustedNavigationButton – A flag that returns true if the custom navigation button should be dispayed, false if it should be hidden.

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 ¶

Trusted ¶

Trusted by Online EFTPOS enables a quicker way to pay with Online EFTPOS.

Let your registered customers save you as a Trusted merchant so the next time they pay, they do not need to approve the request in their bank app!

Your registered customer must be logged in before beginning the payment process. For banks that support Trusted, a checkbox will appear in the plugin below the bank tiles, allowing customers to enable the Trusted feature. Once selected, the customer proceeds with the payment and approves the request in their banking app. After the payment is processed you will be saved as a Trusted merchant against their selected bank and account.

When your customer returns to make their next purchase, is logged in and selects Online EFTPOS as the payment method they will then see their saved Trust. If they pay with the saved Trust, it will automatically process the payment from their nominated bank account. There is no need to approve the request in their bank app.

Requirements ¶

In order to use this feature:

• Your merchant account with us must have this feature enabled.

• Your website or app must support a secure login for your customer before they checkout.

• Your customer must be logged in and you must supply your customer’s unique identifier in the trusted.merchantCustomerId field in create payment intent request.

• If using Custom Page integration, you must define your own buttons (Custom Buttons) or use the plugin’s default buttons.

Sample Request ¶

{
  "merchantTransactionId": "98102214-20f5-4fb9-a699-6574ca6771cb",
  "integrationMode": "CUSTOM",
  "merchant": {
    "url": "https://icecreamshop.demo.paymark.co.nz/open-checkout",
    "redirectUrl": "https://icecreamshop.demo.paymark.co.nz/open-checkout/redirect",
    "notificationUrl": "https://icecreamshop.demo.paymark.co.nz/open-checkout/notification"
  },
  "trusted": {
    "merchantCustomerId": "4b578882-6689-4261-98b9-01816e02918c"
  },
  "oepayment": {
    "amount": 1500,
    "currency": "NZD",
    "reference": "icecream0131"
  },
  "risk": {
    "userAgentInfo": {
      "userAgent": "Mozilla/5.0",
      "userIpAddress": "192.168.1.1",
      "userAgentType": "DESKTOP",
      "latitude": -36.8485,
      "longitude": 174.7633
    },
    "customerType": "CONSUMER",
    "serviceType": "ECOMMERCE_GOODS",
    "deliveryAddress": {
      "addressType": "DELIVERY_TO",
      "addressLine": [
        "88 Shortland Street",
        "CBD"
      ],
      "streetName": "Shortland St.",
      "buildingNumber": "18",
      "postCode": "1010",
      "townName": "Auckland",
      "countrySubDivision": "Auckland",
      "country": "NZ"
    }
  }
}

Note:
Response body is identical to Create Payment Intent

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.