Making a Payment

Online banking payments are a common way to pay bills, invoices or friends. With a simple API call, Akahu allows you to automate these actions on behalf of your users.

Payments on Akahu involve the movement of money from an account that the user has connected into an external account. You should not use payments to move money between the user's connected accounts, make a transfer instead.

Beware

Making payments will move actual money around! It is recommended to only use small amounts during development.

Prerequisites

Our payments endpoint is restricted to whitelisted apps. If you want to get your app approved for making payments, please contact us.

Before you can make a payment, you will need:

  • To be able to make requests to the Akahu API (see here for instructions).
  • An Akahu account with at least one account connected that can make payments.

To determine if your account can make payments, make a GET request to the /accounts endpoint. Locate your account in the results and look for the attributes key. If your account attributes include PAYMENT_FROM, you can pay out of the account.

Making the Request

API Reference

To initiate a payment, make a POST request to the /payments endpoint, with the following details in the body:

{
  "to": {
    "account_number": "01-2345-6789012-34", // The NZ bank account number for the destination account
    "name": "James Smith" // The name of the destination account holder
  },
  "from": "acc_11111111111111111111", // The account ID that you want to transfer from
  "amount": "<number>", // How much you want to transfer (in dollars)
  "meta": {
    "source": {
      // Statement details to be shown on the source account
      "code": "<string>",
      "reference": "<string>"
    },
    "destination": {
      // Statement details to be shown on the destination account
      "code": "<string>",
      "reference": "<string>"
    }
  }
}

The response will look like:

{
  "success": true,
  "item_id": "payment_1111111111111111111111111"
}

Take note of that item_id, we'll need it to keep track of what happens to the payment.

Payment Restrictions

Akahu follows the principle of least privilege when it comes to making payments. Even though your app is whitelisted, we may apply several restrictions, including:

  • Limiting the set of account numbers your app can pay into. Typically your app will only need to pay into your company account(s).
  • Setting maximum payment amounts.
  • Ensuring the data in payment "code" and "reference" fields conforms to a certain format.

If you attempt to create a payment that is not allowed by your app's restrictions, you will receive a 400 HTTP response with an error message.

Following Payment Progress

While it is possible to make the payment request and leave it at that, it makes sense to follow the payment at least until the money leaves the source account. Akahu exposes payment progress, allowing you to implement more advanced logic such as retrying failed payments or notifying the recipient on payment arrival.

Much like transfers, Akahu provides two ways to follow the progress of a payment:

  • Using polling.
  • Using webhooks.

Polling

API Reference

The simplest way to keep an up-to-date view of the payment is to make periodic GET requests to the /payments/{_id} endpoint, using the item_id you got earlier.

Webhooks

More efficient, webhooks will notify you whenever the payment changes its status.

See our Webhook Guide for more information.

Payment Lifecycle

As a payment progresses, you can keep track of it's progress by referring to its state key. state can have following values:

State Description
PAUSED Payment is not yet ready to be processed. This tends to occur when the payment requires human review, for reasons such as fraud prevention or manual checks.
READY Payment is ready to be processed.
INITIATED Akahu has begun processing the payment.
SENT Payment has been processed by the bank and has appeared in the transactions of the source account.
RECEIVED Funds have arrived in the destination account. This will only occur if the destination account is connected to Akahu.
DECLINED The payment has been declined by the source bank. Details are supplied in the status_text field.
ERROR Akahu has encountered an error (not your fault). Details may be supplied in the status_text field.
SENT_TIMEOUT The payment was lodged with the source bank, but it has not been found in the transactions of the source account. Akahu cannot be certain that the payemnt was processed. The payment may still move to RECEIVED if it shows up in the destination account.
SENT_ERROR The payment was lodged with the source bank, but the bank threw an error when Akahu tried to retreive the transactions to confirm. The payment may still move to RECEIVED if it shows up in the destination account.

Also of note is the final field, which will become true once the payment will no longer be updated. If you are polling for updates, it is a good indicator that you can stop polling!

Conclusion

You should now be able to:

  • Initiate a payment.
  • Track the payment's progress via polling or webhooks.
  • Be able to take action to handle the different states of your payments lifecycle.