Making a Transfer

ℹ️

This guide is intended for developers using Akahu's enduring account connectivity. Information provided may not be relevant for those using one-off account connectivity.

Making a transfer is a common activity in online banking. Using Akahu you are able to automate this with a simple API call.

Transfers on Akahu are the movement of money between accounts that the user has connected. A transfer is distinct from a Payment, which is the movement of money to an external account (an account that has not been connected to Akahu by the user). Akahu supports inter-bank transfers, but note that these will take longer due to standard bank processing times.

⚠️

Beware

Making a transfer will move actual money around! It is possible to take actions that result in temporary loss of funds (like transferring into an account that can't transfer back out).

Prerequisites

Before you can make a transfer, you will need:

• To be able to make requests to the Akahu API (see here for instructions).
• An Akahu account with at least two accounts connected, one that can make transfers and one that can receive transfers.

To determine if your accounts can make or receive transfers, make a GET request to the /accounts endpoint.
Locate your accounts in the results and look for the attributes key. If your account attributes include TRANSFER_TO, you can transfer into the account. Likewise if the attributes include TRANSFER_FROM you can transfer out of the account.

Making the Request

API Reference

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

{
  "to": "acc_11111111111111111111", // The account ID that you want to transfer into
  "from": "acc_11111111111111111111", // The account ID that you want to transfer from
  "amount": 5.0 // How much you want to transfer (in dollars)
}

The response will look like:

{
  "success": true,
  "item": {
    "_id": "transfer_1111111111111111111111111",
    "status": "READY",
    "sid": "akx1111111111",
    "from": "acc_1111111111111111111111111",
    "to": "acc_1111111111111111111111111",
    "amount": 2.5,
    "created_at": "2020-04-15T23:12:01.746Z",
    "updated_at": "2020-04-15T23:12:01.746Z",
    "timeline": [
      {
        "status": "READY",
        "time": "2020-04-15T23:00:00.000Z"
      }
    ],
    "final": false
  }
}

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

Following Transfer Progress

While you could just make the transfer request and leave it at that, it makes sense to follow the transfer until the money arrives in the destination account (or at least until it leaves the source account!). This will allow you to implement more advanced logic such as retrying failed transfers or notifying the user (perhaps they have insufficient funds).

Akahu provides two ways to follow the progress of a transfer:

• Using polling.
• Using webhooks.

Polling

API Reference

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

Webhooks

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

In order to receive webhooks you must be acting as a full app - personal apps don't have webhooks enabled.

See our Webhook Guide for more information.

Transfer Lifecycle

As a transfer progresses, you can keep track of its progress by referring to its status. The value of a payment's status may be one of the following:

Normal Statuses

Each transfer begins life with a READY status. As the transfer is processed, it will transition to a status of SENT.

Error Statuses

In some exceptional scenarios a transfer will be assigned one of the following statuses. A PAUSED transfer may subsequently be assigned a new status after some action is taken to resume it, however once a transfer 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 transfer 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 transfer.
• Track the transfer's progress via polling or webhooks.
• Be able to take action to handle the different states of your transfers lifecycle.