Making a Transfer

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"
}

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 state key. state can have the following values:

State Description
PAUSED Transfer is not yet ready to be processed. This tends to occur when the transfer requires human review, for reasons such as fraud prevention or manual checks.
READY Transfer is ready to be processed.
INITIATED Akahu has begun processing the transfer.
SENT Transfer has been processed and has appeared in the transactions of the source account.
RECEIVED Funds have arrived in the destination account.
DECLINED The transfer 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 transfer 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 transfer was processed. The transfer may still move to RECEIVED if it shows up in the destination account.
SENT_ERROR The transfer was lodged with the source bank, but the bank threw an error when Akahu tried to retreive the transactions to confirm. The transfer 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 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.