Production implementation date: 12th February 2026

Enhanced DDR API – Auto Authorisation

Overview

This enhancement allows merchants to automatically authorise and approve Direct Debit Requests (DDRs) at creation time via the API, removing the need for the customer to be sent a link to authorise the payment. This allows merchants to submit a recurring debit and have it automatically active and ready for the payments to process immediately.

This is useful for scenarios where the user signs up via your web portal and you want to create a subscription automatically to begin debiting the user whilst providing access to your business features.

It is recommended that since the user can remain in your web portal while the set up the recurring debit, the should also be given the opportunity to cancel through your web portal as well. This is facilitated using the PATCH endpoint for https://api.payadvantage.com.au/v3/direct_debits/ddr_code by submitting a status of cancel or pause.

API Changes

Create Direct Debit (DDR)

The DDR POST API has been enhanced to support:

• Passing a Customer Payment Account during DDR creation
• Enabling Customer Authorisation Not Required via a new flag

New Request Fields

{
  "customerPaymentAccount": {
    "code": "xxxxxx"
  },
  "autoApproval": true
}

Validation Rules

• The customerPaymentAccount.code must belong to the customer specified in customer.code
• If validation fails, the API will return an error and the DDR will not be created

Auto Authorisation Logic

Authorisation Rules

• When CustomerAuthorisationNotRequired = true:
  • DDRs are authorised immediately
  • DDRs are also often automatically approved and set to Active status, however some DDR's require our support teams approval, in which case the DDR will return the status of Pending
  • High risk DDRs will be rejected when using the CustomerAuthorisationNotRequired flag and will require you to resubmit without the flag and send your customer to the link provided to enable customer authorisation and acceptance.
• When CustomerAuthorisationNotRequired = false (Default):
  • The API will return a link for the customer to follow to authorise the direct debit

For more details, see this article

Customer API – Address Details

Overview

This update enhances the Customer API by including address details in customer retrieval responses. This allows downstream systems to access customer biller address information without additional lookups.

API Changes

Get Customer (Single)

Address details are now returned when retrieving a single customer.

Updated Endpoints

• GET /customers/{customerCode}
• Other single-customer GET endpoints where a full customer object is returned

New Response Fields

The customer object now includes an address section.

Example Response

{
  "code": "CUST123456",
  "name": "John Smith",
  "email": "[email protected]",
  "address": {
    "line1": "123 George Street",
    "line2": "Level 4",
    "city": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country": "AU"
  }
}

Production implementation date: 27th January 2026

Payment Request Webhooks

Overview

Payment Request webhooks notify third-party systems when the status of a Payment Request changes, allowing real-time tracking without polling the API.

Supported Webhook Events

Testing Scenarios

Payment Request Created

• Action: Create a Payment Request via API or Merchant Dashboard
• Webhook: payment_request.created
• Status: active

Payment Request Completed

• Action: Open the hosted payment link and complete payment using a test card
• Webhook: payment_request.completed
• Status: completed
• Note: Payment details appear in the Payments array

Example Payload:

{
  "Entity": "payment_request",
  "Event": "payment_request.completed",
  "ResourceCode": "PR_ABC123",
  "Data": {
    "Code": "PR_ABC123",
    "Status": "completed",
    "Amount": 150.00
  }
}

Retry Behaviour

• If the webhook endpoint does not return 200 OK or 202 Accepted, delivery is retried.
• Retry attempts are visible in the Webhook Logs in the Merchant Dashboard.

Delete Customers via API

Overview

Merchants can now delete customers via the API if they were created but never used for a payment or direct debit. This helps keep your customer list clean and up to date.

When Can you Delete a Customer?

• The customer** has not had any payments**
• The customer has no Direct Debit Requests (DDRs) linked

Customers that have had payments or DDRs cannot be deleted for record-keeping reasons.

How to Delete a Customer

API Endpoint

DELETE /v1/customers/{customerCode}

• Replace {customerCode} with the customer’s code.
• The operation is permanent and cannot be undone.

What Happens

• Success: Customer is removed from the system
• Failure: Customer cannot be deleted if they have payments or DDRs; the API returns an error

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

Production implementation date: 30th June 2025

Customer Custom Fields

Overview

PayAdvantage now completely supports custom fields via the API for customer records. This update includes both API functionality and web application enhancements to provide a improved custom fields support.

API Changes

Customer Endpoints

All customer API endpoints now support custom fields:

