Beneficiary Lookup

curl --request POST \
  --url https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "bankCode": "000014",
  "accountNumber": "0123456789"
}
'

import requests

url = "https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup"

payload = {
    "bankCode": "000014",
    "accountNumber": "0123456789"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({bankCode: '000014', accountNumber: '0123456789'})
};

fetch('https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'bankCode' => '000014',
    'accountNumber' => '0123456789'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup"

	payload := strings.NewReader("{\n  \"bankCode\": \"000014\",\n  \"accountNumber\": \"0123456789\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"bankCode\": \"000014\",\n  \"accountNumber\": \"0123456789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"bankCode\": \"000014\",\n  \"accountNumber\": \"0123456789\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": 200,
  "success": true,
  "message": "Account details retrieved successfully",
  "data": {
    "accountNumber": "0123456789",
    "accountName": "JOHN DOE",
    "bankCode": "000014",
    "bankName": "Access Bank"
  }
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

POST

beneficiaries

beneficiary-lookup

Beneficiary Lookup

curl --request POST \
  --url https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "bankCode": "000014",
  "accountNumber": "0123456789"
}
'

import requests

url = "https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup"

payload = {
    "bankCode": "000014",
    "accountNumber": "0123456789"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({bankCode: '000014', accountNumber: '0123456789'})
};

fetch('https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'bankCode' => '000014',
    'accountNumber' => '0123456789'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup"

	payload := strings.NewReader("{\n  \"bankCode\": \"000014\",\n  \"accountNumber\": \"0123456789\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"bankCode\": \"000014\",\n  \"accountNumber\": \"0123456789\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"bankCode\": \"000014\",\n  \"accountNumber\": \"0123456789\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": 200,
  "success": true,
  "message": "Account details retrieved successfully",
  "data": {
    "accountNumber": "0123456789",
    "accountName": "JOHN DOE",
    "bankCode": "000014",
    "bankName": "Access Bank"
  }
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

Validate a Nigerian bank account and retrieve the account holder’s name. Use this to confirm details before creating a beneficiary.

Nigerian accounts only. This confirms an account holder’s name through Nigeria’s NIP name enquiry, which is why it takes a bankCode. There is no equivalent for USD, GBP or EUR — those rails do not allow a name to be confirmed against an account number before a payment is sent, so no provider can offer it.USD support is coming: it will take a routingNumber and return the bank, so you do not have to supply the bank name and address by hand. It will not return an account holder’s name, because that cannot be verified on US rails.

This is the same lookup as Account Lookup on a different path. Either works; use whichever fits your code.

Example Request

curl -X POST "https://api.rolla.xyz/api/v1/external/beneficiaries/beneficiary-lookup" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bankCode": "000014",
    "accountNumber": "0123456789"
  }'

Example Response

{
  "status": 200,
  "success": true,
  "message": "Account details retrieved successfully",
  "data": {
    "accountNumber": "0123456789",
    "accountName": "JOHN DOE",
    "bankCode": "000014",
    "bankName": "Access Bank"
  }
}

Always verify the account name with your user before creating a beneficiary or initiating a payout. Incorrect details may result in failed or misdirected payments.

Authorizations

X-API-Key

string

header

required

Your Rolla API key

Body

application/json

bankCode

string

required

Bank code from /banks endpoint

Example:

"000014"

accountNumber

string

required

10-digit account number

Example:

"0123456789"

Response

Account details retrieved successfully

status

integer

Example:

200

success

boolean

Example:

true

message

string

Example:

"Account details retrieved successfully"

data

object

Show child attributes

Overview

Banks

Account Lookup

Transactions

Wallet

Beneficiaries

Teams

Account Onboarding

Webhooks

Beneficiary Lookup

Example Request

Example Response

Authorizations

Body

Response

​Example Request

​Example Response

Authorizations

Body

Response

Example Request

Example Response