Beneficiary Verification

Confirm the registered account holder behind a UAE IBAN before initiating a payment.

Integration guide

Goal: Confirm the account holder's name registered against an IBAN, and whether it matches the beneficiary you intend to pay.

Estimated time: 10 minutes

Prerequisites

Sandbox credentials and an access token
An IBAN to check (optionally the beneficiary name to match)

Beneficiary Verification API Quickstart

When to use

Confirm payee right before initiating a payment, to catch a mistyped or fraudulent IBAN.
Validate account ownership during customer or beneficiary onboarding.
Reduce misdirected-payment and authorised-push-payment fraud.

What it returns

Send an IBAN, and, optionally, the name you expect, to POST /verifications/beneficiary. Spare resolves the registered account holder and returns whether it matches.

Request

Field	Required	Description
`iban`	Yes	The beneficiary IBAN to check.
`beneficiaryName`	No	The name you expect, validated against the bank's records.
`swiftCode`	No	BIC/SWIFT code, reserved for international beneficiaries.

Response (data)

Field	Description
`result`	Match outcome, `MATCH`, `PROBABLE`, `REVIEW`, `NO_MATCH`, or `ERROR`.
`beneficiaryName`	The account holder's name registered at the bank. The bank can return it partly masked, for example `YAH* ABDU* KARE***`.
`inputBeneficiaryName`	The name you supplied, echoed back.
`bank`	Institution details, English/Arabic name, bank code, SWIFT code.
`accountStatus`	Whether the account is active.
`accountIdentifier`	The account identifier the result applies to.
`requestId`	Unique transaction identifier, persist it for support and reconciliation.
`executionDate`	When the check ran.

Integration

Authenticate

Exchange your API credentials for a Bearer access token (see Quick Start Setup). Send it as Authorization: Bearer <access-token> with x-tenant: UAE on every request.

Verify the beneficiary

Submit the IBAN (and optional name) to the verification endpoint:

curl -X POST https://api.sandbox.tryspare.ae/verifications/beneficiary \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant: UAE" \
  -H "Content-Type: application/json" \
  -d '{
    "iban": "AE070331234567890123456",
    "beneficiaryName": "Acme Trading LLC"
  }'

const result = await client.verifications.verifyBeneficiary({
  iban: "AE070331234567890123456",
  beneficiaryName: "Acme Trading LLC",
});

console.log(result.data.result); // "MATCH" | "PROBABLE" | "REVIEW" | "NO_MATCH" | "ERROR"

result = client.verifications.verify_beneficiary(
    iban="AE070331234567890123456",
    beneficiary_name="Acme Trading LLC",
)

print(result.data.result)  # "MATCH" | "PROBABLE" | "REVIEW" | "NO_MATCH" | "ERROR"

var result = client.verifications().verifyBeneficiary(
    VerifyBeneficiaryRequest.builder()
        .iban("AE070331234567890123456")
        .beneficiaryName("Acme Trading LLC")
        .build());

System.out.println(result.getData().getResult());

var result = await client.Verifications.VerifyBeneficiaryAsync(
    new VerifyBeneficiaryRequest
    {
        Iban = "AE070331234567890123456",
        BeneficiaryName = "Acme Trading LLC",
    });

Console.WriteLine(result.Data.Result);

result, err := client.Verifications.VerifyBeneficiary(ctx, spareapi.VerifyBeneficiaryRequest{
    IBAN:            "AE070331234567890123456",
    BeneficiaryName: "Acme Trading LLC",
})
if err != nil {
    panic(err)
}

fmt.Println(result.Data.Result)

Act on the result

Branch on result. When the bank returns the account holder's name masked, Spare compares the name you send with the characters it shows, which is where PROBABLE and REVIEW come from.

MATCH the name is consistent with the expected account holder; proceed with the payment.
PROBABLE strong agreement with minor differences, such as a middle name or family name shown differently.
REVIEW partial agreement. We recommend confirming the account holder before proceeding.
NO_MATCH the name does not agree with the account holder; warn the payer or block, per your risk policy.
ERROR the check could not complete; read errorDescription and retry or fall back.

Persist requestId for reconciliation and support.

Sandbox testing

The sandbox resolves these IBANs to a masked account holder name and scores the name you send against it the same way as in production. Supply the listed name to see the listed result. A close name can return PROBABLE or REVIEW, and an unrelated name returns NO_MATCH.

IBAN	Beneficiary name	Returned name	Result
AE880350000000044457788	Falcon Star Electromechanical LLC	`FAL* STA* ELEC* LLC*`	`MATCH`
AE140260000215900171682	Super Shine Car Wash LLC	`SUP* SHI* CAR* WAS*`	`PROBABLE`
AE220400000000044477788	Yahya Abdul Karim	`YAH* ABDU* KARE***`	`REVIEW`
AE370330000019101801798	Royal Crown Event Management	`IMPE* CRO* EVEN* MANA*`	`NO_MATCH`

Key takeaways

Beneficiary Verification resolves the bank's registered account holder for an IBAN and, when you pass a name, returns a MATCH / PROBABLE / REVIEW / NO_MATCH / ERROR outcome.
Run it as a confirm-payee step immediately before initiating a payment.
Persist requestId for reconciliation and support.

Continue learning

Beneficiary Verification API

Full request and response schema, with a try-it panel.

Payments

Initiate a payment once the payee is confirmed.