PayUI Tokenisation

PayUI supports secure payment instrument tokenisation, enabling you to store customer payment instruments for future transactions while maintaining PCI compliance. This guide explains how to create and manage tokenised payment instruments during the payment flow, with customer consent.

Overview

Tokenisation allows you to capture customer’s payment details. PayUI captures the customer’s payment instrument information, creates a customer record and payment instrument on your behalf, and returns resource identifiers you can use for subsequent transactions.

Tokenisation occurs transparently within the PayUI iframe — your application never handles raw card data, reducing PCI scope while still giving you the ability to process future recurring or customer-initiated transactions.

Note: Not available for wallets.

How It Works

When you include customerRequest in your Payment Request with paymentInstrument: create, PayUI will:

1. Collect payment instruments details from the customer in the secure iframe
2. Capture the payment instrument and process the transaction
3. Return the transaction and customer and payment instrument identifiers in customerResult in the transaction response

The customer and payment instrument are created only when paymentInstrument: create is explicitly provided.

Integration Steps

Step 1: Create Payment Request with CustomerRequest

Include customerRequest in your Payment Request creation call when you want to tokenise the customer’s card.

Endpoint: POST /paymentrequests

Request with New Customer (tokenisation):

{
    "reference": "ORDER-2026-001",
    "payment": {
        "amount": 5000,
        "currencyCode": "AUD",
        "description": "Subscription - Premium Plan"
    },
    "paymentMethods": ["card"],
    "transactionRequest": {
        "category": {
            "frequency": "single",
            "captureType": "auto"
        }
    },
    "customerRequest": {
        "paymentInstrument": "create",
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
    }
}

Request without paymentInstrument action (no tokenisation):

If the paymentInstrument is omitted, no payment instrument is created:

{
    "reference": "ORDER-2026-002",
    "payment": {
        "amount": 2500,
        "currencyCode": "AUD",
        "description": "One-time purchase"
    },
    "paymentMethods": ["card"],
    "transactionRequest": {
        "category": {
            "frequency": "single",
            "captureType": "auto"
        }
    },
    "customerRequest": {
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
    }
}

Response (excerpt):

{
    "id": "zWIEEs6BBU2A3GUQ8gD3Ag",
    "reference": "ORDER-2026-001",
    "createdDateTime": "2026-02-09T10:15:00Z",
    "paymentRequestStatus": "created"
}

Step 2: Generate One-Time Token

Generate a one-time token as normal for PayUI integration:

Endpoint: POST /tokens

{
    "scope": "payui",
    "paymentRequestId": "zWIEEs6BBU2A3GUQ8gD3Ag"
}

Step 3: Initialise PayUI

Initialise PayUI with the one-time token. The tokenisation happens automatically when the customer completes payment:

const config = {
    token: "your-one-time-token",
    containerId: "payment-container",
    version: "1.0.0"
};

const payUI = GPAUNZ.PayUI.initialise(config);

payUI.on('process', (payload) => {
    if (payload.result.status === 'approved') {
        console.log('Payment approved. Transaction ID:', payload.transactionId);
        // Tokenisation happens automatically server-side
        // Retrieve customerResult via webhook
    }
});

Step 4: Retrieve Tokenisation Result

After a transaction, retrieve the customerResult containing the customer and payment instrument identifiers.

Webhooks (Recommended)

If subsrcribed to the payment_requests webhooks, listen for payment request webhooks to capture the final state with customerResult:

{
    "id": "zWIEEs6BBU2A3GUQ8gD3Ag",
    "eventType": "payment_requests",
    "created" : "2026-01-27T06:26:02Z",
    "version": "1.0.0",
    "payload" : {
                    "id": "szh-Ib8xP0S_sJZn8xD8yQ",
                    "reference": "ORDER-723-669-1900",
                    "createdDateTime": "2026-01-27T06:25:59Z",
                    "updatedDateTime": "2026-01-27T06:26:43Z",
                    "expiryDateTime": "2026-01-29T06:25:59Z",
                    "paymentRequestStatus": "completed",
                    "transactionResult": {
                        "id": "Iank9maLpkuwlQWGJ4rYcw",
                        "location": "https://api.gpaunz.com/transactions/Iank9maLpkuwlQWGJ4rYcw"
                    },
                    "customerResult": {
                        "id": "Iank9maLpkuwlQWGJ4rYcw",
                        "location": "https://api.gpaunz.com/customers/Iank9maLpkuwlQWGJ4rYcw",
                        "paymentInstrumentId": "JMFEgR2z5EGL7GF7lAcFxA",
                        "paymentInstrumentLocation": "https://api.gpaunz.com/customers/Iank9maLpkuwlQWGJ4rYcw/paymentinstruments/JMFEgR2z5EGL7GF7lAcFxA"
                    },
                    "payment": {
                        "description": "i'm a description",
                        "amount": 100,
                        "currencyCode": "AUD"
                    },
                    "paymentMethods": [
                        "card"
                    ],
                    "result": {
                        "mode": "sandbox",
                        "status": "ok"
                }
        }
}

Store the customerResult.id and customerResult.paymentInstrumentId in your database to use for future transactions.

Tokenisation Flow (Sequence Diagram)

This diagram illustrates the complete tokenisation flow from Payment Request creation through to customer and payment instrument creation:

