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.

Production implementation date: 18th June 2024

Webhook Admin Screen

We are introducing a webhook management screen that allows you to view and check the status of your created webhooks. This feature is particularly useful if you have stopped receiving webhooks and need to diagnose the issue independently. You can access this screen through the developer portal.

The screen is divided into two sections:

1. Webhook registration

To register your webhooks, enter the URL where you want to receive them. You will be prompted to record the secret key needed for signing the payload. Implement this key into your webhook code, then click the re-arm button to initiate the validation process. If any step fails, the system will indicate the exact point of failure, allowing you to correct the issue and click the re-arm button again. Repeat this process until your webhook is fully registered.

2. Webhook logs

You can now view all the webhooks sent to your server, which is very helpful for understanding payloads and diagnosing issues if a webhook wasn't processed correctly. In the near future, there will be an option to resend webhooks, allowing you to replay events for testing and troubleshooting purposes.

Chargebacks - Are no longer failed payments

❗️

Important - Breaking change

To accommodate the introduction of partially charged-back payments, we have updated the way chargebacks are handled and reported in Pay Advantage. These changes will soon be available in the sandbox environment, and we require all API merchants to test their code in this environment to ensure compatibility with the new system. Please note that chargebacks may not always be for the full payment amount.

A new refund webhook will provide the following information. Understanding the type of refund is crucial, as it will indicate whether the refund was initiated by a refund request or due to a chargeback.

The example webhook below shows a refund of type "chargeback" and includes details about the chargeback amount and the payment code associated with the chargeback. Similar webhooks will be received for regular refunds, but their type will be "refund".

Please note: Once this change goes live, any chargeback previously marked as failed will no longer be considered a failed payment. Instead, it will be classified as a payment with an associated chargeback.

{
    Code: '4E6A62AE',
    MerchantCode: 'PAABCDE',
    DateCreated: '2024-05-21T05:18:08.143+00:00',
    DateUpdated: '2024-05-21T05:18:14.913+00:00',
    Event: 'refund.processed',
    ResourceCode: 'YY2J4A',
    ResourceUrl: 'https://api.secure.payadvantage.com.au/refunds/YY2J4A',
    EndpointCode: '9Y2J4A',
    EndpointUrl: 'http://myapp.com/webhooks',
    Status: 'sending',
    Data: {
      Amount: 44.83,
      Payment: {
        Code: 'ABCABC'
      },
      ExternalID: null,
      Code: 'YY2J4A',
      Reason: 'Chargeback - Unauthorised',
      DateCreated: '2024-05-21T15:18:08.083+10:00',
      DateCancelled: null,
      CancelledReason: null,
      DateUpdated: '2024-05-21T15:18:08.050+10:00',
      Status: null,
      CustomerPaymentAccount: 
          "CustomerPaymentAccount": {
              "Code": "9BRGTY",
              "Name": "111-111, XXX111"
          },
      Attempts: [],
      IsMerchantInitiated: false,
      Customer: {
          "Code": "FZ5ZQE",
          "Name": "Orlando Summer"
      },
      CanBeCancelled: false,
      DateFailed: null,
      FailReason: null,
      CreatedBy: {
          "FirstName": "Customer",
          "LastName": "Support",
          "UserName": "[email protected]"
      },
      Type: 'chargeback' // Use this parameter to determine if this is a chargeback or refund
    }
  }

New webhooks: Refund and Chargeback

A newly introduced webhook has been release where you are able to be notified by webhook about any refund updates or chargebacks. Most payments are refunded by the merchant however, there are circumstances where we refund payments due to fraud or other reasons. When a refund occurs you can now handle these scenarios in your backend system by handling these webhook events.

The differentiating parameter is Data.Type. This will provide the information necessary for understanding if the money has been given back to the customer via a refund or via a chargeback.

Both refunds and chargebacks are not required to be the full amount of a payment. You may see multiple refunds or chargebacks come through for a single payment. Ensure that your system is able to handle this information. External ID is a handle parameter to use to be able to link the refunds and the payments or chargebacks together.

If you were previously calling the api /payments_failed/ to retrieve chargedback payments and you will now be able to call the payments API to return all payments with chargebacks. The type parameter will be used to

ALL CHARGEBACKS - https://api.payadvantage.com.au/payments?amountchargedbackfrom=1
ALL REFUNDS - https://api.payadvantage.com.au/payments?amountrefundedfrom=1

OR

ALL CHARGEBACKS - https://api.payadvantage.com.au/refunds?type=chargeback
ALL REFUNDS - https://api.payadvantage.com.au/refunds?type=refund

What do I need to do?

1. Handle the new refund type webhooks. You are welcome to ignore these new events if they are not important to your system. However, you will need to ensure the new refund webhooks do not cause failures in your current system
2. If you are relying on failed payment webhooks to notify of chargebacks, you will need to change it to listening for the refund webhook. Then monitoring the data payload to determine the type of the refund. It will either be refund or chargeback. To test chargebacks in our Test/Sandbox environment follow the process outlined here: https://docs.payadvantage.com.au/docs/charge-credit-cards-in-sandbox#simulate-chargeback
3. If you were calling the /payments/ or /payments_failed/ API to understand what payments had been chargedback you can now call the /payments?amountchargedbackfrom=1 to return all chargebacks.