Making a One-Off Payment

Prerequisites

Before you can make a one-off payment, you will need:

• An Akahu App Token and App Secret (see here for instructions).

• A rough idea of the size of payment you will be initiating. This should be within bank limits, which you can inspect via the GET /v1/connections endpoint (API Reference).

Creating the payment

One-off payments can be created using the POST /v1/one-off-payments endpoint (API Reference), with the following required details in the body:

Other optional fields can be specified - see the API Reference for a full listing. Some common fields and their uses are listed at the bottom of this page.

The payment response

A successful response from the payment creation endpoint contains three fields:

The user should be directed to visit the authorisation_url to complete the payment within the expiry window.

Common optional payment fields

When creating a one-off payment additional optional fields can be specified to customise or enable specific behavior.

Setting unique payment references

To aid in payment reconciliation your app can provide unique values for particulars, code, and reference that will be visible on the transaction in the destination account.
These can be specified by setting the payee.particulars, payee.code, and payee.reference fields in the payment body.
These values must be fewer than 13 characters long, and are restricted to alphanumeric characters as well as (space), -, and _.

You can also set custom values to be visible on the payer's transaction using payer.particulars, payer.code, and payer.reference, for example explaining the purpose of the payment.

Webhooks

If set, Akahu will send webhooks to the URI defined in the webhook_uri field of the payment body.
See Monitoring Payment Progress for details about these webhooks.

Payment expiry

By default one-off payments will expire after one hour unless the user has authorised them.
If your app requires a different expiry lifetime, set the expires_at field in the payment body.
This must be an ISO 8601 timestamp between 15 minutes and 1 year in the future.

When this time is reached, the payment will receive a status of CANCELLED with a status_reason.code of TIMED_OUT.

Deep links

When a user is redirected to a native app via iOS universal links or Android app links, the browser often enables additional checks to ensure that the user intended to open a native app.
If your redirect_uri is a deep link, you can also set the redirect_mode field in the payment body to "deep_link".
This will require the user to make an explicit tap before returning to your app, helping to ensure successful navigation.

Retrieving payer details

While you can manually supply payer details, most use-cases call for the user to select an account to pay from.
In some instances it can be useful for your app to know which account the user selected, for example to process refunds.

To request payer account details, set the payer.release_account_details field to true.
The payer account name and number will be requested from the bank, and will be populated as payer.name and payer.account_number on the payment when you request the payment from GET /v1/one-off-payments/{paymentId}.

Note that these details will only become available after the user has chosen their account and given consent for the payment.

Enforcing payer details

If your app already knows details of the account that the payer will use, these can be enforced by setting these fields:

• payer.bank: An enumerable value, specifying a single bank that the payer must use.
• payer.account_number: The payer account that must be used, specified as its NZ BECS account number.
• payer.name: The name of the payer - this may be set if payer.account_number is also set, otherwise it will be ignored.