Beneficiary Verification (BV)

Retrieve the registered owner behind an IBAN and confirm it matches your intended beneficiary.

Integration guide

Goal: Look up the registered account owner for an IBAN and confirm it matches the beneficiary you intend to pay.

Estimated time: 15 minutes

Prerequisites

Sandbox credentials and an access token
An IBAN to look up (optionally a beneficiary name to match)

Account Verification (AV)Account Verification Pro

When to use

Confirm-payee checks before initiating a transfer
Real-time account-ownership validation during onboarding
Fraud prevention where you need the authenticated owner name

What it returns

Beneficiary Verification (BV) resolves the registered owner of an IBAN and, when you supply a name, whether it matches.

Request inputs

Field	Description
`iban`	The IBAN to look up
`beneficiaryName`	Optional. A name to validate against the bank's records

Response

Field	Description
`beneficiaryName`	The bank's registered account owner
`bank`	Institution details, name (English/Arabic), SWIFT code, bank code
`accountStatus`	Whether the account is active or inactive
`result`	`MATCH`, `NO-MATCH`, or `ERROR`
`requestId`	Unique transaction identifier for support/audit

Integration summary

Authenticate

Obtain a Bearer access token from your API credentials.

Submit the IBAN

Send the IBAN (and optional beneficiary name) to the verification endpoint:

curl -X POST https://sandbox.sparefinancial.sa/api/v2.0/av/BeneficiaryVerification/Match \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "iban": "...", "beneficiaryName": "Acme Trading LLC" }'

const res = await fetch(
  "https://sandbox.sparefinancial.sa/api/v2.0/av/BeneficiaryVerification/Match",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      iban: "...",
      beneficiaryName: "Acme Trading LLC",
    }),
  },
);

const data = await res.json();

import requests

res = requests.post(
    "https://sandbox.sparefinancial.sa/api/v2.0/av/BeneficiaryVerification/Match",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "iban": "...",
        "beneficiaryName": "Acme Trading LLC",
    },
)

data = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

String body = """
    { "iban": "...", "beneficiaryName": "Acme Trading LLC" }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox.sparefinancial.sa/api/v2.0/av/BeneficiaryVerification/Match"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

String result = response.body();

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://sandbox.sparefinancial.sa/api/v2.0/av/BeneficiaryVerification/Match");
request.Headers.Add("Authorization", $"Bearer {accessToken}");
request.Content = new StringContent(
    "{ \"iban\": \"...\", \"beneficiaryName\": \"Acme Trading LLC\" }",
    Encoding.UTF8,
    "application/json");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

package main

import (
	"bytes"
	"io"
	"net/http"
)

payload := []byte(`{ "iban": "...", "beneficiaryName": "Acme Trading LLC" }`)

req, err := http.NewRequest(
	http.MethodPost,
	"https://sandbox.sparefinancial.sa/api/v2.0/av/BeneficiaryVerification/Match",
	bytes.NewReader(payload),
)
if err != nil {
	panic(err)
}

req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")

res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
defer res.Body.Close()

body, _ := io.ReadAll(res.Body)

Parse the result

Use result to decide whether to proceed. Persist requestId for reconciliation and support.

Key takeaways

BV returns the bank's registered owner name for an IBAN, plus a MATCH / NO-MATCH / ERROR result when you supply a name.
Use it for confirm-payee checks right before initiating a transfer.
Persist the requestId for reconciliation and support.

Continue learning

Account Verification Pro

Combined match + beneficiary in one call.

Verification concept

Choosing between AV, BV, and AV Pro.