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?
- 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
- 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
- If you were calling the
/payments/or/payments_failed/API to understand what payments had been chargedback you can now call the/payments?amountchargedbackfrom=1to return all chargebacks.