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.

The Pay Advantage registered webhooks screen

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.
  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.

Webhook payloads

This is currently available for testing in the sandbox environment

Previously, our webhook implementation required API users to make subsequent calls to the Pay Advantage API to obtain additional data about the received webhook. However, we've improved this experience by directly providing the payload that would typically be acquired through such API calls. This enhancement significantly reduces the need for extensive developer coding and enables immediate action upon receiving the webhook.

If you prefer not to include the webhook payload data in your webhook, we can ensure that you are excluded from the latest webhook update.

Example payload:

[
    {
        "Code": "1FFDB5FA",
        "MerchantCode": "PA12345",
        "DateCreated": "2024-04-02T15:38:02.487+00:00",
        "DateUpdated": "2024-04-02T15:38:08.527+00:00",
        "Event": "payment.created",
        "ResourceCode": "9SFUZA",
        "ResourceUrl": "https://test.payadvantage.com.au/payments/9SFUZA",
        "EndpointCode": "TSFUZA",
        "EndpointUrl": "http://mysite.com/pawebhook",
        "Status": "sending",
        "Data": {
            "Code": "9SFUZA",
            "DateCreated": "2024-04-03T02:37:54.640+11:00",
            "DatePaid": "2024-04-03T02:37:54.640+11:00",
            "DateFailed": null,
            "DateClears": "2024-04-04T00:00:00.000+11:00",
            "DateSettled": null,
            "DateUpdated": "2024-04-03T02:37:54.640+11:00",
            "ReadyToSettle": true,
            "FailCode": null,
            "FailReason": null,
            "PaymentType": "realtime_credit_card",
            "Amount": 34,
            "AmountIncFees": 35.34,
            "AmountRefunded": 0,
            "Customer": {
                "Code": "PF2UZA",
                "Name": "John Davies"
            },
            "BPAYReference": null,
            "ExternalID": null,
            "ExternalReference": null,
            "SettlementCode": null,
            "DDR": null
        }
    }
]

For information on the full release visit: https://help.payadvantage.com.au/hc/en-us/articles/9431396305935-Pay-Advantage-8-16-0

DDR payment API uplift

Payment to DDR query

We've simplified the process of associating a DDR with a payment. With the newly introduced feature enabling search by ddr.code in the GET /payments endpoint and the inclusion of ddr.code within the payment record itself, linking payments to specific DDRs has become effortless. Now, you can seamlessly identify which payments correspond to which DDRs, streamlining your workflow.

Search payments using DDR Code

curl --request GET --url 
'https://api.test.payadvantage.com.au/v3/payments?ddr.code=AAAAAA' 
--header 'accept: application/json'

DDR Code available on the payment record

{
  "Records": [
    {
      "Code": "ABC123",
      "DateCreated": "2023-12-07",
      "DateFailed": null,
      "DateClears": "2023-12-12",
      "DateSettled": "2023-12-12",
      "DateUpdated": "2023-12-12",
      "ReadyToSettle": true,
      "FailCode": null,
      "FailReason": null,
      "PaymentType": "realtime_credit_card",
      "Amount": 200,
      "AmountIncFees": 205,
      "AmountRefunded": 3,
      "DDR": {
        "Code": "AAAAAA"
      },
      "Customer": {
        "Code": "ABC123",
        "Name": "Bob Smith"
      },
      "BPAYReference": "123456789",
      "ExternalID": "Your External ID",
      "SettlementCode": "AABB12"
    }
  ],
  "Meta": {
    "page": 1,
    "recs_per_page": 1,
    "total_recs": 1
  }
}

Webhook Data payloads

Previously, our webhook implementation required API users to make subsequent calls to the Pay Advantage API to obtain additional data about the received webhook. However, we've improved this experience by directly providing the payload that would typically be acquired through such API calls. This enhancement significantly reduces the need for extensive developer coding and enables immediate action upon receiving the webhook.

If you prefer not to include the webhook payload data in your webhook, we can ensure that you are excluded from the latest webhook update.

Example payload:

For information on the full release visit: https://help.payadvantage.com.au/hc/en-us/articles/9351555245839-Pay-Advantage-8-15-0

Introducing Apple and Google pay

New payment type

The introduction of Apple and Google pay has added two new payment types. These payment types will be returned from the GET /payments API call and the paymentType will be either "google_pay" or "apple_pay".

Sample response

{
    "Code": "VKFUZA",
    "DateCreated": "2024-03-22T18:49:56.180+11:00",
    "DatePaid": "2024-03-22T18:49:56.180+11:00",
    "DateFailed": null,
    "DateClears": "2024-03-25T00:00:00.000+11:00",
    "DateSettled": null,
    "DateUpdated": "2024-03-22T18:49:56.180+11:00",
    "ReadyToSettle": true,
    "FailCode": null,
    "FailReason": null,
    "PaymentType": "google_pay",
    "Amount": 23.00,
    "AmountIncFees": 23.76,
    "AmountRefunded": 0.00,
    "Customer": {
        "Code": "2T9UZA",
        "Name": "Jorge Washington"
    },
    "BPAYReference": null,
    "ExternalID": null,
    "ExternalReference": null,
    "SettlementCode": null
}

iFrame changes

To adapt to the recent updates, please consult the documentation that details the new events: device-complete and device-error. These events are triggered when a user selects the Apple Pay or Google Pay option, bypassing the need to enter credit card details, and thus, eliminating the necessity for calling the iFrame authorization. https://docs.payadvantage.com.au/docs/apple-google-payments

For information on the full release visit: https://help.payadvantage.com.au/hc/en-us/articles/9020654160399-Pay-Advantage-8-14-0