Linked Customers

A customer has to be linked to a merchant before they trade with that merchant. That link is a CML (Customer Merchant Link). Each customer has a dedicated, static customer reference, and you use that reference for every payment.

Generally you create the CML through the Merchant API, which is what this page covers. A CML can also be created in the merchant portal, or by the customer signing up.

This page follows one flow:

1. Create the customer with POST /v2/customers as a one-off customer, giving a payment method.
2. Store the customerReference you chose.
3. Charge the customer at will with POST /v2/payments, using that reference.

Every request below carries the credentials described in Authentication.

Create the customer

Make a POST request to /v2/customers. See Create a customer for every field.

Set paymentOption to 28 (OneOff). Choose a customerReference that is unique to this customer. The reference is yours to provide, and it stays the same for every payment.

Required fields

The spec requires these fields:

• customerReference
• firstName
• lastName
• email
• mobile
• dateOfBirth
• paymentOption
• paymentAmount
• paymentFrequency
• paymentStartDate
• notificationMethod

The server also refuses a create that has no address, or no payment method, even though the spec marks both as optional. An address needs address1, suburb, state, country and postcode. The payment method is one of the three below.

Give the payment method

Send the payment method in the create request, in one of three ways.

Bank details

For a bank customer, pass the bank details directly in bankAccount. bsb, accountNumber and accountName are required.

Example request

POST /v2/customers

{
  "customerReference": "cust-1001",
  "firstName": "Test",
  "lastName": "Customer",
  "email": "test@zenpay.com.au",
  "mobile": "0400000000",
  "dateOfBirth": "1999-05-08T14:20:58",
  "notificationMethod": 0,
  "paymentOption": 28,
  "paymentFrequency": 34,
  "paymentAmount": 1,
  "paymentStartDate": "2026-12-09T14:20:58",
  "address": {
    "address1": "1 Test Street",
    "suburb": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country": "AU"
  },
  "bankAccount": {
    "bsb": "062000",
    "accountNumber": "12345678",
    "accountName": "Test Customer"
  },
  "sendWelcomeEmail": false
}

A successful create returns 201 with the created customer in the body. For a one-off customer the sandbox stored paymentAmount as 0 and paymentStartDate as the day the customer was created, whatever the request sent.

A card token from the cardproxies API

A merchant or integrator with the right PCI level and certifications can turn a card into a token with POST /v2/cardproxies. Pass cardNumber and expiry. See Create a card proxy for every field.

Example request

POST /v2/cardproxies

{
  "cardHolderName": "Test Cardholder",
  "cardNumber": "5555555555554444",
  "expiry": "12/29"
}

The response returns the token in cardProxy. Pass it in card.cardProxy when you create the customer, in place of bankAccount:

{
  "card": {
    "cardProxy": "your-card-proxy-token"
  }
}

A card token from Hosted Checkout

If you do not have the PCI level and certifications for the cardproxies API, tokenise the card with the Hosted Checkout plugin in mode 1 (Tokenise). See Operating modes for what the mode does, and Tokenise result (mode 1) for the callback that returns the token.

Pass that token in paymentAccountProxy.proxy when you create the customer, in place of bankAccount:

{
  "paymentAccountProxy": {
    "proxy": "your-hosted-checkout-token"
  }
}

Charge the customer

Once the customer exists, you charge them whenever you choose. Make a POST request to /v2/payments with the customerReference. The customer's stored payment method is charged. See Create a payment for every field.

The spec requires customerReference, paymentAmount and overrideFeePayer. Treat customerEmail, customerName and merchantUniquePaymentId as required too, as described in Token payments.

Example request

POST /v2/payments

{
  "customerReference": "cust-1001",
  "paymentAmount": 1,
  "overrideFeePayer": 2,
  "customerEmail": "test@zenpay.com.au",
  "customerName": "Test Customer",
  "merchantUniquePaymentId": "pay-1001",
  "sendPaymentConfirmation": false
}

Example response (some fields left out)

{
  "paymentReference": "251276",
  "customerReference": "cust-1001",
  "paymentStatus": "Successful",
  "baseAmount": 1,
  "customerFee": 0.05,
  "merchantFee": 0,
  "paymentAmount": 1.05,
  "accountOrCardNo": "*****678",
  "paymentAccount": "BankAccount",
  "merchantUniquePaymentId": "pay-1001",
  "paymentSourceDisplay": "Api Tokenised Payment",
  "customerCode": "BB11226984"
}

The customer's bank account was charged. With overrideFeePayer set to 2 the customer paid the fee, so paymentAmount is baseAmount plus customerFee.

For the paymentStatus codes, see Status Codes.