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`, `NO_MATCH`, or `ERROR`.
`beneficiaryName`	The account holder's name registered at the bank.
`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" | "NO_MATCH" | "ERROR"

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

print(result.data.result)  # "MATCH" | "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:

MATCH, the account holder matches; proceed with the payment.
NO_MATCH, the name differs; 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.

Key takeaways

Beneficiary Verification resolves the bank's registered account holder for an IBAN and, when you pass a name, returns a MATCH / 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.