How it works
To create a recipient, you need to validate and confirm their bank account details. When validating recipient details, we’ll verify the format of account and bank identifiers to ensure they are valid. Where services are available to verify recipient details, we run additional checks. All recipients are created with a validation reason code. Only where services are available to perform name checks on the account will the reason code indicate a match, otherwise the reason code will indicate the check has not been performed. The Confirmation of Payee (CoP) service in the UK checks the recipient name and account details match. For SEPA payments, we also support Verification of Payee (VoP) services. This ensures that the recipient’s details are checked at the point of payment, helping reduce the risk of misdirected funds. Once a recipient’s details have been validated, you’ll confirm the recipient’s details. Confirming a validated recipient transitions them to an AUTHORISED state. This means funds can be sent to this recipient. For more information about the type of details to provide depending on the country that you’re sending money to, see About preferred recipient details.Validate a recipient
POST
/v2/recipients/validateRequest
Query parameters
string
required
The ID of the account that you’re working with.Allowable values: An existing
accountIdRequest body schema
string
required
This represents the identifier of the recipient’s account, such as an Account Number or IBAN. Example:
55555555string
This represents the identifier of the recipient’s bank, such as an a Sort Code, BIC or Routing Number. This field is required if the accountIdentifier provided is not an IBAN. Example:
123456string
required
The name of the recipient. Example:
John Frankstring
Display name for the payee. Example:
Electricianstring
required
The type of account, either
individual,business or charity.string
This is the default reference which will be attached to payments made to the recipient if no reference is defined at the point of making a payment. Where reference is used to form part of an account identifier, this field can be used to form part of an Account details check. Example:
Paying my savings accountstring
required
The currency code of which the recipient will receive payments in, ISO-4217 format. Example:
EURstring
Identifier for intermediary bank. Example:
QBLCCCCVstring
This represents a pre defined purpose for the Payment. This field is required for certain recipients depending on their
currencyCode and bankAddress.countryCode. See more details on payment purpose codes guide. Example: BKFstring
Further free text description for the purpose of the payment Example:
Funding my own accountstring
This indicates a paymentNetwork preference for the payment to be sent by. If the requested payment network cannot be used, the payment will still be processed via an appropriate network to ensure successful delivery.Allowable values:
SWIFT, SEPA.INSTANT, SEPA.CREDITTRANSFER, UKFPS, CHAPS, ACH, WIRETRANSFERarray
This defines the Email addresses who will be sent notifications of payments to this recipient. This array requires a name and an email as input.
object
required
The recipient address object.
string
required
Country code for the recipient’s address. Example:
GBstring
Street address of the recipient. Example:
123 Main Ststring
City of the recipient’s address. Example:
Londonstring
Postal code of the recipient’s address. Example:
SW1A 1AAobject
The recipient’s bank address object.
string
Bank name of the recipient’s bank. Example:
Brilliant Bankstring
Full bank name of the recipient’s bank. Example:
Brilliant Bank PLCstring
Street address of the recipient’s bank. Example:
123 Main Ststring
City of the recipient’s bank address. Example:
Londonstring
Postal code of the recipient’s bank address. Example:
SW1A 1AAstring
required
Country code for the recipient’s bank address. Example:
GBResponse
If your request is successful, you will receive a200 OK response with the following structure:
Reason codes
Reason code categories for matching:- N0xx: General match.
- N1xx: Account not supported or opt out scenarios.
- N2xx: Account details issues (e.g., incorrect number, invalid reference, no name match or close name match).
- N3xx: External factors (e.g. account switched).
- N5xx: External factors (e.g. downstream server side error).
Testing Confirmation of Payee (UK Service)
This table lists the predefined test accounts that should be used to execute specific Confirmation of Payee test scenarios in the sandbox. Each account is configured for a different purpose, such as simulating successful matches, close matches, no matches, or invalid configurations. Where the Reference column is N/A, the reference field should be empty in order for the test scenario to work as expected. We will populate the empty reference with the name of the product you are working on.Confirm a recipient
POST
/v2/recipients/confirmRequest
Use this request to confirm a validated recipient, which will create them on the specified account. If account details verification is required and fails during the validation step, this must be presented to the customer before confirming the recipient.Query parameters
string
required
The ID of the account that you’re creating a recipient for.Allowable values: An existing
accountIdstring
required
The ID of the recipient.Allowable values: An existing
recipientIdRequest body schema
string
required
The method used for verifying the recipient.Allowable values:
sms_otp, phone, email, biometrics, otherResponse
Upon a successful request, you will receive a201 Created response, confirming that the recipient creation process has been completed. If you’ve set up webhooks, you’ll receive a RecipientCreated event when this happens.