Making a Transfer
Learn how to transfer money between a user's account
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
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
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
.
Status | Description |
---|---|
READY | Transfer is ready to be processed. |
PENDING_APPROVAL | Transfer is ready to be processed however the user has requested their approval before it can be processed. Akahu will handle the approval with the user directly. |
SENT | Transfer has been processed and has appeared in the transactions of the source account. |
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.
Status | Description |
---|---|
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. |
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. |
CANCELLED | Transfer was cancelled. Details may be supplied in the status_text field. |
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.
Updated 3 months ago