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": "[email protected]",
  "status": "pending",
  "payments": []
}

PayID Status Lifecycle

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