Guides
Guides

PayID Payments

Suggest Edits

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

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:

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

Request Parameters:

  • paymentRequest (optional): Payment request code this PayID is associated with
  • 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"
  },
  "paymentRequests": [
    {
      "code": "PR123456"
    }
  ],
  "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"
            },
          "PaymentRequests": [
            ],
          "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

StatusDescription
pendingPayID is in the process of being created
waitingPayID active and ready to receive payments
completePayment successfully received and processed
expiredPayID expired without successful payment
return_in_progressRefund/return initiated
return_completeRefund/return completed successfully
return_rejectedRefund/return was rejected

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": {
    "payment": {
      "code": "PAY123456",
      "amount": 100.00,
      "status": "succeeded",
      "paymentType": "payid",
      "customer": {
        "code": "CUST123456"
      },
      "externalID": "EXT123456",
      "dateCreated": "2024-01-15T11:00:00Z"
    }
  }
}

payment.settled

Triggered when PayID payment funds are settled to your account.

{
  "event": "payment.settled",
  "timestamp": "2024-01-15T14:00:00Z",
  "data": {
    "payment": {
      "code": "PAY123456",
      "amount": 100.00,
      "status": "settled",
      "settlementDate": "2024-01-15T14:00:00Z"
    }
  }
}

payment.failed

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

{
  "event": "payment.failed",
  "timestamp": "2024-01-15T11:30:00Z",
  "data": {
    "payment": {
      "code": "PAY123456",
      "amount": 95.00,
      "expectedAmount": 100.00,
      "status": "failed",
      "failureReason": "Incorrect amount paid",
      "customer": {
        "code": "CUST123456"
      }
    }
  }
}

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

CodeDescription
invalid_requestRequest validation failed
not_foundRequested resource not found
rate_limit_exceededAPI rate limit reached
payid_not_enabledPayID feature not enabled for merchant
customer_not_foundCustomer does not exist
payment_request_not_foundPayment request does not exist

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.

Updated 3 days ago