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.

Table of Contents

1. PayID Endpoints
2. Payment Request with PayID
3. Customer Creation with PayID
4. PayID Status Lifecycle
5. Webhooks
6. Error Handling
7. Sandbox Testing

PayID Endpoints

Create PayID

Creates a new PayID payment request for a customer.

Endpoint: POST /pay_ids

Headers:

• Authorization: Bearer {your_access_token}
• Content-Type: application/json

Request Body:

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

Request Parameters:

• amount (required): Payment amount in AUD (decimal)
• description (required): Payment description (1-50 characters)
• onchargeFees (optional): Whether to charge fees to customer (boolean, default: false)
• externalID (optional): External system identifier (1-50 characters)
• customer (required): Customer code object
• persistent (optional): Whether PayID should be reusable (boolean, default: false)

Response (200 OK):

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

Get PayID List

Retrieves a paginated list of PayIDs with optional filtering.

Endpoint: GET /pay_ids

Query Parameters:

• page (optional): Page number (default: 1)
• per_page (optional): Items per page (default: 25, max: 100)
• sort (optional): Sort field (datecreated, amount)
• datecreated (optional): Filter by creation date (YYYY-MM-DD)
• datecreatedfrom (optional): Filter from creation date
• datecreatedto (optional): Filter to creation date
• dateexpires (optional): Filter by expiry date
• dateexpiresfrom (optional): Filter from expiry date
• dateexpiresto (optional): Filter to expiry date
• description (optional): Filter by description (partial match)
• amount (optional): Filter by exact amount
• amountfrom (optional): Filter from amount
• amountto (optional): Filter to amount
• payid (optional): Filter by PayID value

Response (200 OK):

{
  "Records": [
      {
          "Code": "366QXC",
          "DateCreated": "2025-08-11T14:25:34.777+10:00",
          "DateExpires": "2025-08-12T14:25:32.333+10:00",
          "Description": "PayID for customer NQ5Z8A",
          "ExternalID": null,
          "Amount": 0,
          "AmountIncFees": 0,
          "OnchargeFees": false,
          "Customer": {
              "Code": "NQ5Z8A"
            },
          "PayID": "[email protected]",
          "Status": "waiting",
          "Payments": null
        }
    ],
  "Meta": {
      "page": 0,
      "recs_per_page": 32767,
      "total_recs": 6
    }
}

Get Single PayID

Retrieves details of a specific PayID by its code.

Endpoint: GET /pay_ids/{code}

Path Parameters:

• code (required): PayID unique identifier

Response (200 OK):

{
  "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"
  },
  "payID": "[email protected]",
  "status": "complete",
  "payments": [
    {
      "code": "PAY123456",
      "amount": 100.00,
      "status": "succeeded",
      "dateCreated": "2024-01-15T11:00:00Z"
    }
  ]
}

Payment Request with PayID

You can create payment requests that include PayID as a payment option, allowing customers to choose from multiple payment methods.

Create Payment Request with PayID Option

Endpoint: POST /payment_requests

Request Body:

{
  "customer": {
    "code": "CUST123456"
  },
  "description": "Invoice payment",
  "amount": 250.00,
  "externalID": "INV-2024-001",
  "paymentOptions": ["credit-card", "payid", "bpay"],
  "onchargeFees": true,
  "expiryDays": 7,
  "sendInitialLink": true,
  "sendReminders": true
}

Key Parameters:

• paymentOptions: Array including "payid" to enable PayID payments
• sendInitialLink: Whether to send payment link to customer immediately
• sendReminders: Whether to send reminder notifications

Response (200 OK):

{
  "code": "PR123456",
  "customer": {
    "code": "CUST123456",
    "name": "John Smith"
  },
  "description": "Invoice payment",
  "amount": 250.00,
  "status": "active",
  "dateCreated": "2024-01-15T10:30:00Z",
  "dateExpires": "2024-01-22T10:30:00Z",
  "paymentOptions": ["credit-card", "payid", "bpay"],
  "links": [
    {
      "code": "LNK123456",
      "url": "https://pay.payadvantage.com.au/link/LNK123456",
      "dateExpires": "2024-01-22T10:30:00Z"
    }
  ]
}

Customer Creation with PayID

When creating customers, you can automatically generate a persistent PayID for them using the ?with=payidref parameter.

Create Customer with PayID Reference

Endpoint: POST /customers?with=payidref

Request Body:

{
  "name": "John Smith",
  "email": "[email protected]",
  "mobile": "+61412345678",
  "isConsumer": true,
  "address": {
    "line1": "123 Main Street",
    "city": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "countryID": 1
  },
  "externalID": "CRM-12345"
}

Response (201 Created):

