SpareSpare Docs
GuidesAPI Reference

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)

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

FieldDescription
ibanThe IBAN to look up
beneficiaryNameOptional. A name to validate against the bank's records

Response

FieldDescription
beneficiaryNameThe bank's registered account owner
bankInstitution details, name (English/Arabic), SWIFT code, bank code
accountStatusWhether the account is active or inactive
resultMATCH, NO-MATCH, or ERROR
requestIdUnique 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.

Sandbox testing

The sandbox resolves these IBANs to a registered owner. Supply the listed name to see a MATCH; supply any other name to see a NO-MATCH.

Match

IBANBeneficiary name
SA02 0548 2877 1759 4474 3614MAHMOUD AL-MASAA
SA02 1012 0407 6563 5517 3154KHAMIS AL-JAFALI
SA02 1090 1704 8587 4890 0789RAED AL MUHAIDIB
SA02 2001 6669 0379 5586 9321KAWTHER AL SAFWAN
SA02 3082 5947 4580 2005 8295HAITHAM AL AYED
SA02 1021 7220 3012 9444 5123Ψ§Ω„Ψ³ΨΉΩˆΨ―ΩŠΨ© Ψ£.Ψ¨Ψ§Ωƒ.Ψ΅Ω†Ψ§ΨΉΨ©

No-match

These IBANs return a NO-MATCH, use any name to test the no-match path.

IBAN
SA26 3055 5687 0483 8074 0916
SA59 6079 4750 4545 4438 6967
SA12 3651 0406 8630 1901 5611
SA86 5506 8980 1402 8124 6132

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.

On this page