• GET /customers - Returns custom fields in response
• GET /customers/{code} - Includes custom fields for individual customers
• POST /customers - Accepts custom fields when creating customers
• PUT /customers/{code} - Updates custom field values

Custom Fields in API Responses

Customer responses now include a customFields array:

GET /customers
{
  "code": "CUST001",
  "name": "John Smith",
  "email": "[email protected]",
  "customFields": [
    {
      "customFieldID": 1,
      "valueString": "Department A"
    },
    {
      "customFieldID": 2,
      "valueString": "VIP Customer"
    },
    {
      "customFieldID": 3,
      "valueString": "20.00"
    }
  ]
}

Creating Customers with Custom Fields

POST /customers
{
  "name": "Jane Doe",
  "email": "[email protected]",
  "customFields": [
    {
      "customFieldID": 1,
      "valueString": "Department B"
    },
    {
      "customFieldID": 2,
      "valueString": "Standard Customer"
    },
    {
      "customFieldID": 3,
      "valueString": "33.00"
    }
  ]
}

Updating Custom Fields

PUT /customers/{Code}
{
  "customFields": [
    {
      "customFieldID": 1,
      "valueString": "Department C"
    },
    {
      "customFieldID": 2,
      "valueString": "High value Customer"
    },
    {
      "customFieldID": 3,
      "valueString": "22.00"
    }
  ]
}

Web Application improvements

Set Custom Field

Navigate to Settings → Customer Settings to define the names of your custom fields. This allows you to tailor the fields to match your business needs.

Add some value in your custom field

Go to Customers → Customer Details → Edit, then enter values for each custom field. These values will be saved with the customer's profile and can be used for filtering or reference.

Custom Field Names in Search Filters

The customer search UI interface now displays your custom field names instead of generic labels:

• Previously: Search filters showed "Custom Field 1", "Custom Field 2", "Custom Field 3"
• Now: Search filters display the actual field names you've configured (e.g., "Department", "Type", "Total spent")

Custom Field Specifications

• Field IDs: Use 1, 2, or 3 only
• Value Length: Maximum 50 characters per field
• Optional: Custom fields are completely optional
• Unique: One value per field ID per customer

Configuration

Custom field names can be configured through the PayAdvantage web application. Once set, these names will appear throughout the interface and can be retrieved via the API.

Backward Compatibility

• All existing API calls continue to work unchanged
• New customFields array appears in responses (empty array if no custom fields set)
• Custom fields are optional in create/update requests
• Web application gracefully falls back to default labels if custom names not configured

Production implementation date: 23rd May 2025

Payment API enhancement

We've expanded the Payment API to allow access to additional fields, enabling more comprehensive data retrieval.

In this update, the following fields have been added:

Description - The payment description
Source - Where the payment originated

Source attribute

The source attribute is to indicate where the payment originated. This can be useful when differentiating payments that are made from payment requests or from a hosted pages link or even from your internal staff team using virtual terminal.

• Origin - "connected_app", "api", "payment_request", "virtual_terminal", "hosted_pages", "bpay", "ddr", "batch_debit"
• CreatedBy
  • FirstName
  • LastName
  • UserName
• Type - "customer", "api", "user", "system"

{
  "Code": "ABC123",
  "DateCreated": "2025-05-06",
  "DateFailed": null,
  "DateClears": "2025-05-11",
  "DateSettled": "2025-05-11",
  "DateUpdated": "2025-05-11",
  "ReadyToSettle": true,
  "FailCode": null,
  "FailReason": null,
  "PaymentType": "electronic",
  "Amount": 200,
  "AmountIncFees": 205,
  "AmountRefunded": 3,
  "AmountChargedback": 3,
  "Description":"Gym Membership",
  "Customer": {
    "Code": "ABC123",
    "Name": "Bob Smith"
  },
  "BPAYReference": "123456789",
  "ExternalID": "Your External ID",
  "SettlementCode": "AABB12",
  "DDR": {
    "Code": "ABC321"
  },
  "DebitInstruction": {
    "Code": "ABC123321CBA"
  },
  "DebitBatch": {
    "Code": "ABC123"
  },
  "ReceiptLink": "https://www.payadvantage.com.au/receipts/ABC123",
  "Source": {
   	"Origin": "api",
    "CreatedBy": {
      "FirstName": "Bob",
      "LastName": "Franklin",
      "UserName": "[email protected]"
    },
    "type": "api"  
  }
}
    

Production implementation date: 9th April 2025