{
  "code": "CUST123456",
  "name": "John Smith",
  "email": "[email protected]",
  "mobile": "+61412345678",
  "isConsumer": true,
  "dateCreated": "2024-01-15T10:30:00Z",
  "payID": "[email protected]",
  "address": {
    "line1": "123 Main Street",
    "city": "Sydney",
    "state": "NSW",
    "postcode": "2000"
  }
}

PayID Generation Rules:

• Persistent PayIDs (prefix p-): Reusable for multiple payments

These are setup against your PayID registration. Please contact support to make changes to this:

• Customer Reference: Uses customer's customRef field if available
• External ID: Uses customer's externalID field if available
• Unique: Falls back to unique generated code if other fields unavailable

PayID Status Lifecycle

PayIDs progress through several status states during their lifecycle:

Status Values

Status Flow

pending → waiting → complete
    ↓         ↓
  expired   expired
    
complete → return_in_progress → return_complete
                ↓
         return_rejected

Expiry Behavior

• PayIDs automatically expire after their dateExpires time
• Default expiry is 25 hours from creation
• Expired PayIDs cannot receive payments
• Status changes from waiting to expired
• Please note - Persistent PayIDs do not expire.

Webhooks

PayAdvantage sends webhook notifications for various PayID events. Configure webhook endpoints in your merchant portal.

Webhook Events

payment.created

Triggered when a PayID payment is successfully initiated.

{
  "event": "payment.created",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": { 'this will contain the webhook data'  }
}

payment.settled

Triggered when PayID payment funds are settled to your account.

{
  "event": "payment.settled",
  "timestamp": "2024-01-15T14:00:00Z",
  "data": { 'this will contain the webhook data'  }
}

payment.failed

Triggered when PayID payment fails (e.g., incorrect amount paid).

{
  "event": "payment.failed",
  "timestamp": "2024-01-15T11:30:00Z",
  "data": { 'this will contain the webhook data'  }
}

refund.created

Triggered when a PayID refund is initiated.

Webhook Configuration

1. Endpoint Setup: Configure webhook URLs in your merchant portal
2. Authentication: Webhooks include signature headers for verification

Please visit https://docs.payadvantage.com.au/reference/webhooks_recent for further refernce on webhooks.

Error Handling

Common Error Responses

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Amount must be at least $1.00.",
  }
}

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "Customer could not be found.",
  }
}

422 Unprocessable Entity

{
  "error": {
    "code": "business_rule_violation",
    "message": "PayID is not enabled for this merchant.",
  }
}

Error Codes

Integration Examples

Basic PayID Creation Flow

// 1. Create customer with PayID
const customer = await fetch('/customers?with=payidref', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Smith',
    email: '[email protected]',
    mobile: '+61412345678',
    isConsumer: true
  })
});

// 2. Create PayID payment request
const payidRequest = await fetch('/pay_ids', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer: { code: customer.code },
    amount: 100.00,
    description: 'Service payment',
    persistent: false
  })
});

// 3. Monitor via webhooks or polling
const payidStatus = await fetch(`/pay_ids/${payidRequest.code}`);

Payment Request with Multiple Options

const paymentRequest = await fetch('/payment_requests', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer: { code: 'CUST123456' },
    description: 'Invoice #12345',
    amount: 250.00,
    paymentOptions: ['credit-card', 'payid', 'bpay'],
    sendInitialLink: true,
    expiryDays: 14
  })
});

This comprehensive API documentation provides everything needed to integrate PayID functionality into your application, including creation, management, status tracking, and webhook handling.

Sandbox Testing

Test Payment Amounts Guide

The PayID Mock System uses specific payment amounts to trigger different scenarios for comprehensive testing. Use these amounts when creating payment requests or making payments to test various success and failure conditions.

Successful Payment Amounts
Normal Successful Payments:

Amount Range: $1.00 to $4,000.00

Behavior: Payment processes successfully with immediate completion

Use Case: Standard payment flow testing

Payment Failure Test Amounts
PayID Expiration Testing:

Amount: $4,055.00

Behavior: PayID expires after 5 seconds

Use Case: Test handling of expired PayIDs

Incorrect Payment Amount Testing:

Overpayment Amount: $4,104.00

Behavior: Simulates customer paying more than required amount

Use Case: Test overpayment handling for Dynamic PayIDs

Underpayment Amount: $4,006.00

Behavior: Simulates customer paying less than required amount

Use Case: Test underpayment handling for Dynamic PayIDs

Refund Failure Test Amounts
Refund Status Validation:

Amount: $4,303.00

Error: Refunds can only be done on COMPLETE, RETURN_COMPLETE or RETURN_FAILED payments

Use Case: Test refund status validation

Manual Payment Processing:

Amount Range: $5,000.01 to $99,999.00

Behavior: Payment requires manual intervention/approval

Use Case: Testing manual payment workflows and delayed processing

Manual Payments Bank Simulation: https://sandbox-payid-mock-frontend.gentletree-4e3b5c0f.australiaeast.azurecontainerapps.io/