Check a payee

Before you send a payout, you can ask the payee’s bank whether the recipient name matches the account. Send the same destination you will send on POST /v2/payouts to POST /v2/payee-checks. You get back one result. The check is optional and moves no money. Conduit runs the same check itself on every UK payout, so a UK payout you create without a check gets the same protection. Use the check to catch a wrong name while your customer is still on the screen. Today a uk_domestic recipient is checked, over faster_payments or chaps. Any other recipient answers unavailable.

Test this flow in sandbox. The sandbox answers each result from the account number you send. The sandbox cheat sheet lists the account numbers.

Prerequisites

Your API key, with write access. A read-only key cannot send this request.
The recipient you will pay: for a UK account, the sort code (6 digits), the account number (8 digits) and the name, exactly as you will send them on the payout.

Step 1 — Check the payee

curl https://api.conduit.financial/v2/payee-checks \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "destination": {
      "type": "fiat",
      "rail": "faster_payments",
      "recipient": {
        "type": "individual",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "sortCode": "404784",
        "accountNumber": "96009001",
        "postalAddress": { ... }
      }
    }
  }'

{
  "result": "close_match"
}

The route takes no Idempotency-Key: each call asks the bank again.

Step 2 — Act on the result

`result`	What it means	What to do
`match`	The name matches the account.	Create the payout.
`close_match`	The details are close to an account, but not an exact match.	Ask your customer to confirm the payee’s name and account type before you create the payout.
`no_match`	The details match no account under this name.	Ask your customer for the correct details before you create the payout.
`unavailable`	The payee’s bank gave no answer, or the recipient has no name check.	Create the payout, or check again later.

Errors

Status	`type`	Cause
`400`	`VALIDATION_ERROR`	A field is missing or has the wrong format, for example a sort code that is not 6 digits, or the request carries an `Idempotency-Key`.
`429`	`RATE_LIMITED`	You sent too many checks in a short time. Wait for the time in `Retry-After`.

What happens next

Send the payout with the same destination.

Getting Started

How Conduit Works

Concepts

How-To Guides

Webhooks

Prerequisites

Step 1 — Check the payee

Step 2 — Act on the result

Errors

What happens next

​Prerequisites

​Step 1 — Check the payee

​Step 2 — Act on the result

​Errors

​What happens next

Prerequisites

Step 1 — Check the payee

Step 2 — Act on the result

Errors

What happens next