Introducing the new payment status_code field

As of today, a new status_code field will be available on all payments initiated through Akahu that do not successfully complete (i.e. payments that are assigned a status of ERROR, DECLINED, or CANCELLED). The purpose of this new field is to provide a programmer-friendly way for apps to take action based on the reason for payment failure.

Previously, Akahu has provided error information to apps using the status_text field, which is a free-text, human readable message containing an explanation of the error. This may lead to developers coding against this field, which makes it difficult for us to update our error messages without breaking their application logic.

With the introduction of status_code, we now have two separate fields to fulfill the two separate use-cases:

  • status_code - for application logic that needs to be performed based on certain failure reasons
  • status_text - a human readable description of the reason why the payment didn't succeed

To provide developers with time to transition any application logic away from relying on status_text, there will be a 2 week grace period, during which no existing status_text values will be changed. As of Monday 5 September 2022, this period will conclude and Akahu will revise the content of existing status_text messages.

See the Status Code and Status Text section of our Making a Payment guide for the full list of possible status codes.

Javascript SDK users can upgrade to [email protected] to get the latest Typescript definitions including the status_code field.