Changelog
EZYPAYHOW EZYPAY WORKSPARTNERS
Back to All
improved

Changes to how failed payments will be handled

November 25th, 2019 by Ezypay

At 12:30 pm AEST ( 2:30pm GMT) Monday January 13th, 2020, we will be updating the mapping of the payment provider responses to our failed payment response codes to provide more detailed and meaningful failed payment reason codes.

We will also be introducing a new process for invalidating payment methods. Ezypay will now act to automatically invalidate the payment method mapped to certain failed payment reasons. Invoices linked to a payment token that has now been invalidated can no longer be processed or retried.

To help you understand and interpret the correct failed payment responses, we are updating and making changes to our invoice, payment API and PAST_DUE webhook events. New data fields will be available in our sandbox environment to test.

How to handle failed payment responses from Ezypay

To ensure failed payments are correctly handled, the following workflow should be followed:

Obtain the status of the invoice from the Get Invoice API or from the Past due webhook.

  1. Ensure you read the failedPaymentReason code / description field to determine the type of failure reason.
  2. Ensure that you read the field paymentMethodInvalid so that you can store the payment method status to ensure that you receive the right information regarding the validity of the payment token.
  3. Ensure you subscribe to the webhook events invoice_past_due and payment_method_invalid
  4. The following new data objects in our API will make it easier for you to know the reason for the failed payment and will now be included in the invoice API.
  • paymentMethodInvalid
  • manualRetryPossible
  • failedPaymentReason (code, description).
  • paymentProviderResponse (code, description)

More detailed information regarding the API enhancements can be found https://developer.ezypay.com/docs/get-invoice-api-enhancements-invalid-payment-method-token-and-failed-reason-response-details

The new failedpaymentresponse codes and how they map to the validity of a payment token is summarised below, these codes and statuses are available from the Invoice API and also PAST_DUE webhook event.

Details on the invoice_past_due webhook data payload can be found here.
https://developer.ezypay.com/docs/webhook-event-response

You should ensure that these fields and mappings are understood in your integration.
Payment provider response codes and descriptions are also updated and the full list can be found here.

developer.ezypay.comdeveloper.ezypay.com
Failed Payment Response Guide

Invalidating payment methods

If any new invoice or invoice retry has an invalid payment method, these attempts will now receive a HTTP 413 response and as such, will not be received and, hence, not processed.

Please ensure that you subscribe to the payment_method_invalid webhook event. Details on the payment_method_invalid webhook data payload can also be found here. https://developer.ezypay.com/docs/webhook-event-response

Detailed information on invalidating payment methods can also be found here.
https://developer.ezypay.com/docs/failed-payment-handling-improvements

Any invalidated payment method that is linked to a subscription will result in its next recurring invoice not being delivered for payment processing. The payment_method_invalid webhook will provide a list of impacted subscriptions linked to the invalid payment method. You can easily make an API call to replace the invalidated payment method with a new valid payment method for the customer and all linked invoices and subscriptions will be updated. The subscription API will now also provide additional data to inform you if the payment method linked to it has been invalidated or not.

🚧

All of the above changes are available in the Sandbox environment. Please ensure that you have made the necessary changes and have tested your integrations here prior to 13th January.

📘

If you have any questions about these changes and the system behaviours that result, please do not hesitate to contact our Implementations Team on 1300 300 553 or at [email protected].