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,
"message": "Account details retrieved successfully",
"success": true,
"data": {
"accountNumber": "0123456789",
"accountName": "JOHN DOE",
"bankCode": "000014",
"bankName": "Access Bank",
"bvn": "",
"accountNameVerified": true
}
}{
"status": 400,
"message": "Bank code is required"
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}{
"status": 404,
"message": "Account not found. Please verify the account number and bank are correct."
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}Beneficiaries
Beneficiary Lookup
Validates a Nigerian bank account through NIP name enquiry and returns the account holder name. Same lookup as POST /lookup, restricted to NGN: currency is optional here and must be NGN if sent.
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,
"message": "Account details retrieved successfully",
"success": true,
"data": {
"accountNumber": "0123456789",
"accountName": "JOHN DOE",
"bankCode": "000014",
"bankName": "Access Bank",
"bvn": "",
"accountNameVerified": true
}
}{
"status": 400,
"message": "Bank code is required"
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}{
"status": 404,
"message": "Account not found. Please verify the account number and bank are correct."
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}Validate a Nigerian bank account and retrieve the account holder’s name. Use this to confirm details before creating a beneficiary.
Any other provider failure returns
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
currency is optional on this path and, if sent, must be NGN.
{
"status": 200,
"message": "Account details retrieved successfully",
"success": true,
"data": {
"accountNumber": "0123456789",
"accountName": "JOHN DOE",
"bankCode": "000014",
"bankName": "Access Bank",
"bvn": "",
"accountNameVerified": true
}
}
accountNameVerified is always true here because the NIP name enquiry returned a real account name. bvn is always empty.
Error Responses
A missing field returns400 with "message": "Bank code is required" or "Account number is required"; a currency other than NGN returns 400 with "message": "Currency must be one of: NGN". An account the bank does not recognise returns 404:
{
"status": 404,
"message": "Account not found. Please verify the account number and bank are correct."
}
500.
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
Your Rolla API key
Body
application/json
Nigerian accounts only. Both fields are trimmed; a blank string counts as absent.
Bank code from GET /banks
Minimum string length:
1Example:
"000014"
10-digit NUBAN account number
Minimum string length:
1Example:
"0123456789"
Optional. Nigerian accounts are the only ones that can be looked up by name, so NGN is the only accepted value and is assumed when the field is omitted. Anything else returns 400 "Currency must be one of: NGN".
Available options:
NGN