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.