Production implementation date: 20th August 2025

PayID Payments

Overview

PayID is a real-time payment system that allows customers to make instant payments using a unique PayID identifier. The PayAdvantage API provides comprehensive PayID functionality including creating PayIDs, managing payment requests with PayID options, and handling customer PayID references.

API Changes

PayID Endpoints

POST /pay_ids - Creates a new PayID payment request for a customer.
GET /pay_ids - Returns a paginated list of PayIDs, with optional filters for date, amount, status, and PayID value.
GET /pay_ids/{code} - Returns details for a specific PayID, including status, amounts, customer, and payment history.

Example Request:

{
  "amount": 100.00,
  "description": "Payment for services rendered",
  "onchargeFees": false,
  "externalID": "EXT123456",
  "customer": {
    "code": "CUST123456"
  },
  "persistent": true
}```

Example response:

{
  "code": "ABC123",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateExpires": "2024-01-22T10:30:00Z",
  "description": "Payment for services rendered",
  "externalID": "EXT123456",
  "amount": 100.00,
  "amountIncFees": 102.00,
  "onchargeFees": false,
  "customer": {
    "code": "CUST123456"
  },
  "paymentRequests": [
    {
      "code": "PR123456"
    }
  ],
  "payID": "unique-payid-123@merchant.payadvantage.com.au",
  "status": "pending",
  "payments": []
}

PayID Status Lifecycle

Status	Description
pending	PayID created, awaiting first payment
waiting	PayID active and ready for payments
complete	Payment received and processed
expired	PayID expired without successful payment
return_in_progress	Refund initiated
return_complete	Refund completed successfully
return_rejected	Refund was rejected

Expiry:

Default expiry is 25 hours from creation
Persistent PayIDs (persistent: true) do not expire

Webhooks for PayID Events

PayID-related webhooks include:

payment.created
payment.settled
payment.failed
refund.created
refund.processed
refund.failed

All webhooks include authentication headers for signature verification and follow the standard retry policy.

Error Handling

Common error responses include:

400 invalid_request – Request validation failed
404 not_found – Resource not found
422 payid_not_enabled – PayID not enabled for merchant

Web Application Enhancements

PayID option in payment request creation – When creating payment requests in the web UI, PayID is now available as a payment method.
PayID in customer details – Persistent PayIDs (if generated) are displayed in the customer’s profile.
PayID search – Search for PayIDs in the PayIDs tab, with filtering options matching the API.
Status tracking – PayID statuses are displayed in the UI, matching the lifecycle stages in the API.

Backward Compatibility

Existing payment request and customer creation endpoints remain unchanged.
PayID-related features are optional; merchants not using PayID will see no changes in workflow.

Customer External ID & Customer Ref Support

Overview

This update ensures that all customer-related API responses consistently return the Customer External ID and Customer Ref fields. These identifiers allow to better reconcile customer data between Pay Advantage and your own systems.

API Changes

Updated Endpoints

The following endpoints now return externalID and CustomerRef as part of the customer object:

POST /direct_debits – Returns the customer’s External ID and Customer Ref when creating direct debits.
GET /direct_debits – Supports searching by Direct Debit Reference and includes External ID and Customer Ref in responses.
GET /direct_debits/{code} – Returns populated External ID and Customer Ref.
GET /webapp/receipts/{code} – Customer details now include External ID and Customer Ref.
GET /webapp/hosted-receipt/{code} – Customer details now include External ID and Customer Ref.
GET /refunds – Customer details now include External ID and Customer Ref.

Example response:

{
  "code": "DD123456",
  "status": "pending",
  "amount": 150.00,
  "customer": {
    "code": "CUST123456",
		"name": "John Smith",
    "externalID": "EXT7890",
    "customerRef": "REF001"
  }
}

Consistency & Null Values

If no values are set for these fields, the API will return null.

Backward Compatibility

These fields are additive and optional.
Existing integrations that do not use externalID or customerRef remain unaffected.

Payment status

The API response now includes the payment status, allowing merchants to easily see whether a payment is pending, processed, or settled.

More information on payment statuses can be found here: https://docs.payadvantage.com.au/docs/payment-statuses