Guides

Requesting Payment Consent

Request and authorise an enduring payment consent

Before you can initiate enduring payments, a user must authorise an enduring payment consent. This is the first phase of using enduring payments: the consent defines the account you can pay from, the payees you can pay to, and the limits that apply.

Requesting a payment consent

Enduring payment consents are requested from the user through Akahu's OAuth authorisation flow. Construct an authorisation request and navigate the user to the authorisation URL. Akahu handles the rest and returns the user to your application once complete.

Every enduring payment consent request is made up of the following components.

Account information scope

Every enduring payment consent request must be combined with at least basic account information scope. This gives your application access to basic account details, such as the account name and account number, to display in your application. You may also want to request:

  • Account balance, to display in your application.
  • Account holder name, to verify against your records before initiating payments.

See Scopes for the access your application can request.

Payees

Each request must specify the payee bank accounts you are requesting the ability to pay. A consent can only be used to pay the payees specified in the request. If you need to pay a variety of payees that may change over time, request that the user authorises either an additional or a replacement consent.

To ensure that payee details (name and account number) are not misrepresented to the user, Akahu requires that each payee is provided from a verified source:

  • Static (STATIC) - a fixed account number from your application's configuration. Static payees must be requested manually and are verified by Akahu before being added to your application's configuration. This is the most common source and is well suited to paying into accounts that you control, such as your company's settlement account.
  • Inline (INLINE) - a payee whose details you supply in the request, verified using one of several verification methods (most commonly an Akahu account verification token).

See Payee Verification for more detail on each source and how Akahu verifies payees.

Limits

Two limits must be included in every enduring payment consent request:

  • Single payment limit - the maximum value of any single payment initiated using the consent. Payments above this amount are rejected.
  • Periodic payment limit - the maximum total value of all payments initiated using the consent within a set period. Available periods are daily, weekly, fortnightly, monthly, and annually.

Limit maximums

For consents on classic connections, Akahu does not enforce an upper bound on the limits you can request. However, each bank may enforce its own limits when a payment is initiated. Some of these are documented in Payment limitations.

For consents on official connections, the maximum requestable limit varies between banks. These limits are described in Payment limits. If your request specifies limits higher than the user's chosen bank will accept, Akahu automatically downlevels the consent to conform to that bank's requirements.

Default payment consent request

If your application requests payment consents to the same payee(s) with the same limits for every user, Akahu will configure a default payment consent request for your application. Once configured, Akahu uses your default whenever an authorisation request does not specify its own payment consent details:

  • Inline authorisation requests cannot specify per-request payment consent details, so an inline request that includes payment access always uses your default.
  • Pushed authorisation requests (PAR) may omit the payment consent details. When omitted, your default is used. When supplied, they override your default for that request.

A default lets you request payment access without building a payment consent for each user, which keeps your integration simple when consent parameters don't vary between users.

Get in touch if you'd like to configure a default payment consent request for your application.

Adding or modifying a consent

A user can authorise more than one enduring payment consent for each account, and consents can be added or changed after the initial authorisation. For example, you can request a new consent for a different payee, or replace an existing consent with updated limits.

Make these changes by sending the user through the authorisation flow again with the appropriate access request. See the enduring_payment_consent access request, which is designed for adding and modifying payment consents on accounts that a user has already shared with your application.

Each consent on an account is identified by a label. Re-consenting with a new label adds a separate consent, while re-consenting with an existing label replaces that consent with the updated details.

After authorisation

You can view the consents on an account in the payment_consents array returned by the /accounts endpoint.

You can now initiate payments using the consent. See Making a Payment for the full details on initiating a payment and tracking its progress. Payments are validated against the consent when they are initiated: a payment is rejected if it is sent to a payee that is not included in the consent, or if it would exceed the consent's single or periodic limit.