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. Limited to /[A-z0-9 \-_]/
  },
  "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. Limited to /[A-z0-9 \-_]{0,12}/
      "code": "<string>",
      "reference": "<string>"
    },
    "destination": {
      // Statement details to be shown on the destination account. Limited to /[A-z0-9 \-_]{0,12}/
      "code": "<string>",
      "reference": "<string>"
    }
  }
}

The response will look like:

{
  "success": true,
  "item": {
    "_id": "payment_1111111111111111111111111",
    "status": "READY",
    "sid": "akp1111111111",
    "from": "acc_1111111111111111111111111",
    "to": {
      "name": "John Smith",
      "account_number": "12-1234-1234567-12"
    },
    "amount": 9.5,
    "created_at": "2020-04-20T01:55:41.674Z",
    "updated_at": "2020-04-20T01:55:41.674Z",
    "timeline": [
      {
        "status": "READY",
        "time": "2020-04-20T01:55:41.674Z"
      }
    ],
    "final": false
  }
}

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

📘

PCR Fields

In the example above, you may note that Akahu exposes the payment code and reference fields to the calling app. You may set these fields as you require within the constraints of a maximum of 12 characters per-field, using only the allowed set of alphanumeric characters, spaces ( ), underscores (_), and hyphens (-).

The particulars field that is usually available on New Zealand account-to-account payments is reserved for use by Akahu. We will set this field to a unique sid identifier for the payment in the format akpxxxxxxxxx. This sid is returned for your reference in the payment response (see example response).

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 status. The value of a payment's status property is determined by following process:

Each status and its corresponding meaning is listed below:

Normal Statuses

Each payment begins life with a READY status. After the payment has been successfully processed, it will transition to a status of SENT.

Error Statuses

In some exceptional scenarios a payment will be assigned one of the following statuses. A PAUSED payment may subsequently be assigned a new status after some action is taken to resume it, however once a payment has a status of ERROR or DECLINED no further status changes will occur.

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.