Customer API enhancement

We've expanded the Customer API to allow access to additional fields, enabling more comprehensive data retrieval.

In this update, the following fields have been added:

• Date of Birth (DOB)
• Phone
• Mobile
• Home Phone

Looking ahead, we're also working on enabling API access to customer custom fields—allowing both retrieval and updates via the API interface.

{
    "Records": [
        {
            "Code": "AAKCHA",
            "ExternalID": null,
            "IsConsumer": true,
            "Name": "Sebastian Carter",
            "FirstName": "Sebastian",
            "LastName": "Carter",
            "CustomRef": "MYOB991846",
            "Email": "[email protected]",
            "DOB": null,
            "Phone": {
                "CountryId": 1,
                "CountryIso": "AU",
                "Number": null
            },
            "Mobile": {
                "CountryId": 1,
                "CountryIso": "AU",
                "Number": null
            },
            "HomePhone": {
                "CountryId": 1,
                "CountryIso": "AU",
                "Number": null
            },
            "BillerCode": "212886",
            "BPAYRef": "9993702910",
            "DateUpdated": null,
            "DateCreated": "2021-04-15T22:34:14.587+10:00",
            "DateJoined": null,
            "CreatedBy": {
                "FirstName": "Darlene",
                "LastName": "Maxwell",
                "UserName": "[email protected]"
            },
            "IsActive": true
        }
   ]
}

📘

Subscribe for updates on our RSS feed

To subscribe to updates on changes we introduce to our API add the RSS feed: https://docs.payadvantage.com.au/changelog.rss to your preferred RSS feed app.

We recommend using Feeder as it provides free push notifications for changes and updates.

Production implementation date: 3rd February 2025

DDR Subscriptions - Webhooks

Receive webhooks on DDR subscriptions updates

Receive webhooks for changes to DDR subscriptions. When a DDR subscription frequency, amount or description changes you will now receive a webhook notification. This is useful in scenarios where you change the settings from the Pay Advantage portal and you require you backend to be notified about the changes. It is also very useful when a DDR amount change requires a customer to approve, you will be notified via a webhook when that has been approved and changed.

The new webhook details are:

Production implementation date: 12th November 2024

Apple Pay - Register domain

Apple pay needs domain registration

In order to use Apple pay using the WordPress plugin or the iFrame you need to register your domain so Apple is able to validate your merchant account and website. (This is not necessary for Google Pay)

The merchant dashboard now has a section where you can register for Apple pay on your domain. Once this domain has been submitted, our support team will be in contact with you to provide a file that you must host on your website. This will enable Apple pay to be used by your customers.

Production implementation date: 16th October 2024

New DDR APIs

Change customer payment account link

You can now send out a change payment account link to your customers via a simple API which returns a link. The customer will be able to follow that link and change the account the Direct Debit payments are being processed.

https://docs.payadvantage.com.au/reference/customer_payment_accounts_links_post

Pause, Cancel, Resume Direct Debits

A much desired feature has been released where you can now cancel, pause or resume the direct debit subscription from the API. Simply send in the status you want to change the direct debit to. A webhook will be triggered to notify a change has occurred on the direct debit.

https://docs.payadvantage.com.au/reference/direct_debits_patch

Production implementation date: 3rd September 2024

Webhook Admin Screen Updates

Webhook Search

You can now search for webhooks directly in the Pay Advantage dashboard. Filters are available for all webhook types, and you can also search by code to easily locate specific events.

Webhook Resend

Setting up webhooks can be challenging, and sometimes you may miss a specific type or encounter a failure. To address this, we've introduced a webhook resending feature. You can now select webhooks you'd like to resend, and they will revert to a sending state until you've successfully acknowledged their receipt.

PayTo (Beta)

PayTo is a new payment method that enables instant bank account transfers, providing immediate feedback on whether the transaction was successful. It’s protected from chargebacks, offering a secure alternative to traditional payment methods. PayTo is now available in the Pay Advantage dashboard and is also supported in the iFrame, Payment Requests, and Payment Authorization API endpoint.

How to use PayTo

• iFrame and Payment Requests: Simply add "PayTo" as a payment option to make it available for customers to select.
• Payment Authorization API: When issuing a payment via the API, you'll receive a pending status initially. PayTo statuses are communicated through webhooks, and within a minute or less, you’ll receive a webhook indicating whether the payment was successful. This process is designed to mirror the familiar workflow of credit card transactions via the API.