Account Verification Pro

Verify a bank account and retrieve beneficiary information for retail or corporate accounts in one call.

Integration guide

Goal: Confirm a bank account (IBAN) and its beneficiary for either a retail identity or a corporate entity.

Estimated time: 20 minutes

Prerequisites

Sandbox credentials and an access token
An IBAN plus a retail identity or corporate registration to match

Account Verification (AV)Beneficiary Verification

When to use

Account Verification Pro combines account validity with beneficiary matching, and supports both retail and corporate accounts. Use it when you want one combined check instead of separate AV and BV calls.

How it differs from basic AV

Basic AV exposes one ID-match endpoint. AV Pro adds two endpoints:

Endpoint	For	Key inputs
Match (Retail)	Individuals	`iban`, `idType`, `idValue`, `beneficiaryName` (optional)
Corporate	Businesses	`iban`, `registrationNumber`, `beneficiaryName` (optional)

Both return a single boolean isAccountValid.

Integration summary

Authenticate

Obtain a Bearer access token from your API credentials.

Choose the right endpoint

Use Match for a retail identity, Corporate for a business.

Match (Retail)

curl -X POST https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "iban": "...", "idType": "NATID", "idValue": "...", "beneficiaryName": "Full Name" }'

const res = await fetch(
  "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      iban: "...",
      idType: "NATID",
      idValue: "...",
      beneficiaryName: "Full Name",
    }),
  },
);

const { isAccountValid } = await res.json();

import requests

res = requests.post(
    "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json",
    },
    json={
        "iban": "...",
        "idType": "NATID",
        "idValue": "...",
        "beneficiaryName": "Full Name",
    },
)

data = res.json()
is_account_valid = data["isAccountValid"]

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": "...", "idType": "NATID", "idValue": "...", "beneficiaryName": "Full Name" }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/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());

// Parse the JSON response and read the isAccountValid field
JsonNode data = new ObjectMapper().readTree(response.body());
boolean isAccountValid = data.get("isAccountValid").asBoolean();

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

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Match");
request.Headers.Add("Authorization", $"Bearer {accessToken}");
request.Content = new StringContent(
    "{ \"iban\": \"...\", \"idType\": \"NATID\", \"idValue\": \"...\", \"beneficiaryName\": \"Full Name\" }",
    Encoding.UTF8,
    "application/json");

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

using var doc = JsonDocument.Parse(body);
var isAccountValid = doc.RootElement.GetProperty("isAccountValid").GetBoolean();

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

payload := []byte(`{ "iban": "...", "idType": "NATID", "idValue": "...", "beneficiaryName": "Full Name" }`)

req, err := http.NewRequest(
	http.MethodPost,
	"https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/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()

var data struct {
	IsAccountValid bool `json:"isAccountValid"`
}
json.NewDecoder(res.Body).Decode(&data)

isAccountValid := data.IsAccountValid

Corporate

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

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

const { isAccountValid } = await res.json();

import requests

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

data = res.json()
is_account_valid = data["isAccountValid"]

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": "...", "registrationNumber": "...", "beneficiaryName": "Acme Trading LLC" }
    """;

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

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

// Parse the JSON response and read the isAccountValid field
JsonNode data = new ObjectMapper().readTree(response.body());
boolean isAccountValid = data.get("isAccountValid").asBoolean();

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

using var client = new HttpClient();

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

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

using var doc = JsonDocument.Parse(body);
var isAccountValid = doc.RootElement.GetProperty("isAccountValid").GetBoolean();

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

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

req, err := http.NewRequest(
	http.MethodPost,
	"https://sandbox.sparefinancial.sa/api/v2.1/av/AccountVerificationPro/Corporate",
	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()

var data struct {
	IsAccountValid bool `json:"isAccountValid"`
}
json.NewDecoder(res.Body).Decode(&data)

isAccountValid := data.IsAccountValid

Handle the result

Read isAccountValid and handle no-match and error responses. The sandbox provides pre-validated test data for both match and no-match scenarios across retail and corporate flows.

Key takeaways

AV Pro combines account validity with beneficiary matching and supports both retail and corporate accounts.
Pick the Match endpoint for individuals and Corporate for businesses.
Both return a single isAccountValid boolean, one call instead of separate AV + BV requests.

Continue learning

Account Verification (AV)

The single-endpoint ID match.

Commercial Registration

Full company record lookup.