sequenceDiagram
    autonumber
    participant FrontEnd
    participant Merchant Server
    participant Single API
    participant PayUI

    FrontEnd->>Merchant Server: Request payment page
    Merchant Server->>Single API: POST /paymentrequests
    Single API-->>Merchant Server: Payment Request ID
    Merchant Server->>Single API: POST /tokens (scope=payui and paymentrequestid)
    Single API-->>Merchant Server: One-Time Token (OTT)
    Merchant Server-->>FrontEnd: Render page with token
    FrontEnd->>PayUI: Load payui.js
    FrontEnd->>PayUI: GPAUNZ.PayUI.initialise(OTT)
    PayUI-->>FrontEnd: Render iframe + emit 'initialise'
    FrontEnd->>FrontEnd: User enters card details
    PayUI-->>FrontEnd: Emit 'surchargeUpdate' (if enabled)
    FrontEnd->>PayUI: User clicks Pay Now
    PayUI->>Single API: POST /customers<br/>(name, email from customerRequest)
    PayUI->>Single API: POST /customers/{id}/paymentinstruments<br/>(card token from PayUI)    
    Single API->>PayUI: Return customer and payment instrument
    PayUI->>Single API: Create transaction with customer and payment instrument
    Single API-->>PayUI: Transaction Result and <br/> PaymentRequest state change
    Single API-->>FrontEnd: Emit 'process' event
    FrontEnd->>FrontEnd: Display Processing Result
    Single API-->>Merchant Server: Transaction Webhook
    Single API-->>Merchant Server: Payment Request Webhook

CustomerRequest Properties

The customerRequest object controls tokenisation behaviour:

Property	Type	Required	Description
paymentInstrument	string	No	Set to "create" to create a payment instrument. If omitted, no payment instrument is created.
name	string	No	Customer name. Cannot be used with id. Optional when creating a new customer.
email	string	No	Customer email. Cannot be used with id. Optional when creating a new customer.

CustomerResult Properties

When tokenisation succeeds, customerResult is populated in the Payment Request response:

Property	Type	Description
id	string	The unique customer identifier.
location	string	The full URL to the customer resource.
paymentInstrumentId	string	The unique payment instrument identifier.
paymentInstrumentLocation	string	The full URL to the payment instrument resource.

Validation Rules

PayUI validates customerRequest to ensure data consistency:

Identity Rules

• Creating a new customer:
  When creating a new customer, you can provide name or email, both optional but recommended. The name can be completed from the PayUi form or else it will be defaulted to VALUED CARDHOLDER.

Payment Instrument Creation

• Explicit opt-in required:
  Payment instruments are only created when paymentInstrument: create is explicitly included in customerRequest.

• Without paymentInstrument: create:
  If you omit paymentInstrument or set it to any other value, no payment instrument will be created.

Example Validation Errors

Validation errors

Code	Message	Reason
V10214	payment_request_customer_id_invalid	the provided customer id is invalid
V10215	payment_request_customer_email_invalid	The email is either invalid format (valid email, lenght) or was provided in conjuction with id
V10216	payment_request_customer_name_invalid	The customer name is either an invalid format or was provided in conjuction with id
V10219	payment_request_customer_paymentinstrument_invalid	payment instrument action is one of the allowed values

Using Tokenised Payment Instruments

Once you have stored the customer ID and payment instrument ID, you can use them for future transactions via the standard Transactions API:

Endpoint: POST /transactions

{
    "reference": "RECURRING-2026-001",
    "category": {
        "origin": "internet",
        "frequency": "recurring",
        "captureType": "auto"
    },
    "payment": {
        "amount": 5000,
        "currencyCode": "AUD",
        "instrument": {
            "customer": {
                "id": "e945e8vh0a9szsxig9pohvs9i3lrmw",
                "paymentInstrumentId": "JMFEgR2z5EGL7GF7lAcFxA",
                "cvn": "123"
            }
        }
    }
}

Note: Including cvn for recurring transactions may improve approval rates and is recommended when available.

Managing Tokenised Instruments

You can manage customer and payment instrument records using the standard API endpoints:

• Retrieve a customer: GET /customers/{customerId}
• Update a customer: PUT /customers/{customerId}
• List payment instruments: GET /customers/{customerId}/paymentinstruments
• Retrieve a payment instrument: GET /customers/{customerId}/paymentinstruments/{paymentInstrumentId}
• Update a payment instrument: PUT /customers/{customerId}/paymentinstruments/{paymentInstrumentId}
• Delete a payment instrument: DELETE /customers/{customerId}/paymentinstruments/{paymentInstrumentId}

For complete documentation on customer and payment instrument management, see the API reference.

Best Practices

Testing

Test tokenisation in the sandbox environment:

1. Create a Payment Request with customerRequest including paymentInstrument: create
2. Complete the payment using sandbox test card numbers
3. Verify customerResult is populated with customer and payment instrument IDs
4. Test subsequent transactions using the tokenised payment instrument

For sandbox card numbers and testing scenarios, see Testing Introduction.

Troubleshooting

customerResult is null or missing when trying to tokenise

• Verify paymentInstrument: create was included in customerRequest

Payment instrument not created

• Ensure paymentInstrument: create is explicitly included in customerRequest
• Omitting this field or using any other value will prevent payment instrument creation

Subsequent transactions fail with tokenised instrument

• Verify the customerId and paymentInstrumentId are correct
• Check that frequency: recurring is set for recurring transactions
• Include cvn when available to improve approval rates

Related Resources

• PayUI Overview
• PayUI Integration Guide
• PayUI Examples
• Webhooks Documentation
• Testing Introduction