Guides

Payee Verification

How Akahu confirms that payee details are correct

When your application requests a payment consent, Akahu needs confidence that the destination account (the payee) is legitimate, and that its details are not being misrepresented to the user. Payee verification is how Akahu establishes that a payee's name and account number can be trusted before a payment consent is presented to the user.

Each payee included in a payment consent request includes a source field that tells Akahu where to source the payee name and account number:

  • STATIC payees are fixed records held in your application's configuration.
  • INLINE payees are supplied in the request itself, and include a verification_method that determines how Akahu verifies the payee's details.

Both sources are described below.

Static payees

A static payee is a fixed bank account number that is added to your application's configuration. Static payees are requested manually and verified by Akahu before being added. Because they are fixed and pre-verified, they are well suited to paying into accounts that you control, such as your company's settlement account.

When requesting payment consent, a static payee can be referenced by its account number. The payee name will be populated based on Akahu's static record for the payee and can't be modified:

{
  "source": "STATIC",
  "account_number": "12-1234-1234567-12"
}

Dynamic payees

Dynamic payees use the INLINE source to supply the payee details in the request. The verification_method field determines how Akahu verifies those details, as described below.

Account verification tokens

When you need to specify a payee dynamically, for example to pay a user into one of their own connected accounts, you can verify the payee using an account verification token.

An account verification token is generated for a connected account and confirms that Akahu has verified the account's holder name and account number. When you supply the token, Akahu sources the payee's name and account number directly from it. Because the details come from the token, they cannot be modified by your application.

Generating a token

Generate a token by calling GET /accounts/{id}/verification-token for the connected account you wish to pay. The token is returned in the item field of the response.

Account verification tokens:

  • Can only be generated for BECS-identifiable bank accounts (i.e. regular NZ bank accounts).
  • Require that your application has permission to read the account holder name (the accounts:owner scope).
ℹ️

Account verification tokens are not bound to the application that generated them. A token created by one of your Akahu applications can be used by another. This allows developers to split responsibilities across applications: for example, using one application to verify payees and a separate application to initiate payments.

Using a token

Supply the token when constructing the payment consent request, using the VERIFICATION_TOKEN verification method:

{
  "source": "INLINE",
  "verification_method": "VERIFICATION_TOKEN",
  "verification_token": "{{verification_token}}"
}

Client-verified payees

The CLIENT_VERIFIED verification method lets your application supply the payee name and account number directly, asserting that you have verified the payee yourself. Unlike an account verification token, your application is responsible for verifying the payee rather than Akahu.

This method is only available to clients who have taken on the liability for payee verification, or who are otherwise trusted to provide correct payee details (for example, the issuer of the payee account).

{
  "source": "INLINE",
  "verification_method": "CLIENT_VERIFIED",
  "account_number": "12-1234-1234567-12",
  "name": "James Smith"
}

Unverified payees

The NONE verification method lets your application supply the payee name and account number directly without any verification. This is intended for use cases such as internal admin applications used by developers to access and make payments from their own bank accounts.

Because the payee details are not verified, this method is restricted and must be enabled for your application by Akahu.

{
  "source": "INLINE",
  "verification_method": "NONE",
  "account_number": "12-1234-1234567-12",
  "name": "James Smith"
}

Using verified payees

Verified payees are referenced wherever your application specifies an account to pay.

For enduring payments, payees are included in a payment consent when you request it. See Requesting Payment Consent for how payees fit into a consent request.