PayID Integration Guide

This page provides a step-by-step guide for integrating PayID Payment Requests into your application.

Prerequisites

Before integrating PayID, ensure:

• Your merchant account has PayID enabled. Contact support if your account does not have this feature.
• You have a valid API key for authentication.
• Your server is configured to receive webhook notifications from the API.

Integration Steps

Step 1: Create a PayID Payment Request

Call POST /paymentrequests with a payment.instrument.payId object to register a unique PayID for the transaction.

Endpoint: POST /paymentrequests

For complete field documentation, see Create a Payment Request.

Example Request:

{
  "reference": "HVolqMiv1kikVDL_pqtlMA",
  "externalReference": "INV-0000001",
  "expiryDateTime": "2026-12-31T23:59:59Z",
  "payment": {
    "amount": 1000,
    "description": "Payment for INV-0000001",
    "instrument": {
      "payId": {
        "type": "single",
        "value": "INV-0000001"
      }
    }
  }
}

Example Response:

{
  "reference": "HVolqMiv1kikVDL_pqtlMA",
  "externalReference": "INV-0000001",
  "id": "E1HKfn68Pkms5zsZsvKONwNw",
  "createdDateTime": "2026-01-27T10:15:00Z",
  "updatedDateTime": "2026-01-27T10:15:00Z",
  "expiryDateTime": "2026-12-31T23:59:59Z",
  "paymentRequestStatus": "created",
  "payment": {
    "description": "Payment for INV-0000001",
    "amount": 1000,
    "currencyCode": "AUD",
    "instrument": {
      "payId": {
        "type": "single",
        "email": "INV-0000001@pay.gpaunz.com"
      }
    }
  },
  "result": {
    "mode": "live",
    "status": "ok"
  }
}

The response includes payment.instrument.payId.email — this is the PayID value the customer uses to send the payment.

Step 2: Share the PayID with Your Customer

Present the generated payment.instrument.payId.email to the customer on your payment confirmation page or in your invoice/email. Instruct the customer to:

1. Open their banking app (any NPP-enabled bank).
2. Navigate to the Pay or Transfer section and select PayID as the destination type.
3. Enter the PayID value exactly as provided.
4. Enter the exact payment amount shown on their invoice.
5. Confirm the payment.

Important: The PayID is tied to a specific payment amount and expiry. Ensure the customer pays before the expiryDateTime.

Step 3: Receive Webhook Notifications

The API sends a payment_requests webhook each time the paymentRequestStatus changes. For a successful payment flow you will receive two notifications:

1. created — sent when the Payment Request is registered and the PayID is ready to receive payment.
2. completed — sent when the customer’s payment has been received and processed.

If your webhook endpoint is also subscribed to the transactions event, you will additionally receive a transaction created notification when the payment completes.

You must acknowledge each webhook with an HTTP 200 response. See the Webhooks guide for authentication and retry details.

Note: If a webhook is not received, you can always retrieve the current Payment Request status by polling the GET /paymentrequests/{id} endpoint described in Step 4.

Step 4: Retrieve the Final Status

Poll or query the Payment Request at any time using:

Endpoint: GET /paymentrequests/{id}

The paymentRequestStatus field reflects the current state:

Status	Meaning
created	Awaiting payment from the customer.
completed	Payment received successfully.
expired	No payment was received before expiryDateTime.
cancelled	The request was explicitly cancelled via the API.

Step 5: Handle Refunds (if required)

To refund a completed PayID Payment Request, call:

Endpoint: POST /transactions/{id}/refunds

The refund is processed asynchronously. Listen for a webhook notification with the updated refund status (pending → approved or declined).