Introduction
Welcome to the Ceviant API! Our API provides a collection of services that enable seamless financial operations for users. With our API, users can:
Create a wallet account to store and manage funds.
Initiate loan creation and disbursal for seamless lending operations.
Process payouts to external accounts.
Configure webhooks for:
- Collections: Receive real-time notifications when payments are collected.
- Pending payout responses: Get updates on the status of pending payouts.
We have language bindings in Shell, Ruby, Python, JavaScript, and Java! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Authentication
The Ceviant API uses OAuth2 client credentials for authentication. Merchants are provided with a consumerKey and consumerSecret. To obtain an access token, make a request to the /oauth2/token endpoint as follows:
To obtain an access token, use this code:
# Access Token Request in Ruby
require 'net/http'
require 'uri'
require 'base64'
auth = Base64.strict_encode64("consumer-key:consumer-secret")
uri = URI("https://identity.uat.ceviant/oauth2/token")
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Basic #{auth}"
req.set_form_data('grant_type' => 'client_credentials')
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
# Access Token Request in Ruby
import requests
import base64
auth = base64.b64encode(b"consumer-key:consumer-secret").decode("utf-8")
headers = {"Authorization": f"Basic {auth}"}
data = {"grant_type": "client_credentials"}
response = requests.post("https://identity.uat.ceviant/oauth2/token", headers=headers, data=data)
print(response.json())
# With shell, you can just pass the correct header with each request
curl -k -X POST https://identity.uat.ceviant/oauth2/token \
-d "grant_type=client_credentials" \
-H "Authorization: Basic Base64(consumer-key:consumer-secret)"
// Access Token Request in Ruby
fetch("https://identity.uat.ceviant/oauth2/token", {
method: "POST",
headers: {
"Authorization": "Basic " + btoa("consumer-key:consumer-secret"),
"Content-Type": "application/x-www-form-urlencoded"
},
body: "grant_type=client_credentials"
})
.then(response => response.json())
.then(data => console.log(data));
// Access Token Request in Java
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class OAuthClient {
public static void main(String[] args) throws Exception {
String clientId = "consumer-key";
String clientSecret = "consumer-secret";
String auth = Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes());
URL url = new URL("https://identity.uat.ceviant.co/oauth2/token");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Basic " + auth);
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setDoOutput(true);
String body = "grant_type=client_credentials";
try (OutputStream os = conn.getOutputStream()) {
os.write(body.getBytes());
os.flush();
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The json response payload is::
{
"access_token": "eyJ4NXQiOiJPV1JpTXpaaVlURXhZVEl4WkdGa05UVTJOVE0zTWpkaFltTmxNVFZrTnpRMU56a3paVGc1TVRrNE0yWmxOMkZoWkdaalpURmlNemxsTTJJM1l6ZzJNZyIsImtpZCI6Ik9XUmlNelppWVRFeFlUSXhaR0ZrTlRVMk5UTTNNamRoWW1ObE1UVmtOelExTnprelpUZzVNVGs0TTJabE4yRmhaR1pqWlRGaU16bGxNMkkzWXpnMk1nX1JTMjU2IiwidHlwIjoiYXQrand0IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJPWnZEWWF2SEZta2MwbjllTWtoVG01UEFxNkVhIiwiYXV0IjoiQVBQTElDQVRJT04iLCJhdWQiOiJPWnZEWWF2SEZta2MwbjllTWtoVG01UEFxNkVhIiwibmJmIjoxNzQyMjI2NDcwLCJhenAiOiJPWnZEWWF2SEZta2MwbjllTWtoVG01UEFxNkVhIiwib3JnX2lkIjoiMTAwODRhOGQtMTEzZi00MjExLWEwZDUtZWZlMzZiMDgyMjExIiwiaXNzIjoiaHR0cHM6XC9cL2lkZW50aXR5LnVhdC5jZXZpYW50LmNvXC9vYXV0aDJcL3Rva2VuIiwiZXhwIjoxNzQyMjMwMDcwLCJvcmdfbmFtZSI6IlN1cGVyIiwiaWF0IjoxNzQyMjI2NDcwLCJqdGkiOiI2M2EwMzQyYy00ZDIxLTQ1YTEtODBjNS0yNWM2NThhZGY5M2IiLCJjbGllbnRfaWQiOiJPWnZEWWF2SEZta2MwbjllTWtoVG01UEFxNkVhIn0.eZZgNRlDa2OnkcdcmUVi1XOWajSwXiBqVJ8W-ZVp0UAz3e0QTBACHUV_DZQeql5aGECiejCSDxeupIXbUouhO4vf4gOADWxezO-HrtJXx3Bv-sDFDIr5mGjeyX8iy611nob0ZlW9paCTU1empVW9LJWRbknlQkwL1T8AWXX3h6nV7WIKOtbXx_gvUc9o6OGFWtFUJnyGY9uhE-1HVapT_cfFbwtMuVcpzm6d9A3ocu2VQAc0QkQhLBzIowofsRRj3f8NqUY9a5P2S3WuQQebf2S1NjcGbQAc5M7ynqRPnQZJA9qgsl2jpam_td6ojhnATABY4I9HiF9i2cQ5oybFMw",
"token_type": "Bearer",
"expires_in": 3600
}
Make sure to replace
consumer-keyandconsumer-secretwith your consumerkey and consumer secret values respectively.
Ceviant expects that accesstoken gotten from the /oauth2/token endpoint be included in all API requests to the server in a header that looks like the following:
Authorization: Bearer Token
Fund Transfer
The FundTransfer API provides secure, reliable payment processing capabilities for authorized third-party merchants. This RESTful API enables businesses to initiate, monitor, and manage financial transfers from merchant accounts to recipient accounts through standardized endpoints with comprehensive authentication and validation. With robust error handling and comprehensive documentation, the FundTransfer API offers a seamless integration experience for merchants looking to automate their payment processes.
Create Account
require 'net/http'
require 'uri'
require 'json'
uri = URI("{{baseUrl}}/storedValueAccounts")
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = "Bearer {{access_token}}"
req.body = {
svaCode: "CEVIANT_SANDBOX"
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/storedValueAccounts"
headers = {"Content-Type": "application/json", "Authorization": "Bearer {{access_token}}"}
data = {
"svaCode": "CEVIANT_SANDBOX",
"svaAccountBankCode": "PROVIDUS|FCMB",
"svaAccountName": "cevian-myname"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
curl -X POST "{{baseUrl}}/storedValueAccounts" \
-H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{
"svaCode": "CEVIANT_SANDBOX",
"svaAccountBankCode": "PROVIDUS|FCMB",
"svaAccountName": "cevian-myname"
}'
fetch("{{baseUrl}}/storedValueAccounts", {
method: "POST",
headers: {
"Authorization": "Bearer {{access_token}}",
"Content-Type": "application/json"
},
body: JSON.stringify({
svaCode: "CEVIANT_SANDBOX",
svaAccountBankCode: "PROVIDUS|FCMB",
svaAccountName: "cevian-myname"
})
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class CreateAccount {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/storedValueAccounts");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{" +
"\"svaCode\":\"CEVIANT_SANDBOX\"," +
"\"svaAccountBankCode\":\"PROVIDUS|FCMB\"," +
"\"svaAccountName\":\"cevian-myname\"" +
"}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"id": "8778298b-771c-41cc-b125-9c41b9fb0c53",
"created": "2025-03-17T16:50:57Z",
"updated": "2025-03-17T16:50:57Z",
"svaCode": "CEVIANT_SANDBOX",
"svaAccountName": "Ceviant Sandbox",
"svaAccountNumber": "9997728070",
"svaAccountOfficialBankCode": "101",
"svaAccountBankCode": "PROVIDUS",
"status": "ACTIVE"
}
This endpoint creates a transactionable accounts for the merchant.
HTTP Request
POST {{baseUrl}}/storedValueAccounts
Request Body Parameter
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account to be created |
| svaAccountBankCode | This is the institution from which the svaAccount is created. This could either be PROVIDUS or FCMB at the moment. You will be informed as soon as we have other supported Institutions |
| svaAccountName | The name of the account |
Get Accounts
require 'net/http'
require 'uri'
uri = URI("{{baseUrl}}/storedValueAccounts?svaCode={{svaCode}}")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer {{access_token}}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/storedValueAccounts?svaCode={{svaCode}}"
headers = {"Authorization": "Bearer {{access_token}}"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "{{baseUrl}}/storedValueAccounts?svaCode={{svaCode}}" \
-H "Authorization: Bearer {{access_token}}"
fetch("{{baseUrl}}/storedValueAccounts?svaCode={{svaCode}}", {
method: "GET",
headers: {
"Authorization": "Bearer {{access_token}}"
}
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class GetAccounts {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/storedValueAccounts?svaCode={{svaCode}}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"storedValueAccounts": [
{
"id": "3cc61d2c-c157-47f8-94bc-11df668515c0",
"created": "2025-03-17T16:02:14Z",
"updated": "2025-03-17T16:02:44Z",
"version": 1,
"svaCode": "FUNDING_TESTS",
"svaName": "Funding (SVA) Tests",
"corporateId": "9452e985-6e81-4b3f-b305-f0b0744ac3ca",
"svaAccountName": "Funding (SVA) Tests",
"svaAccountNumber": "9998942031",
"svaAccountOfficialBankCode": "101",
"svaAccountBankCode": "PROVIDUS",
"collectionAccountName": "Ceviant Payment Ltd",
"collectionAccountNumber": "0112345678",
"collectionAccountOfficialBankCode": "101",
"collectionAccountBankCode": "PROVIDUS",
"dailyLimitEnabled": null,
"dailyLimitAmount": null,
"useCeviantCollectionAccount": false,
"exemptRequestIdTimestamp": false,
"fees": [],
"status": "ACTIVE",
"svaAccountLedger": "FINERACT",
"feeApplicationType": null,
"webhookSecretKey": null,
"webhookEnabled": null
}
]
}
This endpoint retrieves the stored value accounts associated with the provided svaCode.
HTTP Request
GET {{baseUrl}}/storedValueAccounts?svaCode={svaCode}
Query Parameter
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account to retrieve the associated accounts |
Get Bank Lists
require 'net/http'
require 'uri'
uri = URI("{{baseUrl}}/accountTransferBanks?svaCode=svaCode")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer {{access_token}}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/accountTransferBanks?svaCode=svaCode"
headers = {"Authorization": "Bearer {{access_token}}"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "{{baseUrl}}/accountTransferBanks?svaCode=svaCode" \
-H "Authorization: Bearer {{access_token}}"
fetch("{{baseUrl}}/accountTransferBanks?svaCode=svaCode", {
method: "GET",
headers: {
"Authorization": "Bearer {{access_token}}"
}
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class GetBankLists {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/accountTransferBanks?svaCode=svaCode");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns an HTTP STATUS CODE OF 200 JSON structured like this:
{
"banks": [
{
"bankName": "ABU MICROFINANCE BANK",
"nibssCode": "090197"
},
{
"bankName": "ACCESS BANK",
"nibssCode": "000014"
},
{
"bankName": "Amac Microfinance Bank",
"nibssCode": "090394"
},
{
"bankName": "AMJU MFB",
"nibssCode": "090180"
},
{
"bankName": "AMML MFB",
"nibssCode": "090116"
},
{
"bankName": "ASOSAVINGS",
"nibssCode": "090001"
},
{
"bankName": "ASTRAPOLARIS MFB",
"nibssCode": "090172"
},
{
"bankName": "Calabar Microfinance Bank",
"nibssCode": "090415"
},
{
"bankName": "CITI BANK",
"nibssCode": "000009"
},
{
"bankName": "CORONATION",
"nibssCode": "060001"
},
{
"bankName": "COVENANT MFB",
"nibssCode": "070006"
},
{
"bankName": "EAGLE FLIGHT MFB",
"nibssCode": "090294"
},
{
"bankName": "ECOBANK BANK",
"nibssCode": "000010"
},
{
"bankName": "FAST Microfinance Bank",
"nibssCode": "090179"
},
{
"bankName": "FCMB",
"nibssCode": "000003"
},
{
"bankName": "FHA MORTGAGE BANK LTD",
"nibssCode": "070026"
},
{
"bankName": "FIDELITY BANK",
"nibssCode": "000007"
},
{
"bankName": "Finca Microfinance Bank",
"nibssCode": "090400"
},
{
"bankName": "Firmus MICROFINANCE BANK",
"nibssCode": "090366"
},
{
"bankName": "FIRST BANK OF NIGERIA",
"nibssCode": "000016"
},
{
"bankName": "FIRST GENERATION MORTGAGE BANK",
"nibssCode": "070014"
},
{
"bankName": "FIRST ROYAL MICROFINANCE BANK",
"nibssCode": "090164"
},
{
"bankName": "FIRSTTRUST MORGAGES LIMITED",
"nibssCode": "090107"
},
{
"bankName": "FORTIS MICROFINANCE BANK",
"nibssCode": "070002"
},
{
"bankName": "FSDH",
"nibssCode": "400001"
},
{
"bankName": "GLOBUS BANK",
"nibssCode": "000027"
},
{
"bankName": "Greenacres MFB",
"nibssCode": "090599"
},
{
"bankName": "GREENBANK MFB",
"nibssCode": "090178"
},
{
"bankName": "GROOMING MICROFINANCE BANK",
"nibssCode": "090195"
},
{
"bankName": "GTBANK PLC",
"nibssCode": "000013"
},
{
"bankName": "HAGGAI MORTGAGE BANK",
"nibssCode": "070017"
},
{
"bankName": "HERITAGE",
"nibssCode": "000020"
},
{
"bankName": "IKIRE MFB",
"nibssCode": "090279"
},
{
"bankName": "JAIZ BANK",
"nibssCode": "000006"
},
{
"bankName": "JUBILEELIFE",
"nibssCode": "090003"
},
{
"bankName": "KEYSTONE BANK",
"nibssCode": "000002"
},
{
"bankName": "KONTAGORA MFB",
"nibssCode": "090299"
},
{
"bankName": "LETSHEGO MICROFINANCE BANK",
"nibssCode": "090420"
},
{
"bankName": "MAYFRESH MORTGAGE BANK",
"nibssCode": "070019"
},
{
"bankName": "Midland MFB",
"nibssCode": "090192"
},
{
"bankName": "MOLUSI MICROFINANCE BANK",
"nibssCode": "090362"
},
{
"bankName": "MUTUAL TRUST MICROFINANCE BANK",
"nibssCode": "090151"
},
{
"bankName": "NEWDAWN MICROFINANCE BANK",
"nibssCode": "090205"
},
{
"bankName": "NPF MICROFINANCE BANK",
"nibssCode": "070001"
},
{
"bankName": "Nwannegadi MFB",
"nibssCode": "090399"
},
{
"bankName": "OMIYE MFB",
"nibssCode": "090295"
},
{
"bankName": "OPAY",
"nibssCode": "100004"
},
{
"bankName": "Oscotech MFB",
"nibssCode": "090396"
},
{
"bankName": "PAGA",
"nibssCode": "100002"
},
{
"bankName": "Peace Microfinance Bank",
"nibssCode": "090402"
},
{
"bankName": "PERSONAL TRUST MICROFINANCE BANK",
"nibssCode": "090135"
},
{
"bankName": "POLARIS BANK",
"nibssCode": "000008"
},
{
"bankName": "POLYUWANNA MFB",
"nibssCode": "090296"
},
{
"bankName": "Preeminent Microfinance Bank",
"nibssCode": "090412"
},
{
"bankName": "SAFE HAVEN MFB",
"nibssCode": "090286"
},
{
"bankName": "SEEDVEST MICROFINANCE BANK",
"nibssCode": "090369"
},
{
"bankName": "STANBICIBTC BANK",
"nibssCode": "000012"
},
{
"bankName": "STANDARDCHARTERED",
"nibssCode": "000021"
},
{
"bankName": "STERLING BANK",
"nibssCode": "000001"
},
{
"bankName": "Sunbeam Microfinance Bank",
"nibssCode": "090302"
},
{
"bankName": "SUNTRUST BANK",
"nibssCode": "000022"
},
{
"bankName": "TAJ BANK",
"nibssCode": "000026"
},
{
"bankName": "TITAN TRUST BANK",
"nibssCode": "000025"
},
{
"bankName": "TRUSTFUND MICROFINANCE BANK",
"nibssCode": "090276"
},
{
"bankName": "UNITED BANK FOR AFRICA",
"nibssCode": "000004"
},
{
"bankName": "UNION BANK",
"nibssCode": "000018"
},
{
"bankName": "UNITY BANK",
"nibssCode": "000011"
},
{
"bankName": "UNN MFB",
"nibssCode": "090251"
},
{
"bankName": "VFD MFB",
"nibssCode": "090110"
},
{
"bankName": "WEMA BANK",
"nibssCode": "000017"
},
{
"bankName": "WinView Bank",
"nibssCode": "090419"
},
{
"bankName": "ZENITH BANK PLC",
"nibssCode": "000015"
},
{
"bankName": "PROVIDUS BANK",
"nibssCode": "999998"
},
{
"bankName": "KUDA MICROFINANCE BANK",
"nibssCode": "090267"
},
{
"bankName": "RAND MERCHANT BANK",
"nibssCode": "000024"
},
{
"bankName": "CENTRAL BANK OF NIGERIA",
"nibssCode": "000028"
},
{
"bankName": "SIGNATURE BANK",
"nibssCode": "000034"
},
{
"bankName": "OPTIMUS BANK",
"nibssCode": "000036"
},
{
"bankName": "AAA FINANCE",
"nibssCode": "050005"
},
{
"bankName": "BRANCH INTERNATIONAL FINANCIAL SERVICES",
"nibssCode": "050006"
},
{
"bankName": "TEKLA FINANCE LTD",
"nibssCode": "050007"
},
{
"bankName": "SIMPLE FINANCE LIMITED",
"nibssCode": "050008"
},
{
"bankName": "FAST CREDIT",
"nibssCode": "050009"
},
{
"bankName": "ENCO FINANCE",
"nibssCode": "050012"
},
{
"bankName": "DIGNITY FINANCE",
"nibssCode": "050013"
},
{
"bankName": "TRINITY FINANCIAL SERVICES LIMITED",
"nibssCode": "050014"
},
{
"bankName": "LUKEFIELD FINANCE COMPANY LIMITED",
"nibssCode": "050015"
},
{
"bankName": "FBNQUEST MERCHANT BANK",
"nibssCode": "060002"
},
{
"bankName": "NOVA MB",
"nibssCode": "060003"
},
{
"bankName": "LBIC MORTGAGE BANK",
"nibssCode": "070012"
},
{
"bankName": "PLATINUM MORTGAGE BANK",
"nibssCode": "070013"
},
{
"bankName": "INFINITY TRUST MORTGAGE BANK",
"nibssCode": "070016"
},
{
"bankName": "COOP MORTGAGE BANK",
"nibssCode": "070021"
},
{
"bankName": "PARRALEX",
"nibssCode": "090004"
},
{
"bankName": "MICROVIS MICROFINANCE BANK",
"nibssCode": "090113"
},
{
"bankName": "EMPIRETRUST MICROFINANCE BANK",
"nibssCode": "090114"
},
{
"bankName": "REGENT MFB",
"nibssCode": "090125"
},
{
"bankName": "BC KASH MFB",
"nibssCode": "090127"
},
{
"bankName": "MONEYTRUST MFB",
"nibssCode": "090129"
},
{
"bankName": "CONSUMER MFB",
"nibssCode": "090130"
},
{
"bankName": "ALLWORKERS MFB",
"nibssCode": "090131"
},
{
"bankName": "AL-BARKAH MFB",
"nibssCode": "090133"
},
{
"bankName": "ROYAL EXCHANGE MICROFINANCE BANK",
"nibssCode": "090138"
},
{
"bankName": "VISA MICROFINANCE BANK",
"nibssCode": "090139"
},
{
"bankName": "SAGAMU MICROFINANCE BANK",
"nibssCode": "090140"
},
{
"bankName": "CHIKUM MICROFINANCE BANK",
"nibssCode": "090141"
},
{
"bankName": "YES MFB",
"nibssCode": "090142"
},
{
"bankName": "APEKS MICROFINANCE BANK",
"nibssCode": "090143"
},
{
"bankName": "CIT MICROFINANCE BANK",
"nibssCode": "090144"
},
{
"bankName": "FULL RANGE MFB",
"nibssCode": "090145"
},
{
"bankName": "TRIDENT MICROFINANCE BANK",
"nibssCode": "090146"
},
{
"bankName": "HACKMAN MICROFINANCE BANK",
"nibssCode": "090147"
},
{
"bankName": "IRL MICROFINANCE BANK",
"nibssCode": "090149"
},
{
"bankName": "VIRTUE MFB",
"nibssCode": "090150"
},
{
"bankName": "FFS MICROFINANCE BANK",
"nibssCode": "090153"
},
{
"bankName": "CEMCS MFB",
"nibssCode": "090154"
},
{
"bankName": "ADVANS LA FAYETTE MFB",
"nibssCode": "090155"
},
{
"bankName": "E-BARCS MFB",
"nibssCode": "090156"
},
{
"bankName": "INFINITY MFB",
"nibssCode": "090157"
},
{
"bankName": "FUTO MFB",
"nibssCode": "090158"
},
{
"bankName": "CREDIT AFRIQUE MFB",
"nibssCode": "090159"
},
{
"bankName": "ADDOSSER MFBB",
"nibssCode": "090160"
},
{
"bankName": "FIRST MULTIPLE MFB",
"nibssCode": "090163"
},
{
"bankName": "PETRA MICROFINANCE BANK",
"nibssCode": "090165"
},
{
"bankName": "ESO-E MICROFINANCE BANK",
"nibssCode": "090166"
},
{
"bankName": "DAYLIGHT MICROFINANCE BANK",
"nibssCode": "090167"
},
{
"bankName": "GASHUA MICROFINANCE BANK",
"nibssCode": "090168"
},
{
"bankName": "ALPHAKAPITAL MFB",
"nibssCode": "090169"
},
{
"bankName": "RAHAMA MFB",
"nibssCode": "090170"
},
{
"bankName": "MAINSTREET MFB",
"nibssCode": "090171"
},
{
"bankName": "RELIANCE MFB",
"nibssCode": "090173"
},
{
"bankName": "MALACHY MFB",
"nibssCode": "090174"
},
{
"bankName": "GIREI MFB",
"nibssCode": "090186"
},
{
"bankName": "BAINES CREDIT MFB",
"nibssCode": "090188"
},
{
"bankName": "ESAN MFB",
"nibssCode": "090189"
},
{
"bankName": "MUTUAL BENEFITS MFB",
"nibssCode": "090190"
},
{
"bankName": "KCMB MFB",
"nibssCode": "090191"
},
{
"bankName": "NIRSAL NATIONAL MICROFINANCE BANK",
"nibssCode": "090194"
},
{
"bankName": "PENNYWISE MICROFINANCE BANK",
"nibssCode": "090196"
},
{
"bankName": "RENMONEY MICROFINANCE BANK",
"nibssCode": "090198"
},
{
"bankName": "YOBE MFB",
"nibssCode": "090252"
},
{
"bankName": "IMO MICROFINANCE BANK",
"nibssCode": "090258"
},
{
"bankName": "ALEKUN MICROFINANCE BANK",
"nibssCode": "090259"
},
{
"bankName": "ABOVE ONLY MICROFINANCE BANK",
"nibssCode": "090260"
},
{
"bankName": "QUICKFUND MICROFINANCE BANK",
"nibssCode": "090261"
},
{
"bankName": "NAVY MICROFINANCE BANK",
"nibssCode": "090263"
},
{
"bankName": "AUCHI MICROFINANCE BANK",
"nibssCode": "090264"
},
{
"bankName": "LOVONUS MICROFINANCE BANK",
"nibssCode": "090265"
},
{
"bankName": "UNIBEN MICROFINANCE BANK",
"nibssCode": "090266"
},
{
"bankName": "ADEYEMI COLLEGE STAFF MICROFINANCE BANK",
"nibssCode": "090268"
},
{
"bankName": "GREENVILLE MICROFINANCE BANK",
"nibssCode": "090269"
},
{
"bankName": "AB MICROFINANCE BANK",
"nibssCode": "090270"
},
{
"bankName": "OLABISI ONABANJO UNIVERSITY MICROFINANCE BANK",
"nibssCode": "090272"
},
{
"bankName": "EMERALDS MFB",
"nibssCode": "090273"
},
{
"bankName": "PRESTIGE MICROFINANCE BANK",
"nibssCode": "090274"
},
{
"bankName": "MERIDIAN MFB",
"nibssCode": "090275"
},
{
"bankName": "ALHAYAT MFB",
"nibssCode": "090277"
},
{
"bankName": "GLORY MFB ",
"nibssCode": "090278"
},
{
"bankName": "MEGAPRAISE MICROFINANCE BANK",
"nibssCode": "090280"
},
{
"bankName": "FIRST OPTION MFB",
"nibssCode": "090285"
},
{
"bankName": "ASSETS MATRIX MFB",
"nibssCode": "090287"
},
{
"bankName": "PILLAR MFB",
"nibssCode": "090289"
},
{
"bankName": "FCT MFB",
"nibssCode": "090290"
},
{
"bankName": "AFEKHAFE MFB",
"nibssCode": "090292"
},
{
"bankName": "ALERT MFB",
"nibssCode": "090297"
},
{
"bankName": "FEDERALPOLY NASARAWAMFB",
"nibssCode": "090298"
},
{
"bankName": "PURPLEMONEY MFB",
"nibssCode": "090303"
},
{
"bankName": "EVANGEL MFB",
"nibssCode": "090304"
},
{
"bankName": "BAYERO MICROFINANCE BANK",
"nibssCode": "090316"
},
{
"bankName": "PATRICK GOLD",
"nibssCode": "090317"
},
{
"bankName": "FEDERAL UNIVERSITY DUTSE MICROFINANCE BANK",
"nibssCode": "090318"
},
{
"bankName": "KADPOLY MICROFINANCE BANK",
"nibssCode": "090320"
},
{
"bankName": "REPHIDIM MICROFINANCE BANK",
"nibssCode": "090322"
},
{
"bankName": "MAINLAND MICROFINANCE BANK",
"nibssCode": "090323"
},
{
"bankName": "BALOGUN GAMBARI MFB",
"nibssCode": "090326"
},
{
"bankName": "TRUST MFB",
"nibssCode": "090327"
},
{
"bankName": "EYOWO MICROFINANCE BANK",
"nibssCode": "090328"
},
{
"bankName": "NEPTUNE MICROFINANCE BANK",
"nibssCode": "090329"
},
{
"bankName": "UNAAB MFB",
"nibssCode": "090331"
},
{
"bankName": "EVERGREEN MICROFINANCE BANK",
"nibssCode": "090332"
},
{
"bankName": "BIPC MICROFINANCE BANK",
"nibssCode": "090336"
},
{
"bankName": "OAU MICROFINANCE BANK LTD",
"nibssCode": "090345"
},
{
"bankName": "CASHCONNECT MICROFINANCE BANK",
"nibssCode": "090360"
},
{
"bankName": "HEADWAY MFB",
"nibssCode": "090363"
},
{
"bankName": "NUTURE MFB",
"nibssCode": "090364"
},
{
"bankName": "ILASAN MICROFINANCE BANK",
"nibssCode": "090370"
},
{
"bankName": "AGOSASA MICROFINANCE BANK",
"nibssCode": "090371"
},
{
"bankName": "LEGEND MICROFINANCE BANK",
"nibssCode": "090372"
},
{
"bankName": "TF MICROFINANCE BANK",
"nibssCode": "090373"
},
{
"bankName": "COASTLINE MICROFINANCE BANK",
"nibssCode": "090374"
},
{
"bankName": "APPLE MICROFINANCE BANK",
"nibssCode": "090376"
},
{
"bankName": "ISALEOYO MICROFINANCE BANK",
"nibssCode": "090377"
},
{
"bankName": "NEW GOLDEN PASTURES MICROFINANCE BANK",
"nibssCode": "090378"
},
{
"bankName": "KREDI MONEY MICROFINANCE BANK",
"nibssCode": "090380"
},
{
"bankName": "MANNY MICROFINANCE BANK",
"nibssCode": "090383"
},
{
"bankName": "GTI MICROFINANCE BANK",
"nibssCode": "090385"
},
{
"bankName": "INTERLAND MFB",
"nibssCode": "090386"
},
{
"bankName": "EK-RELIABLE MICROFINANCE BANK",
"nibssCode": "090389"
},
{
"bankName": "DAVODANI MICROFINANCE BANK",
"nibssCode": "090391"
},
{
"bankName": "MOZFIN MICROFINANCE BANK",
"nibssCode": "090392"
},
{
"bankName": "BRIDGEWAY MICROFINANCE BANK",
"nibssCode": "090393"
},
{
"bankName": "BORGU MFB",
"nibssCode": "090395"
},
{
"bankName": "CHANELLE BANK",
"nibssCode": "090397"
},
{
"bankName": "FEDERAL POLYTECHNIC NEKEDE MICROFINANCE BANK",
"nibssCode": "090398"
},
{
"bankName": "SHEPHERD TRUST MICROFINANCE BANK",
"nibssCode": "090401"
},
{
"bankName": "OLOWOLAGBA MICROFINANCE BANK",
"nibssCode": "090404"
},
{
"bankName": "MONIEPOINT MICROFINANCE BANK",
"nibssCode": "090405"
},
{
"bankName": "BUSINESS SUPPORT MICROFINANCE BANK",
"nibssCode": "090406"
},
{
"bankName": "GMB MICROFINANCE BANK",
"nibssCode": "090408"
},
{
"bankName": "FCMB MFB",
"nibssCode": "090409"
},
{
"bankName": "MARITIME MICROFINANCE BANK",
"nibssCode": "090410"
},
{
"bankName": "GIGINYA MICROFINANCE BANK",
"nibssCode": "090411"
},
{
"bankName": "CHIBUEZE MICROFINANCE BANK",
"nibssCode": "090416"
},
{
"bankName": "IMOWO MICROFINANCE BANK",
"nibssCode": "090417"
},
{
"bankName": "LANDGOLD MICROFINANCE BANK",
"nibssCode": "090422"
},
{
"bankName": "MKOBO MICROFINANCE BANK LTD",
"nibssCode": "090455"
},
{
"bankName": "CATLAND MICROFINANCE BANK",
"nibssCode": "090498"
},
{
"bankName": "BROADVIEW MICROFINANCE BANK LTD",
"nibssCode": "090568"
},
{
"bankName": "QUBE MICROFINANCE BANK LTD",
"nibssCode": "090569"
},
{
"bankName": "IYAMOYE MICROFINANCE BANK LTD",
"nibssCode": "090570"
},
{
"bankName": "ILARO POLY MICROFINANCE BANK LTD",
"nibssCode": "090571"
},
{
"bankName": "EWT MICROFINANCE BANK",
"nibssCode": "090572"
},
{
"bankName": "SNOW MFB",
"nibssCode": "090573"
},
{
"bankName": "GOLDMAN MICROFINANCE BANK LTD",
"nibssCode": "090574"
},
{
"bankName": "FIRSTMIDAS MICROFINANCE BANK LTD",
"nibssCode": "090575"
},
{
"bankName": "OCTOPUS MICROFINANCE BANK LTD",
"nibssCode": "090576"
},
{
"bankName": "IWADE MICROFINANCE BANK LTD",
"nibssCode": "090578"
},
{
"bankName": "GBEDE MICROFINANCE BANK",
"nibssCode": "090579"
},
{
"bankName": "OTECH MICROFINANCE BANK LTD",
"nibssCode": "090580"
},
{
"bankName": "BANC CORP MICROFINANCE BANK LTD",
"nibssCode": "090581"
},
{
"bankName": "STATESIDE MFB",
"nibssCode": "090583"
},
{
"bankName": "ISLAND MICROFINANCE BANK LTD",
"nibssCode": "090584"
},
{
"bankName": "GOMBE MICROFINANCE BANK LTD",
"nibssCode": "090586"
},
{
"bankName": "MICROBIZ MFB",
"nibssCode": "090587"
},
{
"bankName": "ORISUN MFB",
"nibssCode": "090588"
},
{
"bankName": "MERCURY MICROFINANCE BANK",
"nibssCode": "090589"
},
{
"bankName": "WAYA MICROFINANCE BANK LTD",
"nibssCode": "090590"
},
{
"bankName": "GABSYN MFB",
"nibssCode": "090591"
},
{
"bankName": "KANO POLY MFB",
"nibssCode": "090592"
},
{
"bankName": "TASUED MICROFINANCE BANK LTD",
"nibssCode": "090593"
},
{
"bankName": "IBA MFB",
"nibssCode": "090598"
},
{
"bankName": "AVE MARIA MICROFINANCE BANK LTD",
"nibssCode": "090600"
},
{
"bankName": "KENECHUKWU MICROFINANCE BANK",
"nibssCode": "090602"
},
{
"bankName": "MACROD MFB",
"nibssCode": "090603"
},
{
"bankName": "KKU MICROFINANCE BANK",
"nibssCode": "090606"
},
{
"bankName": "AKPO MICROFINANCE BANK",
"nibssCode": "090608"
},
{
"bankName": "UMMAH MICROFINANCE BANK",
"nibssCode": "090609"
},
{
"bankName": "AMOYE MICROFINANCE BANK",
"nibssCode": "090610"
},
{
"bankName": "CREDITVILLE MFB",
"nibssCode": "090611"
},
{
"bankName": "MEDEF MFB",
"nibssCode": "090612"
},
{
"bankName": "TOTAL TRUST MICROFINANCE BANK",
"nibssCode": "090613"
},
{
"bankName": "FLOURISH MFB",
"nibssCode": "090614"
},
{
"bankName": "BESTSTAR MFB",
"nibssCode": "090615"
},
{
"bankName": "RAYYAN MFB",
"nibssCode": "090616"
},
{
"bankName": "IYIN EKITI MFB",
"nibssCode": "090620"
},
{
"bankName": "GIDAUNIYAR ALHERI MICROFINANCE BANK",
"nibssCode": "090621"
},
{
"bankName": "ROYAL BLUE MFB",
"nibssCode": "090622"
},
{
"bankName": "MAB ALLIANZ MFB",
"nibssCode": "090623"
},
{
"bankName": "PARKWAY-READYCASH",
"nibssCode": "100003"
},
{
"bankName": "CELLULANT",
"nibssCode": "100005"
},
{
"bankName": "ETRANZACT",
"nibssCode": "100006"
},
{
"bankName": "STANBIC IBTC @EASE WALLET",
"nibssCode": "100007"
},
{
"bankName": "ECOBANK XPRESS ACCOUNT",
"nibssCode": "100008"
},
{
"bankName": "TEASYMOBILE",
"nibssCode": "100010"
},
{
"bankName": "ACCESSMONEY",
"nibssCode": "100013"
},
{
"bankName": "FIRSTMONIE WALLET",
"nibssCode": "100014"
},
{
"bankName": "FORTISMOBILE",
"nibssCode": "100016"
},
{
"bankName": "FIDELITY MOBILE",
"nibssCode": "100019"
},
{
"bankName": "KONGAPAY",
"nibssCode": "100025"
},
{
"bankName": "CONTEC GLOBAL",
"nibssCode": "100032"
},
{
"bankName": "PALMPAY",
"nibssCode": "100033"
},
{
"bankName": "ZWALLET",
"nibssCode": "100034"
},
{
"bankName": "M36",
"nibssCode": "100035"
},
{
"bankName": "LEADREMIT LIMITED",
"nibssCode": "110044"
},
{
"bankName": "9 PAYMENT SERVICE BANK",
"nibssCode": "120001"
},
{
"bankName": "HOPEPSB",
"nibssCode": "120002"
},
{
"bankName": "NEW PRUDENTIAL BANK",
"nibssCode": "090108"
},
{
"bankName": "XPRESS PAYMENTS",
"nibssCode": "090201"
},
{
"bankName": "ACCELEREX NETWORK",
"nibssCode": "090202"
},
{
"bankName": "ITEX INTEGRATED SERVICES LIMITED",
"nibssCode": "090211"
},
{
"bankName": "GTMOBILE",
"nibssCode": "100009"
},
{
"bankName": "MKUDI",
"nibssCode": "100011"
},
{
"bankName": "ZENITHMOBILE",
"nibssCode": "100018"
},
{
"bankName": "INNOVECTIVES KESH",
"nibssCode": "100029"
},
{
"bankName": "PAYATTITUDE ONLINE",
"nibssCode": "110001"
},
{
"bankName": "FLUTTERWAVE TECHNOLOGY SOLUTIONS LIMITED",
"nibssCode": "110002"
},
{
"bankName": "INTERSWITCH LIMITED",
"nibssCode": "110003"
},
{
"bankName": "3LINE CARD MANAGEMENT LIMITED",
"nibssCode": "110005"
},
{
"bankName": "PAYSTACK PAYMENTS LIMITED",
"nibssCode": "110006"
},
{
"bankName": "TEAM APT",
"nibssCode": "110007"
},
{
"bankName": "KADICK INTEGRATION LIMITED",
"nibssCode": "110008"
},
{
"bankName": "CELLULANT PSSP",
"nibssCode": "110012"
},
{
"bankName": "QR PAYMENTS",
"nibssCode": "110013"
},
{
"bankName": "Nibss Test",
"nibssCode": "999032"
}
]
}
The above command returns a HTTP STATUS CODE OF 404 JSON structured like this:
{
"message": "Can't find stored value account with sva code BABS",
"statusCode": 404,
"reasonCode": "NOT_FOUND",
"reasonCodeStr": "NOT_FOUND",
"suppressed": []
}
This endpoint retrieves the list of banks available for account transfers.
HTTP Request
GET {{baseUrl}}/accountTransferBanks?svaCode=svaCode
Query Parameter
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account to retrieve the bank list for |
Account Enquiry
require 'net/http'
require 'uri'
uri = URI("{{baseUrl}}/accountValidations?svaCode=CEVIANT&accountNumber=1115420507&institutionCode=090110")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer {{access_token}}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/accountValidations?svaCode=CEVIANT&accountNumber=0115420507&institutionCode=090110"
headers = {"Authorization": "Bearer {{access_token}}"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "{{baseUrl}}/accountValidations?svaCode=CEVIANT&accountNumber=0115420507&institutionCode=090110" \
-H "Authorization: Bearer {{access_token}}"
fetch("{{baseUrl}}/accountValidations?svaCode=CEVIANT&accountNumber=0115420507&institutionCode=090110", {
method: "GET",
headers: {
"Authorization": "Bearer {{access_token}}"
}
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class GetLoanStatus {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/accountValidations?svaCode=CEVIANT&accountNumber=0115420507&institutionCode=090110");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns JSON structured like this:
{
"accountName": "ceviant ceviant"
}
This endpoint is use to validate a beneficiary account.
HTTP Request
GET {{baseUrl}}/accountValidations?svaCode=CEVIANT&accountNumber=0115420507&institutionCode=090110
Query Parameter
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account |
| accountNumber | Beneficiary nuban account number |
| institutionCode | NIBSS institution code for the beneficiary bank |
Account Balance Enquiry
require 'net/http'
require 'uri'
uri = URI("{{baseUrl}}/accountBalances?svaCode=CEVIANT&accountId={accountId}")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer {{access_token}}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/accountBalances?svaCode=CEVIANT&accountId={accountId}"
headers = {"Authorization": "Bearer {{access_token}}"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "{{baseUrl}}/accountBalances?svaCode=CEVIANT&accountId={accountId}" \
-H "Authorization: Bearer {{access_token}}"
fetch("{{baseUrl}}/accountBalances?svaCode=CEVIANT", {
method: "GET",
headers: {
"Authorization": "Bearer {{access_token}}"
}
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class GetLoanStatus {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/accountBalances?svaCode=CEVIANT&accountId={accountId}");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP status code of 200 JSON structured like this:
{
"balanceAmount": 561231678604.34
}
The above command returns HTTP status code of 404 JSON structured like this:
{
"message": "Can't find stored value account with sva code CEVIANT2",
"statusCode": 404,
"reasonCode": "NOT_FOUND",
"reasonCodeStr": "NOT_FOUND",
"suppressed": []
}
This endpoint retrieves the merchant account balance.
HTTP Request
GET {{baseUrl}}/accountBalances?svaCode={svaCode}&accountId={accountId}
Query Parameter
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account for the merchant |
| accountId | The id of the account to check balance on |
Single Transfer
require 'net/http'
require 'uri'
require 'json'
uri = URI("{{baseUrl}}/accountTransfers")
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = "Bearer {{access_token}}"
req.body = {
narration: "test",
transferInitiatorName: "Sesan",
beneficiaryAccountNumber: "0115420506",
beneficiaryAccountName: "Tunde Daniel",
beneficiaryInstitutionCode: "000013",
requestId: "FUNDING_TESTS-20250317163300-0001",
amount: "300",
transactionDate: "2025-03-17T16:36:20",
currency: "NGN",
svaCode: "FUNDING_TESTS",
accountId: "3cc61d2c-c157-47f8-94bc-11df668515c0"
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/accountTransfers"
headers = {"Content-Type": "application/json", "Authorization": "Bearer {{access_token}}"}
data = {
"narration": "test",
"transferInitiatorName": "Sesan",
"beneficiaryAccountNumber": "0115420506",
"beneficiaryAccountName": "Tunde Daniel",
"beneficiaryInstitutionCode": "000013",
"requestId": "FUNDING_TESTS-20250317163300-0001",
"amount": "300",
"transactionDate": "2025-03-17T16:36:20",
"currency": "NGN",
"svaCode": "FUNDING_TESTS",
"accountId": "3cc61d2c-c157-47f8-94bc-11df668515c0"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
curl -X POST "{{baseUrl}}/accountTransfers" \
-H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{
"narration": "test",
"transferInitiatorName": "Sesan",
"beneficiaryAccountNumber": "0115420506",
"beneficiaryAccountName": "Tunde Daniel",
"beneficiaryInstitutionCode": "000013",
"requestId": "FUNDING_TESTS-20250317163300-0001",
"amount": "300",
"transactionDate": "2025-03-17T16:36:20",
"currency": "NGN",
"svaCode": "FUNDING_TESTS",
"accountId": "3cc61d2c-c157-47f8-94bc-11df668515c0"
}'
fetch("{{baseUrl}}/accountTransfers", {
method: "POST",
headers: {
"Authorization": "Bearer {{access_token}}",
"Content-Type": "application/json"
},
body: JSON.stringify({
narration: "test",
transferInitiatorName: "Sesan",
beneficiaryAccountNumber: "0115420506",
beneficiaryAccountName: "Tunde Daniel",
beneficiaryInstitutionCode: "000013",
requestId: "FUNDING_TESTS-20250317163300-0001",
amount: "300",
transactionDate: "2025-03-17T16:36:20",
currency: "NGN",
svaCode: "FUNDING_TESTS",
accountId: "3cc61d2c-c157-47f8-94bc-11df668515c0"
})
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class SingleTransfer {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/accountTransfers");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{" +
"\"narration\":\"test\"," +
"\"transferInitiatorName\":\"Sesan\"," +
"\"beneficiaryAccountNumber\":\"0115420506\"," +
"\"beneficiaryAccountName\":\"Tunde Daniel\"," +
"\"beneficiaryInstitutionCode\":\"000013\"," +
"\"requestId\":\"FUNDING_TESTS-20250317163300-0001\"," +
"\"amount\":\"300\"," +
"\"transactionDate\":\"2025-03-17T16:36:20\"," +
"\"currency\":\"NGN\"," +
"\"svaCode\":\"FUNDING_TESTS\"," +
"\"accountId\":\"3cc61d2c-c157-47f8-94bc-11df668515c0\"" +
"}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"requestId": "<string>",
"accountTransferId": "<string>",
"transactionId": "<string>",
"sessionId": "<string>",
"responseCode": "APPROVED",
"responseCodeReason": "<string>",
"responseMessage": "<string>"
}
This endpoint initiates a single transfer from the originating account to the receiving account.
HTTP Request
POST {{baseUrl}}/accountTransfers
Request Body Parameter
| Parameter | Description |
|---|---|
| narration | The narration for the transfer |
| transferInitiatorName | The name of the transfer initiator |
| beneficiaryAccountNumber | The account number of the beneficiary |
| beneficiaryAccountName | The account name of the beneficiary |
| beneficiaryInstitutionCode | The nibss institution code of the beneficiary's bank |
| requestId | A unique identifier for the transfer request. It is in this format SVA_CODE-YYYYMMDDHHmmSS-FOUR_DIGIT_RANDOM_NUMBER |
| amount | The amount to be transferred |
| transactionDate | The date of the transaction. It is in this format yyyy-MM-ddTHH:mm:SS |
| currency | The currency of the transfer |
| svaCode | The code of the stored value account |
| accountId | The ID of the originating account |
Response Body Payload
| Parameter | Description |
|---|---|
| requestId | The unique identifier for the transfer request |
| accountTransferId | The debited account id belonging to the svaCode |
| transactionId | external transaction ref gotten from provider |
| sessionId | sessionId gotten from the provider |
| responseCode | Indicates the transaction status: APPROVED (Transaction completed successfully), PENDING (Queued for processing), DECLINED (Debit from the SVA account failed due to insufficient balance, inactivity, or other reasons), IN_PROGRESS (Debit was successful, and credit to the beneficiary is in progress), FAILED (Credit to the beneficiary account failed after multiple retries, leading to transaction failure). |
| responseCodeReason | Description of the responseCode |
| responseMessage | Human understandable message for the responseCode |
Note
Only transactions with a PENDING, IN_PROGRESS, PENDING_SINGLE_INSTANT, IN_PROGRESS_SINGLE, IN_PROGRESS_SINGLE_INSTANT status should be checked for updates. Transactions marked as DECLINED or FAILED are considered unsuccessful.
Single Instant Transfer
require 'net/http'
require 'uri'
require 'json'
uri = URI("{{baseUrl}}/accountTransfers")
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = "Bearer {{access_token}}"
req.body = {
narration: "test",
transferInitiatorName: "Sesan",
beneficiaryAccountNumber: "0115420506",
beneficiaryAccountName: "Tunde Daniel",
beneficiaryInstitutionCode: "000013",
requestId: "FUNDING_TESTS-20250317163300-0001",
amount: "300",
transactionDate: "2025-03-17T16:36:20",
currency: "NGN",
svaCode: "FUNDING_TESTS",
accountId: "3cc61d2c-c157-47f8-94bc-11df668515c0"
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/accountTransfers"
headers = {"Content-Type": "application/json", "Authorization": "Bearer {{access_token}}"}
data = {
"narration": "test",
"transferInitiatorName": "Sesan",
"beneficiaryAccountNumber": "0115420506",
"beneficiaryAccountName": "Tunde Daniel",
"beneficiaryInstitutionCode": "000013",
"requestId": "FUNDING_TESTS-20250317163300-0001",
"amount": "300",
"transactionDate": "2025-03-17T16:36:20",
"currency": "NGN",
"svaCode": "FUNDING_TESTS",
"accountId": "3cc61d2c-c157-47f8-94bc-11df668515c0"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
curl -X POST "{{baseUrl}}/accountTransfers" \
-H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{
"narration": "test",
"transferInitiatorName": "Sesan",
"beneficiaryAccountNumber": "0115420506",
"beneficiaryAccountName": "Tunde Daniel",
"beneficiaryInstitutionCode": "000013",
"requestId": "FUNDING_TESTS-20250317163300-0001",
"amount": "300",
"transactionDate": "2025-03-17T16:36:20",
"currency": "NGN",
"svaCode": "FUNDING_TESTS",
"accountId": "3cc61d2c-c157-47f8-94bc-11df668515c0"
}'
fetch("{{baseUrl}}/accountTransfers", {
method: "POST",
headers: {
"Authorization": "Bearer {{access_token}}",
"Content-Type": "application/json"
},
body: JSON.stringify({
narration: "test",
transferInitiatorName: "Sesan",
beneficiaryAccountNumber: "0115420506",
beneficiaryAccountName: "Tunde Daniel",
beneficiaryInstitutionCode: "000013",
requestId: "FUNDING_TESTS-20250317163300-0001",
amount: "300",
transactionDate: "2025-03-17T16:36:20",
currency: "NGN",
svaCode: "FUNDING_TESTS",
accountId: "3cc61d2c-c157-47f8-94bc-11df668515c0"
})
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class SingleTransfer {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/accountTransfers");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{" +
"\"narration\":\"test\"," +
"\"transferInitiatorName\":\"Sesan\"," +
"\"beneficiaryAccountNumber\":\"0115420506\"," +
"\"beneficiaryAccountName\":\"Tunde Daniel\"," +
"\"beneficiaryInstitutionCode\":\"000013\"," +
"\"requestId\":\"FUNDING_TESTS-20250317163300-0001\"," +
"\"amount\":\"300\"," +
"\"transactionDate\":\"2025-03-17T16:36:20\"," +
"\"currency\":\"NGN\"," +
"\"svaCode\":\"FUNDING_TESTS\"," +
"\"accountId\":\"3cc61d2c-c157-47f8-94bc-11df668515c0\"" +
"}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"requestId": "<string>",
"accountTransferId": "<string>",
"transactionId": "<string>",
"sessionId": "<string>",
"responseCode": "APPROVED",
"responseCodeReason": "<string>",
"responseMessage": "<string>"
}
This endpoint is the same as single transfer but its faster and it is not advisable to be used when pushing a lot of single transfer traffic. It initiates a single transfer from the originating account to the receiving account.
HTTP Request
POST {{baseUrl}}/single/accountTransfers
Request Body Parameter
| Parameter | Description |
|---|---|
| narration | The narration for the transfer |
| transferInitiatorName | The name of the transfer initiator |
| beneficiaryAccountNumber | The account number of the beneficiary |
| beneficiaryAccountName | The account name of the beneficiary |
| beneficiaryInstitutionCode | The nibss institution code of the beneficiary's bank |
| requestId | A unique identifier for the transfer request. It is in this format SVA_CODE-YYYYMMDDHHmmSS-FOUR_DIGIT_RANDOM_NUMBER |
| amount | The amount to be transferred |
| transactionDate | The date of the transaction. It is in this format yyyy-MM-ddTHH:mm:SS |
| currency | The currency of the transfer |
| svaCode | The code of the stored value account |
| accountId | The ID of the originating account |
Response Body Payload
| Parameter | Description |
|---|---|
| requestId | The unique identifier for the transfer request |
| accountTransferId | The debited account id belonging to the svaCode |
| transactionId | external transaction ref gotten from provider |
| sessionId | sessionId gotten from the provider |
| responseCode | Indicates the transaction status: APPROVED (Transaction completed successfully), PENDING (Queued for processing), DECLINED (Debit from the SVA account failed due to insufficient balance, inactivity, or other reasons), IN_PROGRESS (Debit was successful, and credit to the beneficiary is in progress), FAILED (Credit to the beneficiary account failed after multiple retries, leading to transaction failure). |
| responseCodeReason | Description of the responseCode |
| responseMessage | Human understandable message for the responseCode |
Note
Only transactions with a PENDING, IN_PROGRESS, PENDING_SINGLE_INSTANT, IN_PROGRESS_SINGLE, IN_PROGRESS_SINGLE_INSTANT status should be checked for updates. Transactions marked as DECLINED or FAILED are considered unsuccessful.
Single Transfer Status
require 'net/http'
require 'uri'
uri = URI("{{baseUrl}}/accountTransferStatus?svaCode=CEVIANT&requestId=CEVIANT-20250307181620-111000")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer {{access_token}}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/accountTransferStatus?svaCode=CEVIANT&requestId=CEVIANT-20250307181620-111000"
headers = {"Authorization": "Bearer {{access_token}}"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "{{baseUrl}}/accountTransferStatus?svaCode=CEVIANT&requestId=CEVIANT-20250307181620-111000" \
-H "Authorization: Bearer {{access_token}}"
fetch("{{baseUrl}}/accountTransferStatus?svaCode=CEVIANT&requestId=CEVIANT-20250307181620-111000", {
method: "GET",
headers: {
"Authorization": "Bearer {{access_token}}"
}
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class SingleTransferStatus {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/accountTransferStatus?svaCode=CEVIANT&requestId=CEVIANT-20250307181620-111000");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"requestId": "<string>",
"accountTransferId": "<string>",
"transactionId": "<string>",
"sessionId": "<string>",
"status": "APPROVED",
"statusReason": "<string>",
"responseMessage": "<string>"
}
The above command returns NOT_FOUND JSON structured like this:
{
"requestId": "CEVIANT-20250307181620-111000",
"accountTransferId": null,
"transactionId": null,
"sessionId": null,
"status": "NOT_FOUND",
"statusReason": "NOT_FOUND",
"responseMessage": "No request found with requestId: CEVIANT-20250307181620-111000"
}
This endpoint retrieves the status of a specific transfer.
HTTP Request
GET {{baseUrl}}/accountTransferStatus?svaCode=CEVIANT&requestId=CEVIANT-20250307181620-111000
Query Parameter
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account |
| requestId | The unique identifier for the transfer request |
Response Body Payload
| Parameter | Description |
|---|---|
| requestId | The unique identifier for the transfer request |
| accountTransferId | The debited account id belonging to the svaCode |
| transactionId | external transaction ref gotten from provider |
| sessionId | sessionId gotten from the provider |
| status | Indicates the transaction status: APPROVED (Transaction completed successfully), PENDING (Queued for processing), DECLINED (Debit from the SVA account failed due to insufficient balance, inactivity, or other reasons), IN_PROGRESS (Debit was successful, and credit to the beneficiary is in progress), FAILED (Credit to the beneficiary account failed after multiple retries, leading to transaction failure). |
| statusCodeReason | Description of the statusCode |
| responseMessage | Human understandable message for the statusCode |
Note
Only transactions with a PENDING, IN_PROGRESS, PENDING_SINGLE_INSTANT, IN_PROGRESS_SINGLE, IN_PROGRESS_SINGLE_INSTANT status should be checked for updates. Transactions marked as DECLINED or FAILED are considered unsuccessful.
Bulk Transfer
require 'net/http'
require 'uri'
require 'json'
uri = URI("{{baseUrl}}/bulk/accountTransfers")
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = "Bearer {{access_token}}"
req.body = {
svaCode: "FUNDING_TESTS",
transfers: [
{
narration: "test",
transferInitiatorName: "Sesan",
beneficiaryAccountNumber: "0115420506",
beneficiaryAccountName: "Tunde Daniel",
beneficiaryInstitutionCode: "000013",
requestId: "FUNDING_TESTS-20250317161853-0001",
amount: "300",
transactionDate: "2025-03-17T16:18:53",
currency: "NGN",
svaCode: null,
accountId: "3cc61d2c-c157-47f8-94bc-11df668515c0"
}
]
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/bulk/accountTransfers"
headers = {"Content-Type": "application/json", "Authorization": "Bearer {{access_token}}"}
data = {
"svaCode": "FUNDING_TESTS",
"transfers": [
{
"narration": "test",
"transferInitiatorName": "Sesan",
"beneficiaryAccountNumber": "0115420506",
"beneficiaryAccountName": "Tunde Daniel",
"beneficiaryInstitutionCode": "000013",
"requestId": "FUNDING_TESTS-20250317161853-0001",
"amount": "300",
"transactionDate": "2025-03-17T16:18:53",
"currency": "NGN",
"svaCode": null,
"accountId": "3cc61d2c-c157-47f8-94bc-11df668515c0"
}
]
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
curl -X POST "{{baseUrl}}/bulk/accountTransfers" \
-H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{
"svaCode": "FUNDING_TESTS",
"transfers": [
{
"narration": "test",
"transferInitiatorName": "Sesan",
"beneficiaryAccountNumber": "0115420506",
"beneficiaryAccountName": "Tunde Daniel",
"beneficiaryInstitutionCode": "000013",
"requestId": "FUNDING_TESTS-20250317161853-0001",
"amount": "300",
"transactionDate": "2025-03-17T16:18:53",
"currency": "NGN",
"svaCode": null,
"accountId": "3cc61d2c-c157-47f8-94bc-11df668515c0"
}
]
}'
fetch("{{baseUrl}}/bulk/accountTransfers", {
method: "POST",
headers: {
"Authorization": "Bearer {{access_token}}",
"Content-Type": "application/json"
},
body: JSON.stringify({
svaCode: "FUNDING_TESTS",
transfers: [
{
narration: "test",
transferInitiatorName: "Sesan",
beneficiaryAccountNumber: "0115420506",
beneficiaryAccountName: "Tunde Daniel",
beneficiaryInstitutionCode: "000013",
requestId: "FUNDING_TESTS-20250317161853-0001",
amount: "300",
transactionDate: "2025-03-17T16:18:53",
currency: "NGN",
svaCode: null,
accountId: "3cc61d2c-c157-47f8-94bc-11df668515c0"
}
]
})
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class BulkTransfer {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/bulk/accountTransfers");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{" +
"\"svaCode\":\"FUNDING_TESTS\"," +
"\"transfers\":[" +
"{" +
"\"narration\":\"test\"," +
"\"transferInitiatorName\":\"Sesan\"," +
"\"beneficiaryAccountNumber\":\"0115420506\"," +
"\"beneficiaryAccountName\":\"Tunde Daniel\"," +
"\"beneficiaryInstitutionCode\":\"000013\"," +
"\"requestId\":\"FUNDING_TESTS-20250317161853-0001\"," +
"\"amount\":\"300\"," +
"\"transactionDate\":\"2025-03-17T16:18:53\"," +
"\"currency\":\"NGN\"," +
"\"svaCode\":null," +
"\"accountId\":\"3cc61d2c-c157-47f8-94bc-11df668515c0\"" +
"}" +
"]" +
"}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"bulkRequestStatus": "OK",
"bulkRequestStatusReason": "<string>",
"bulkRequestStatusMessage": "<string>",
"transferResponses": [
{
"requestId": "FUNDING_TESTS-20250317161853-0001",
"accountTransferId": "<string>",
"transactionId": "<string>",
"sessionId": "<string>",
"responseCode": "APPROVED",
"responseCodeReason": "<string>",
"responseMessage": "<string>"
}
]
}
This endpoint initiates a bulk transfer from the originating account to multiple receiving accounts.
HTTP Request
POST {{baseUrl}}/bulk/accountTransfers
Request Body Parameter
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account |
| transfers | An array of transfer objects |
| transfers[].narration | The narration for the transfer |
| transfers[].transferInitiatorName | The name of the transfer initiator |
| transfers[].beneficiaryAccountNumber | The account number of the beneficiary |
| transfers[].beneficiaryAccountName | The account name of the beneficiary |
| transfers[].beneficiaryInstitutionCode | The institution code of the beneficiary's bank |
| transfers[].requestId | A unique identifier for the transfer request |
| transfers[].amount | The amount to be transferred |
| transfers[].transactionDate | The date of the transaction |
| transfers[].currency | The currency of the transfer |
| transfers[].svaCode | The code of the stored value account (optional) |
| transfers[].accountId | The ID of the originating account |
Bulk Transfer Status
require 'net/http'
require 'uri'
require 'json'
uri = URI("{{baseUrl}}/bulk/accountTransferStatus")
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = "Bearer {{access_token}}"
req.body = {
svaCode: "CEVIANT",
requestIds: [
"CEVIANT-20250307183701-11100",
"CEVIANT-20250307183701-11101"
]
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/bulk/accountTransferStatus"
headers = {"Content-Type": "application/json", "Authorization": "Bearer {{access_token}}"}
data = {
"svaCode": "CEVIANT",
"requestIds": [
"CEVIANT-20250307183701-11100",
"CEVIANT-20250307183701-11101"
]
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
curl -X POST "{{baseUrl}}/bulk/accountTransferStatus" \
-H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{
"svaCode": "CEVIANT",
"requestIds": [
"CEVIANT-20250307183701-11100",
"CEVIANT-20250307183701-11101"
]
}'
fetch("{{baseUrl}}/bulk/accountTransferStatus", {
method: "POST",
headers: {
"Authorization": "Bearer {{access_token}}",
"Content-Type": "application/json"
},
body: JSON.stringify({
svaCode: "CEVIANT",
requestIds: [
"CEVIANT-20250307183701-11100",
"CEVIANT-20250307183701-11101"
]
})
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class BulkTransferStatus {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/bulk/accountTransferStatus");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{" +
"\"svaCode\":\"CEVIANT\"," +
"\"requestIds\":[" +
"\"CEVIANT-20250307183701-11100\"," +
"\"CEVIANT-20250307183701-11101\"" +
"]" +
"}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"bulkRequestStatus": "OK",
"bulkRequestStatusReason": "<string>",
"bulkRequestStatusMessage": "<string>",
"transferResponses": [
{
"requestId": "<string>",
"accountTransferId": "<string>",
"transactionId": "<string>",
"sessionId": "<string>",
"responseCode": "PENDING",
"responseCodeReason": "<string>",
"responseMessage": "<string>"
},
{
"requestId": "<string>",
"accountTransferId": "<string>",
"transactionId": "<string>",
"sessionId": "<string>",
"responseCode": "DECLINED",
"responseCodeReason": "<string>",
"responseMessage": "<string>"
}
]
}
This endpoint retrieves the status of multiple transfer requests.
HTTP Request
POST {{baseUrl}}/bulk/accountTransferStatus
Request Body Parameter
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account |
| requestIds | An array of request IDs to retrieve the status for |
Transaction History
require 'net/http'
require 'uri'
uri = URI("{{baseUrl}}/accountTransferTransactions?svaCode=svaCode&startDate=2025-01-01&endDate=2025-03-16&page=1&size=100&accountId=cf7f07f2-1938-468a-9569-d811243494b1")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer {{access_token}}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/accountTransferTransactions?svaCode=svaCode&startDate=2025-01-01&endDate=2025-03-16&page=1&size=100&accountId=cf7f07f2-1938-468a-9569-d811243494b1"
headers = {"Authorization": "Bearer {{access_token}}"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "{{baseUrl}}/accountTransferTransactions?svaCode=svaCode&startDate=2025-01-01&endDate=2025-03-16&page=1&size=100&accountId=cf7f07f2-1938-468a-9569-d811243494b1" \
-H "Authorization: Bearer {{access_token}}"
fetch("{{baseUrl}}/accountTransferTransactions?svaCode=svaCode&startDate=2025-01-01&endDate=2025-03-16&page=1&size=100&accountId=cf7f07f2-1938-468a-9569-d811243494b1", {
method: "GET",
headers: {
"Authorization": "Bearer {{access_token}}"
}
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class TransactionHistory {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/accountTransferTransactions?svaCode=svaCode&startDate=2025-01-01&endDate=2025-03-16&page=1&size=100&accountId=cf7f07f2-1938-468a-9569-d811243494b1");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"totalItems": 9315,
"totalPages": 94,
"currentPage": 1,
"transactions": [
{
"amount": 300.00,
"requestId": "CEVIANT_DEVOPS-20250315163119-0500",
"accountTransferId": "e1c0343d-c365-4f28-b907-d468324544b1",
"transactionId": null,
"transactionDate": "2025-03-15T16:31:19Z",
"valueDate": null,
"status": "PENDING"
},
{
"amount": 300.00,
"requestId": "CEVIANT_DEVOPS-20250315163119-0499",
"accountTransferId": "a73b4e5c-e75c-4182-bc69-e76dc3b6e5f2",
"transactionId": null,
"transactionDate": "2025-03-15T16:31:19Z",
"valueDate": null,
"status": "PENDING"
}
]
}
This endpoint retrieves the transaction history for a specific account under a specified sva code.
HTTP Request
GET {{baseUrl}}/accountTransferTransactions?svaCode=svaCode&startDate=2025-01-01&endDate=2025-03-16&page=1&size=100&accountId=cf7f07f2-1938-468a-9569-d811243494b1
Query Parameters
| Parameter | Description |
|---|---|
| svaCode | The code of the stored value account |
| startDate | The start date for the transaction history (format: YYYY-MM-DD) |
| endDate | The end date for the transaction history (format: YYYY-MM-DD) |
| page | The page number for pagination |
| size | The number of transactions per page |
| accountId | The ID of the account to retrieve transactions for |
Loans
Create a Loan Disbursable Account
require 'net/http'
require 'uri'
require 'json'
uri = URI("{{baseUrl}}/wallet/{corporateId}/create-account")
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = "Bearer {{access_token}}"
req.body = {
firstname: "Tunde",
middlename: "moses",
lastname: "Test",
email: "danieltunde882929@gmail.com",
mobile: "09122030303",
bvn: "12345556671",
dob: "05 October 2006",
clientType: "individual"
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/wallet/{corporateId}/create-account"
headers = {"Content-Type": "application/json","Authorization":"Bearer access_token"}
data = {
"firstname": "Tunde",
"middlename": "moses",
"lastname": "Test",
"email": "danieltunde882929@gmail.com",
"mobile": "09122030303",
"bvn": "12345556671",
"dob": "05 October 2006",
"clientType": "individual"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
curl -X POST "{{baseUrl}}/wallet/{corporateId}/create-account" \
-H "Authorization: Bearer {{access_token}}" \
-d '{
"firstname":"Tunde",
"middlename":"moses",
"lastname":"Test",
"email":"danieltunde882929@gmail.com",
"mobile":"09122030303",
"bvn":"12345556671",
"dob":"05 October 2006",
"clientType":"individual"
}'
fetch("{{baseUrl}}/wallet/{corporateId}/create-account", {
method: "POST",
headers: {
"Authorization":"Bearer access_token",
"Content-Type": "application/json"
},
body: JSON.stringify({
firstname: "Tunde",
middlename: "moses",
lastname: "Test",
email: "danieltunde882929@gmail.com",
mobile: "09122030303",
bvn: "12345556671",
dob: "05 October 2006",
clientType: "individual"
})
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class CreateWallet {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/wallet/{corporateId}/create-account");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{" +
"\"firstname\":\"Tunde\","
+ "\"middlename\":\"moses\","
+ "\"lastname\":\"Test\","
+ "\"email\":\"danieltunde882929@gmail.com\","
+ "\"mobile\":\"09122030303\","
+ "\"bvn\":\"12345556671\","
+ "\"dob\":\"05 October 2006\","
+ "\"clientType\":\"individual\""
+ "}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"status": true,
"message": "Account created successfully",
"data": {
"clientId": 8,
"accountId": 5,
"accountNo": "000000005",
"externalReference": "MYP-12345556670"
}
}
The above command returns HTTP 404 JSON structured like this:
{
"status": false,
"message": "No customer created for this user [1002]"
}
This endpoint creates a wallet account. The account can be used to receive loan disbursements.
Http Request
POST {{baseUrl}}/wallet/{corporateId}/create-account
Path Parameter
| Parameter | Description |
|---|---|
| corporateId | A unique id assigned to merchant after successfully onboarded |
Create Loan and Disburse
require 'net/http'
require 'uri'
require 'json'
uri = URI("{{baseUrl}}/loan/{corporateId}/create-and-disburse")
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = "Bearer {{access_token}}"
req.body = {
transactionId: "Loan11",
duration: "6",
durationType: "2",
amount: "20000",
accountNo: "000002275"
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/wallet/{corporateId}/create-account"
headers = {"Content-Type": "application/json","Authorization":"Bearer access_token"}
data = {
"transactionId": "Loan11",
"duration": "6",
"durationType": "2",
"amount": "20000",
"accountNo": "000002275"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
curl -X POST "{{baseUrl}}/wallet/{corporateId}/create-account" \
-H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "Loan11",
"duration": "6",
"durationType": "2",
"amount": "20000",
"accountNo": "000002275"
}'
fetch("{{baseUrl}}/wallet/{corporateId}/create-account", {
method: "POST",
headers: {
"Authorization":"Bearer access_token",
"Content-Type": "application/json"
},
body: JSON.stringify({
transactionId: "Loan11",
duration: "6",
durationType: "2",
amount: "20000",
accountNo: "000002275"
})
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class CreateWallet {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/wallet/{corporateId}/create-account");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{" +
"\"transactionId\":\"Loan11\","
+ "\"duration\":\"6\","
+ "\"durationType\":\"2\","
+ "\"amount\":\"20000\","
+ "\"accountNo\":\"000002275\""
+ "}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"status": true,
"message": "Account created successfully",
"status": true,
"message": "Loan successfully created and disbursed",
"data": {
"loanId": 81,
"loanAccountNo": "000000081",
"linkedAccountNo": "000002275"
}
}
The above command returns HTTP 404 JSON structured like this:
{
"status": false,
"message": "No loan product mapper has been configured for api access. Kindly reach out to admin"
}
The above command returns HTTP 403 JSON structured like this:
{
"status": false,
"message": "Mismatch productId found"
}
The above command returns HTTP 400 JSON structured like this:
{
"status": false,
"message": "duration can only be within 1 and 11"
}
This endpoint creates a loan and disburses it. The loan amount will be credited to the specified account.
Http Request
POST {{baseUrl}}/loan/{corporateId}/create-and-disburse
Path Parameter
| Parameter | Description |
|---|---|
| corporateId | A unique id assigned to merchant after successfully onboarded |
Request Body
| Parameter | Description |
|---|---|
| transactionId | A unique identifier for the transaction |
| duration | The duration of the loan |
| durationType | The type of duration (e.g.,0 - daily, 1- weekly, 2 - Monthly) |
| amount | The amount of the loan |
| accountNo | The account number to which the loan amount will be credited |
Calculate Loan Schedule
require 'net/http'
require 'uri'
require 'json'
uri = URI("{{baseUrl}}/loan/{corporateId}/calculate-schedule")
req = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
req['Authorization'] = "Bearer {{access_token}}"
req.body = {
transactionId: "Loan11",
duration: "6",
durationType: "2",
amount: "20000",
accountNo: "000002275"
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/loan/{corporateId}/calculate-schedule"
headers = {"Content-Type": "application/json","Authorization":"Bearer access_token"}
data = {
"transactionId": "Loan11",
"duration": "6",
"durationType": "2",
"amount": "20000",
"accountNo": "000002275"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
curl -X POST "{{baseUrl}}/loan/{corporateId}/calculate-schedule" \
-H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "Loan11",
"duration": "6",
"durationType": "2",
"amount": "20000",
"accountNo": "000002275"
}'
fetch("{{baseUrl}}/loan/{corporateId}/calculate-schedule", {
method: "POST",
headers: {
"Authorization":"Bearer access_token",
"Content-Type": "application/json"
},
body: JSON.stringify({
transactionId: "Loan11",
duration: "6",
durationType: "2",
amount: "20000",
accountNo: "000002275"
})
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class CalculateLoanSchedule {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/loan/{corporateId}/calculate-schedule");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{" +
"\"transactionId\":\"Loan11\","
+ "\"duration\":\"6\","
+ "\"durationType\":\"2\","
+ "\"amount\":\"20000\","
+ "\"accountNo\":\"000002275\""
+ "}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"status": true,
"message": "Repayment schedule fetch successfully",
"data": {
"repaymentSchedule": {
"currency": {
"code": "NGN",
"name": "Nigerian Naira",
"decimalPlaces": 2,
"inMultiplesOf": 0,
"nameCode": "currency.NGN",
"displayLabel": "Nigerian Naira [NGN]"
},
"loanTermInDays": 184,
"totalPrincipalDisbursed": 20000.00,
"totalPrincipalExpected": 20000.00,
"totalPrincipalPaid": 0,
"totalInterestCharged": 9187.10,
"totalFeeChargesCharged": 0.00,
"totalPenaltyChargesCharged": 0.00,
"totalRepaymentExpected": 29187.10,
"totalOutstanding": 0,
"totalCredits": 0,
"periods": [
{
"dueDate": [
2025,
3,
5
],
"principalDisbursed": 20000.00,
"principalLoanBalanceOutstanding": 20000.00,
"feeChargesDue": 0,
"feeChargesOutstanding": 0,
"totalOriginalDueForPeriod": 0,
"totalDueForPeriod": 0,
"totalOutstandingForPeriod": 0,
"totalActualCostOfLoanForPeriod": 0,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
},
{
"period": 1,
"fromDate": [
2025,
3,
5
],
"dueDate": [
2025,
4,
5
],
"daysInPeriod": 31,
"principalOriginalDue": 3333.33,
"principalDue": 3333.33,
"principalOutstanding": 3333.33,
"principalLoanBalanceOutstanding": 16666.67,
"interestOriginalDue": 1531.18,
"interestDue": 1531.18,
"interestOutstanding": 1531.18,
"feeChargesDue": 0.00,
"penaltyChargesDue": 0.00,
"totalOriginalDueForPeriod": 4864.51,
"totalDueForPeriod": 4864.51,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 4864.51,
"totalActualCostOfLoanForPeriod": 1531.18,
"totalInstallmentAmountForPeriod": 4864.51,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
},
{
"period": 2,
"fromDate": [
2025,
4,
5
],
"dueDate": [
2025,
5,
5
],
"daysInPeriod": 30,
"principalOriginalDue": 3333.33,
"principalDue": 3333.33,
"principalOutstanding": 3333.33,
"principalLoanBalanceOutstanding": 13333.34,
"interestOriginalDue": 1531.18,
"interestDue": 1531.18,
"interestOutstanding": 1531.18,
"feeChargesDue": 0.00,
"penaltyChargesDue": 0.00,
"totalOriginalDueForPeriod": 4864.51,
"totalDueForPeriod": 4864.51,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 4864.51,
"totalActualCostOfLoanForPeriod": 1531.18,
"totalInstallmentAmountForPeriod": 4864.51,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
},
{
"period": 3,
"fromDate": [
2025,
5,
5
],
"dueDate": [
2025,
6,
5
],
"daysInPeriod": 31,
"principalOriginalDue": 3333.33,
"principalDue": 3333.33,
"principalOutstanding": 3333.33,
"principalLoanBalanceOutstanding": 10000.01,
"interestOriginalDue": 1531.18,
"interestDue": 1531.18,
"interestOutstanding": 1531.18,
"feeChargesDue": 0.00,
"penaltyChargesDue": 0.00,
"totalOriginalDueForPeriod": 4864.51,
"totalDueForPeriod": 4864.51,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 4864.51,
"totalActualCostOfLoanForPeriod": 1531.18,
"totalInstallmentAmountForPeriod": 4864.51,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
},
{
"period": 4,
"fromDate": [
2025,
6,
5
],
"dueDate": [
2025,
7,
5
],
"daysInPeriod": 30,
"principalOriginalDue": 3333.33,
"principalDue": 3333.33,
"principalOutstanding": 3333.33,
"principalLoanBalanceOutstanding": 6666.68,
"interestOriginalDue": 1531.18,
"interestDue": 1531.18,
"interestOutstanding": 1531.18,
"feeChargesDue": 0.00,
"penaltyChargesDue": 0.00,
"totalOriginalDueForPeriod": 4864.51,
"totalDueForPeriod": 4864.51,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 4864.51,
"totalActualCostOfLoanForPeriod": 1531.18,
"totalInstallmentAmountForPeriod": 4864.51,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
},
{
"period": 5,
"fromDate": [
2025,
7,
5
],
"dueDate": [
2025,
8,
5
],
"daysInPeriod": 31,
"principalOriginalDue": 3333.33,
"principalDue": 3333.33,
"principalOutstanding": 3333.33,
"principalLoanBalanceOutstanding": 3333.35,
"interestOriginalDue": 1531.18,
"interestDue": 1531.18,
"interestOutstanding": 1531.18,
"feeChargesDue": 0.00,
"penaltyChargesDue": 0.00,
"totalOriginalDueForPeriod": 4864.51,
"totalDueForPeriod": 4864.51,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 4864.51,
"totalActualCostOfLoanForPeriod": 1531.18,
"totalInstallmentAmountForPeriod": 4864.51,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
},
{
"period": 6,
"fromDate": [
2025,
8,
5
],
"dueDate": [
2025,
9,
5
],
"daysInPeriod": 31,
"principalOriginalDue": 3333.35,
"principalDue": 3333.35,
"principalOutstanding": 3333.35,
"principalLoanBalanceOutstanding": 0.00,
"interestOriginalDue": 1531.20,
"interestDue": 1531.20,
"interestOutstanding": 1531.20,
"feeChargesDue": 0.00,
"penaltyChargesDue": 0.00,
"totalOriginalDueForPeriod": 4864.55,
"totalDueForPeriod": 4864.55,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 4864.55,
"totalActualCostOfLoanForPeriod": 1531.20,
"totalInstallmentAmountForPeriod": 4864.55,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
}
]
}
}
}
The above command returns HTTP 404 JSON structured like this:
{
"status": false,
"message": "No loan product mapper has been configured for api access. Kindly reach out to admin"
}
The above command returns HTTP 403 JSON structured like this:
{
"status": false,
"message": "Mismatch productId found"
}
The above command returns HTTP 400 JSON structured like this:
{
"status": false,
"message": "duration can only be within 1 and 11"
}
This endpoint calculates the loan schedule based on the provided loan details.
Http Request
POST {{baseUrl}}/loan/{corporateId}/calculate-schedule
Path Parameter
| Parameter | Description |
|---|---|
| corporateId | A unique id assigned to merchant after successfully onboarded |
Request Body
| Parameter | Description |
|---|---|
| transactionId | A unique identifier for the transaction |
| duration | The duration of the loan |
| durationType | The type of duration (e.g.,0 - daily, 1- weekly, 2 - Monthly) |
| amount | The amount of the loan |
| accountNo | The account number to which the loan amount will be credited |
Get Loan Status
require 'net/http'
require 'uri'
uri = URI("{{baseUrl}}/loan/{transactionId}/status")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer {{access_token}}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/loan/{transactionId}/status"
headers = {"Authorization": "Bearer {{access_token}}"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "{{baseUrl}}/loan/{transactionId}/status" \
-H "Authorization: Bearer {{access_token}}"
fetch("{{baseUrl}}/loan/{transactionId}/status", {
method: "GET",
headers: {
"Authorization": "Bearer {{access_token}}"
}
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class GetLoanStatus {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/loan/{transactionId}/status");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns JSON structured like this:
{
"status": true,
"message": "Loan accounts information gotten",
"data": {
"corporateId": "1001",
"status": "DISBURSED",
"linkedAccountNo": "000000005",
"loanAccountNo": "000000002",
"loanId": 2,
"amount": 20000,
"reference": "Tun001-loan16"
}
}
This endpoint retrieves the status of a specific loan.
HTTP Request
GET {{baseUrl}}/loan/{transactionId}/status
Path Parameter
| Parameter | Description |
|---|---|
| transactionId | The ID of the transaction to retrieve the status for |
Get Loan Schedule
require 'net/http'
require 'uri'
uri = URI("{{baseUrl}}/loan/{loanTransactionId}/repayment-schedule")
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer {{access_token}}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
import requests
url = "{{baseUrl}}/loan/{loanTransactionId}/repayment-schedule"
headers = {"Authorization": "Bearer {{access_token}}"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "{{baseUrl}}/loan/{loanTransactionId}/repayment-schedule" \
-H "Authorization: Bearer {{access_token}}"
fetch("{{baseUrl}}/loan/{loanTransactionId}/repayment-schedule", {
method: "GET",
headers: {
"Authorization": "Bearer {{access_token}}"
}
})
.then(response => response.json())
.then(data => console.log(data));
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class GetLoanSchedule {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/loan/{loanTransactionId}/repayment-schedule");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Authorization", "Bearer " + access_token);
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns JSON structured like this:
{
"status": true,
"message": "Repayment schedule fetched successfully",
"data": {
"repaymentSchedule": {
"currency": {
"code": "NGN",
"name": "Nigerian Naira",
"decimalPlaces": 2,
"inMultiplesOf": 0,
"nameCode": "currency.NGN",
"displayLabel": "Nigerian Naira [NGN]"
},
"loanTermInDays": 184,
"totalPrincipalDisbursed": 20000.00,
"totalPrincipalExpected": 20000.00,
"totalPrincipalPaid": 0,
"totalInterestCharged": 9187.10,
"totalFeeChargesCharged": 0.00,
"totalPenaltyChargesCharged": 0.00,
"totalRepaymentExpected": 29187.10,
"totalOutstanding": 0,
"totalCredits": 0,
"periods": [
{
"dueDate": [
2025,
3,
5
],
"principalDisbursed": 20000.00,
"principalLoanBalanceOutstanding": 20000.00,
"feeChargesDue": 0,
"feeChargesOutstanding": 0,
"totalOriginalDueForPeriod": 0,
"totalDueForPeriod": 0,
"totalOutstandingForPeriod": 0,
"totalActualCostOfLoanForPeriod": 0,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
},
{
"period": 1,
"fromDate": [
2025,
3,
5
],
"dueDate": [
2025,
4,
5
],
"daysInPeriod": 31,
"principalOriginalDue": 3333.33,
"principalDue": 3333.33,
"principalOutstanding": 3333.33,
"principalLoanBalanceOutstanding": 16666.67,
"interestOriginalDue": 1531.18,
"interestDue": 1531.18,
"interestOutstanding": 1531.18,
"feeChargesDue": 0.00,
"penaltyChargesDue": 0.00,
"totalOriginalDueForPeriod": 4864.51,
"totalDueForPeriod": 4864.51,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 4864.51,
"totalActualCostOfLoanForPeriod": 1531.18,
"totalInstallmentAmountForPeriod": 4864.51,
"totalCredits": 0,
"totalAccruedInterest": 0,
"downPaymentPeriod": false
},
// ...more installments...
]
}
}
}
The above command returns HTTP 404 JSON structured like this:
{
"status": false,
"message": "No loan product mapper has been configured for api access. Kindly reach out to admin"
}
The above command returns HTTP 403 JSON structured like this:
{
"status": false,
"message": "Mismatch productId found"
}
The above command returns HTTP 400 JSON structured like this:
{
"status": false,
"message": "Invalid loanTransactionId"
}
This endpoint retrieves the repayment schedule of a specific loan.
HTTP Request
GET {{baseUrl}}/loan/{loanTransactionId}/repayment-schedule
Path Parameter
| Parameter | Description |
|---|---|
| loanTransactionId | The ID of the loan transaction to retrieve the repayment schedule for |
CeviantPay SDKDocumentation
Overview
The CeviantPay SDK provides a simple and seamless integration for accepting payments in your web application. This SDK allows you to quickly set up payment collection with minimal configuration.
Installation
Add the CeviantPay script to your HTML file:
PROD
<script src="https://webpayment.ceviant.co/sdk.js"></script>
DEV
<script src="https://webpayment.uat.ceviant.co/sdk.js"></script>
Configuration Options
| Parameter | Type | Required | Description |
|---|---|---|---|
publicKey |
string |
Yes | Your CeviantPay public API key (test or live) |
mode |
string |
Yes | Environment mode: 'DEV' for testing, 'PROD' for production |
amount |
number |
Yes | Amount to charge in the smallest currency unit (e.g., kobo for NGN) |
currency |
string |
Yes | Currency code (e. g., 'NGN') |
customerId |
`string | number` | Yes |
customerEmail |
string |
Yes | Customer's email address |
customerPhone |
number |
No | Customer's phone number |
onSuccess |
function |
Yes | Callback function triggered on successful payment |
onClose |
function |
No | Callback function triggered when payment modal is closed |
Basic Usage
window.ceviantPay({
publicKey: 'pk_test_your_public_key',
mode: 'DEV',
amount: 50000, // 500. 00 in NGN (amount in kobo)
currency: 'NGN',
customerId: '123456',
customerEmail: 'customer@example.com',
customerPhone: 2348012345678,
onSuccess: (response) => {
console.log('Payment successful:', response);
},
onClose: () => {
console.log('Payment modal closed');
},
});
interface CeviantPayConfig {
publicKey: string;
mode: 'DEV' | 'PROD';
amount: number;
currency: string;
customerId: string | number;
customerEmail: string;
customerPhone?: number;
onSuccess: (response: any) => void;
onClose?: () => void;
}
declare global {
interface Window {
ceviantPay: (config: CeviantPayConfig) => void;
}
}
window.ceviantPay({
publicKey: 'pk_test_your_public_key',
mode: 'DEV',
amount: 50000,
currency: 'NGN',
customerId: '123456',
customerEmail: 'customer@example.com',
customerPhone: 2348012345678,
onSuccess: (response) => {
console.log('Payment successful:', response);
},
onClose: () => {
console.log('Payment modal closed');
},
});
The basic usage examples is given in both typescript and javascript language. Kindly click the language tab to select
React Integration Example
import React, { useState } from 'react';
interface CartItem {
quantity: number;
unitPrice: number;
}
const CheckoutButton: React.FC = () => {
const [transactionRef, setTransactionRef] = useState<string | null>(null);
const [open, setOpen] = useState(false);
const cartItems: CartItem[] = [
{ quantity: 2, unitPrice: 1500 },
{ quantity: 1, unitPrice: 3000 },
];
const handlePayment = () => {
(window as any).ceviantPay({
publicKey: 'pk_test_your_public_key',
mode: 'DEV',
amount:
cartItems.reduce(
(acc, item) => acc + item.quantity * item.unitPrice,
0
) * 100, // Convert to smallest currency unit
currency: 'NGN',
customerId: '123456',
customerEmail: 'customer@example.com',
customerPhone: 2348012345678,
onSuccess: (response: any) => {
setTransactionRef(response);
setOpen(true);
},
onClose: () => {
console.log('Payment modal closed');
},
});
};
return <button onClick={handlePayment}>Pay Now</button>;
};
export default CheckoutButton;
You can use this to mimic a checkout form
Amount Calculation
Important: The
amountparameter should be in the smallest currency unit.
For Nigerian Naira (NGN), this means the amount should be in kobo:
// To charge ₦500.00
const amountInKobo = 500 * 100; // = 50000
// To calculate from cart items
const totalAmount =
cartItems.reduce((acc, item) => acc + item.quantity * item.unitPrice, 0) *
100;
Callback Responses
onSuccess
The onSuccess callback receives a response object containing transaction details:
onSuccess: (response) => {
console.log(response);
// {
// reference: 'TXN_123456789',
// status: 'success',
// amount: 50000,
// currency: 'NGN',
// ...
// }
};
onClose
The onClose callback is triggered when the user closes the payment modal without completing the transaction:
onClose: () => {
// Handle modal close
// e.g., show a message or redirect
};
Environment Modes
| Mode | Description | Key Prefix |
|---|---|---|
DEV |
Test environment for development and testing | pk_test_ |
PROD |
Live environment for production transactions | pk_live_ |
Supported Currencies
| Currency Code | Currency Name |
|---|---|
NGN |
Nigerian Naira |
Error Handling
Wrap your payment initialization in a try-catch block for proper error handling:
try {
window.ceviantPay({
publicKey: 'pk_test_your_public_key',
mode: 'DEV',
amount: 50000,
currency: 'NGN',
customerId: '123456',
customerEmail: 'customer@example.com',
onSuccess: (response) => {
console.log('Payment successful:', response);
},
onClose: () => {
console.log('Payment cancelled');
},
});
} catch (error) {
console.error('Payment initialization failed:', error);
}
Security Best Practices
- Never expose your secret key - Only use public keys (
pk_) in client-side code - Validate transactions server-side - Always verify transaction status on your backend
- Use HTTPS - Ensure your website uses SSL/TLS encryption
- Validate amounts - Verify the amount on your server before confirming orders
Support
For support and inquiries, contact the CeviantPay team:
- Email: support@ceviantpay.com
Embedded Lending SDK
Overview
Embedded Lending lets your customers buy now and pay in instalments without leaving your checkout.
The customer pays part of the price upfront. This is the equity contribution. Ceviant Finance lends the rest and pays you the full purchase price. The customer then repays Ceviant Finance, not you.
Your integration has four parts:
- Your server starts a lending session for the order, using your lending keys.
- Your page opens the Lending SDK with the session token it gets back.
- Your server receives webhooks.
- Your server releases the product once the purchase is funded.
You do not build any loan screens, and you do not collect the equity payment yourself. The SDK runs the whole application: customer details, identity checks, bank statement, credit decision, offer and equity payment.
Before You Start
| Parameter | Where | Description |
|---|---|---|
| Lending keys | Corporate Portal → Finance → Lending → Generate keys | A public key (cfn_pk_test_… on test, cfn_pk_live_… in production) and a secret key (cfn_sk_test_… / cfn_sk_live_…). The secret key is shown once; keep it on your server. Rotating the keys disables the old secret immediately. |
| Webhook URL | Same page | An https:// URL your server receives webhooks on. The first time you save it you are shown a signing secret (whsec_…) once; keep it so you can verify webhooks. |
| Lending programme | Set up by Ceviant Finance | Loan limits, tenors, rate, equity percentage, the customer data collected, the screens shown, and the settlement account you are paid into. You can only start sessions once your programme is active. |
Test keys only work on the test environment, and live keys only work in production.
Environments
| Setting | Test (UAT) | Production |
|---|---|---|
{{baseUrl}} |
https://collections.uat.ceviant.cloud/paymentgateway |
https://collections.ceviant.cloud/paymentgateway |
| SDK script | https://lending.uat.ceviant.cloud/sdk.js |
https://lending.ceviant.cloud/sdk.js |
SDK mode |
'TEST' |
'PROD' |
| Keys | cfn_pk_test_…, cfn_sk_test_… |
cfn_pk_live_…, cfn_sk_live_… |
All amounts are integers in the minor unit of the currency. For NGN that is kobo, so ₦1,000,000 is sent as 100000000.
Start a Lending Session
curl -X POST "{{baseUrl}}/onlending/lending/sessions" \
-H "Authorization: Basic cfn_pk_test_your_public_key" \
-H "X-Secret-Key: cfn_sk_test_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"merchantReference":"ATTEMPT-0001",
"orderReference":"ORDER-1029",
"productDescription":"5kVA solar inverter kit",
"purchaseAmount":100000000,
"currency":"NGN",
"merchantCustomerReference":"CUST-778",
"customer":{
"firstName":"Ada",
"lastName":"Obi",
"email":"ada.obi@example.com",
"phoneNumber":"08012345678"
}
}'
// Server side only: the secret key must never reach the browser.
app.post('/checkout/:orderId/instalments', async (req, res) => {
const order = await orders.get(req.params.orderId);
const response = await fetch(`${process.env.CEVIANT_API}/onlending/lending/sessions`, {
method: 'POST',
headers: {
Authorization: `Basic ${process.env.CEVIANT_LENDING_PUBLIC_KEY}`,
'X-Secret-Key': process.env.CEVIANT_LENDING_SECRET_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
merchantReference: `${order.id}-${order.attempt}`,
orderReference: order.id,
productDescription: order.title,
purchaseAmount: order.totalKobo,
currency: 'NGN',
merchantCustomerReference: order.customerId,
customer: {
firstName: order.firstName,
lastName: order.lastName,
email: order.email,
phoneNumber: order.phone,
},
}),
});
if (!response.ok) return res.status(502).json({ error: 'Could not start instalments' });
const session = await response.json();
await orders.update(order.id, { lendingApplicationReference: session.applicationReference });
// Only the token goes to the page.
res.json({ sessionToken: session.sessionToken });
});
import os
import requests
url = "{{baseUrl}}/onlending/lending/sessions"
headers = {
"Authorization": "Basic " + os.environ["CEVIANT_LENDING_PUBLIC_KEY"],
"X-Secret-Key": os.environ["CEVIANT_LENDING_SECRET_KEY"],
"Content-Type": "application/json",
}
data = {
"merchantReference": "ATTEMPT-0001",
"orderReference": "ORDER-1029",
"productDescription": "5kVA solar inverter kit",
"purchaseAmount": 100000000,
"currency": "NGN",
"merchantCustomerReference": "CUST-778",
"customer": {
"firstName": "Ada",
"lastName": "Obi",
"email": "ada.obi@example.com",
"phoneNumber": "08012345678",
},
}
response = requests.post(url, json=data, headers=headers)
session = response.json()
print(session["applicationReference"], session["sessionToken"])
import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class StartLendingSession {
public static void main(String[] args) throws Exception {
URL url = new URL("{{baseUrl}}/onlending/lending/sessions");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Basic " + System.getenv("CEVIANT_LENDING_PUBLIC_KEY"));
conn.setRequestProperty("X-Secret-Key", System.getenv("CEVIANT_LENDING_SECRET_KEY"));
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String requestBody = "{"
+ "\"merchantReference\":\"ATTEMPT-0001\","
+ "\"orderReference\":\"ORDER-1029\","
+ "\"productDescription\":\"5kVA solar inverter kit\","
+ "\"purchaseAmount\":100000000,"
+ "\"currency\":\"NGN\","
+ "\"merchantCustomerReference\":\"CUST-778\""
+ "}";
try (OutputStream os = conn.getOutputStream()) {
byte[] input = requestBody.getBytes("utf-8");
os.write(input, 0, input.length);
}
BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
}
}
The above command returns HTTP 200 JSON structured like this:
{
"applicationReference": "LND261022K7QM2XRA",
"status": "INFORMATION_REQUIRED",
"sessionToken": "ls_…",
"sessionExpiresAt": "2026-10-22T13:30:00",
"existing": false,
"assessmentReused": false
}
The above command returns HTTP 400 JSON structured like this:
{
"status": false,
"message": "No active lending programme for this corporate"
}
The above command returns HTTP 409 JSON structured like this:
{
"status": false,
"message": "merchantReference already used for a different order"
}
Call this endpoint when the customer chooses Pay in Instalments. It creates the lending application and returns the session token your page opens the SDK with.
Http Request
POST {{baseUrl}}/onlending/lending/sessions
Headers
| Parameter | Description |
|---|---|
| Authorization | Basic followed by your lending public key |
| X-Secret-Key | Your lending secret key |
Request Body
| Parameter | Required | Description |
|---|---|---|
| merchantReference | Yes | Your unique reference for this checkout attempt. Sending the same value again returns the same application with a new token, never a duplicate. |
| purchaseAmount | Yes | The full price, in kobo. |
| orderReference | Recommended | Your order reference. Webhooks and the loan API return it to you. |
| currency | No | Defaults to your programme's currency. |
| productDescription | No | Shown to the customer. |
| merchantCustomerReference | No | Your own customer id. |
| customer | No | Details you already hold, which prefill the form: firstName, lastName, email, phoneNumber, dateOfBirth (YYYY-MM-DD), bvn, nin and address. The customer confirms or corrects them in the SDK. |
| programmeCode | Only with several programmes | Which of your programmes to use. |
| previousApplicationReference | No | See Choosing a cheaper product. |
Response
| Parameter | Description |
|---|---|
| applicationReference | Ceviant's reference for the application. Store it against your order. |
| status | The application status it starts in. |
| sessionToken | Pass this, and only this, to your page. Valid for 30 minutes and limited to this one application. |
| sessionExpiresAt | When the token expires. Call the endpoint again with the same merchantReference for a new one. |
| existing | true if this merchantReference resumed an application that already existed. |
| assessmentReused | true if the customer's earlier identity checks and statement analysis were reused. |
Errors
| Code | Meaning |
|---|---|
| 400 | Invalid request, or you have no active lending programme |
| 401 | Wrong lending keys, or test keys used in production (or the other way round) |
| 409 | This merchantReference was already used for a different order, or its application is closed |
Open the SDK
<script src="https://lending.uat.ceviant.cloud/sdk.js"></script>
const { sessionToken } = await fetch(`/checkout/${orderId}/instalments`, {
method: 'POST',
}).then((r) => r.json());
window.onLendingInit({
sessionToken,
mode: 'TEST', // 'PROD' in production
onSuccess: (result) => {
// The customer has paid the equity.
// Show "payment received, we'll confirm your order shortly".
// Do NOT release the product yet: wait for the application.funded webhook.
console.log(result.applicationReference, result.status);
},
onIneligible: (result) => {
// result.reasonCode; for PURCHASE_ABOVE_ELIGIBLE_AMOUNT
// also result.maxPurchaseAmount (kobo).
console.log(result.reasonCode, result.maxPurchaseAmount);
},
onClose: (result) => {
// The customer closed the SDK. result.status shows how far they got.
console.log(result.status);
},
});
interface LendingResult {
applicationReference?: string;
status?: string;
reasonCode?: string;
maxPurchaseAmount?: number;
maxFinancedAmount?: number;
}
interface LendingConfig {
sessionToken: string;
mode: 'TEST' | 'PROD';
onSuccess?: (result: LendingResult) => void;
onIneligible?: (result: LendingResult) => void;
onClose?: (result: LendingResult) => void;
}
declare global {
interface Window {
onLendingInit: (config: LendingConfig) => void;
}
}
window.onLendingInit({
sessionToken,
mode: 'TEST',
onSuccess: (result) => console.log('funding started', result.applicationReference),
onIneligible: (result) => console.log('not eligible', result.reasonCode),
onClose: (result) => console.log('closed at', result.status),
});
import React, { useState } from 'react';
const PayInInstalments: React.FC<{ orderId: string }> = ({ orderId }) => {
const [busy, setBusy] = useState(false);
const openSdk = async () => {
setBusy(true);
try {
// Your server starts the session; the browser only ever sees the token.
const { sessionToken } = await fetch(`/checkout/${orderId}/instalments`, {
method: 'POST',
}).then((r) => r.json());
(window as any).onLendingInit({
sessionToken,
mode: 'TEST',
onSuccess: () => setBusy(false),
onIneligible: (result: any) => {
setBusy(false);
if (result.reasonCode === 'PURCHASE_ABOVE_ELIGIBLE_AMOUNT') {
// Send them to products at or below result.maxPurchaseAmount.
}
},
onClose: () => setBusy(false),
});
} catch (error) {
setBusy(false);
console.error('Could not start instalments', error);
}
};
return (
<button onClick={openSdk} disabled={busy}>
Pay in Instalments
</button>
);
};
export default PayInInstalments;
Include the script once on your checkout page, then open the SDK with the token from the previous step. The SDK runs full screen in an iframe on top of your page, and removes itself when the customer closes it.
Configuration Options
| Parameter | Type | Required | Description |
|---|---|---|---|
| sessionToken | string |
Yes | The session token your server obtained. |
| mode | string |
Yes | 'TEST' or 'PROD'. It must match your keys. |
| onSuccess | function |
No | The equity is paid and funding has started. The SDK stays on its confirmation screen until the customer closes it. |
| onIneligible | function |
No | The customer is not eligible, or the purchase is larger than they can finance. |
| onClose | function |
No | The customer closed the SDK. |
Every callback receives an object with applicationReference and status. onIneligible also carries reasonCode, and maxPurchaseAmount / maxFinancedAmount where they apply.
What the customer sees
The SDK shows the screens your programme defines, typically in this order:
- Your information: name, date of birth, email, phone, and BVN or NIN.
- Identity verification.
- Bank statement: the customer picks their bank and uploads a PDF of up to 10 MB.
- Eligibility decision.
- Loan offer: the customer chooses a tenor and sees the instalment, interest, total and first repayment date, then accepts or declines.
- Equity payment: paid to Ceviant Finance through Ceviant's payment checkout.
- Confirmation: the customer's repayment account details.
Webhooks
{
"event": "application.funded",
"id": "LND261022K7QM2XRA:application.funded",
"applicationReference": "LND261022K7QM2XRA",
"merchantReference": "ATTEMPT-0001",
"orderReference": "ORDER-1029",
"currency": "NGN",
"purchaseAmount": 100000000,
"loanAmount": 60000000,
"equityAmount": 40000000,
"amountPaid": 100000000,
"paidAt": "2026-10-22T12:01:15",
"loanMaturityDate": "2027-10-22",
"repaymentAccount": {
"accountNumber": "9012345678",
"accountName": "CFN/Ada Obi",
"bankName": "VFD Microfinance Bank"
},
"occurredAt": "2026-10-22T12:01:16Z"
}
Ceviant sends a JSON POST to your webhook URL. Respond with 2xx. Failed deliveries are retried.
| Event | When | Also carries |
|---|---|---|
| application.status_changed | Every status change | status, previousStatus |
| application.funded | You have been paid the purchase price. Release the product. | purchaseAmount, loanAmount, equityAmount, amountPaid, paidAt, loanMaturityDate, repaymentAccount |
| repayment.received | A customer repayment was applied | reference, amount, receivedAt, outstandingAmount |
| loan.repaid | The loan is fully repaid | none |
Every webhook also includes id, event, applicationReference, merchantReference, orderReference, customerReference, currency and occurredAt.
The id is unique to what happened. If you receive an id you have already processed, return 200 and ignore it.
Verifying the Signature
const crypto = require('crypto');
const express = require('express');
app.post(
'/webhooks/ceviant-lending',
express.raw({ type: 'application/json' }),
async (req, res) => {
const signature = req.get('x-ceviant-webhook-signature') || '';
const expected = crypto
.createHmac('sha512', process.env.CEVIANT_WEBHOOK_SECRET)
.update(req.body)
.digest('base64');
const valid =
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body.toString('utf8'));
if (await webhooks.alreadyProcessed(event.id)) return res.sendStatus(200);
if (event.event === 'application.funded') {
await orders.markPaidAndRelease(event.orderReference, event.applicationReference);
}
await webhooks.markProcessed(event.id);
res.sendStatus(200);
},
);
import base64
import hashlib
import hmac
import os
from flask import Flask, request
app = Flask(__name__)
@app.post("/webhooks/ceviant-lending")
def ceviant_lending():
raw = request.get_data() # the raw body, before any JSON parsing
expected = base64.b64encode(
hmac.new(
os.environ["CEVIANT_WEBHOOK_SECRET"].encode(), raw, hashlib.sha512
).digest()
).decode()
signature = request.headers.get("x-ceviant-webhook-signature", "")
if not hmac.compare_digest(expected, signature):
return "", 401
event = request.get_json()
if already_processed(event["id"]):
return "", 200
if event["event"] == "application.funded":
release_product(event["orderReference"], event["applicationReference"])
mark_processed(event["id"])
return "", 200
Each webhook carries an x-ceviant-webhook-signature header. Its value is the HMAC-SHA512 of the raw request body, keyed with your signing secret (whsec_…) and base64-encoded.
Release the Product
Release the product when you receive application.funded, which means the status is FUNDED. Do not release on any of these:
- the SDK's
onSuccess; - status
EQUITY_PAYMENT_SUCCESSFUL; - the customer reaching your "thank you" page.
Funding usually follows the equity payment within seconds. In that time the loan is created and Ceviant Finance pays the full price into your settlement account.
If you missed a webhook, check the loan with the Loan API. Keep the order open until it is funded. How long an offer stays valid is set in your programme.
Choosing a Cheaper Product
Sometimes a customer qualifies for a loan, but not a big enough one for this purchase. The SDK then calls onIneligible with reasonCode: "PURCHASE_ABOVE_ELIGIBLE_AMOUNT" and maxPurchaseAmount, the highest price they can buy, in kobo.
To handle it:
- Send the customer back to your catalogue, filtered to products at or below
maxPurchaseAmount. - When they pick a new product, start a new session with a new
merchantReference, and setpreviousApplicationReferenceto the earlier application's reference. - Their identity checks and bank statement are reused, as long as the statement was analysed within 30 days. They get a decision straight away, without re-uploading anything, and the session response has
assessmentReused: true.
Lending Loan API
curl "{{baseUrl}}/onlending/lending/loans?status=ACTIVE&page=0&size=20" \
-H "Authorization: Basic cfn_pk_test_your_public_key" \
-H "X-Secret-Key: cfn_sk_test_your_secret_key"
const loans = await fetch(
`${process.env.CEVIANT_API}/onlending/lending/loans?status=ACTIVE&page=0&size=20`,
{
headers: {
Authorization: `Basic ${process.env.CEVIANT_LENDING_PUBLIC_KEY}`,
'X-Secret-Key': process.env.CEVIANT_LENDING_SECRET_KEY,
},
},
).then((r) => r.json());
import os
import requests
headers = {
"Authorization": "Basic " + os.environ["CEVIANT_LENDING_PUBLIC_KEY"],
"X-Secret-Key": os.environ["CEVIANT_LENDING_SECRET_KEY"],
}
loans = requests.get(
"{{baseUrl}}/onlending/lending/loans",
params={"status": "ACTIVE", "page": 0, "size": 20},
headers=headers,
).json()
Uses the same lending keys and headers as the session endpoint.
Http Request
GET {{baseUrl}}/onlending/lending/loans
GET {{baseUrl}}/onlending/lending/loans/{reference}
Query Parameters
| Parameter | Description |
|---|---|
| status | Filter by loan status |
| from, to | ISO date-time range |
| page, size | Page number and page size, at most 100 per page |
The list returns your loans, newest first. A single loan can be fetched by application, order, merchant or loan reference, and comes back with its balances, repayment schedule and payment history. The same loans appear in the Corporate Portal under Lending → Loans.
Loan statuses: PENDING_ACTIVATION, ACTIVE, PAST_DUE, FULLY_REPAID, CLOSED, CANCELLED. These are separate from the application statuses below.
Application Statuses
| Status | Meaning |
|---|---|
| INFORMATION_REQUIRED | Waiting for the customer's details |
| INITIATED | Details captured |
| VERIFICATION_PENDING, VERIFICATION_FAILED | Identity checks (BVN / NIN) |
| STATEMENT_ANALYSIS_PENDING, STATEMENT_ANALYSIS_FAILED | Bank statement analysis |
| ASSESSMENT_PENDING | Credit decision in progress |
| ELIGIBLE, INELIGIBLE | Credit decision |
| OFFER_PRESENTED, OFFER_ACCEPTED, OFFER_REJECTED | Loan offer |
| EQUITY_PAYMENT_PENDING, EQUITY_PAYMENT_FAILED, EQUITY_PAYMENT_SUCCESSFUL | Equity contribution |
| PROCESSING | Loan being set up and your payout being sent |
| FUNDED | You have been paid. Release the product. |
| COMPLETED | Loan fully repaid |
| CANCELLED, FAILED | Closed without funding |
What the Customer is Told
Ceviant Finance emails and texts the customer for each of these, so you do not need to:
- equity payment received;
- repayment account opened;
- loan active;
- each repayment;
- overdue reminders;
- loan fully repaid.
Testing
- Generate test keys in the Corporate Portal on UAT, and set your webhook URL.
- Ask Ceviant Finance to activate a test programme for your corporate account.
- Start a session from your server, and open the SDK with
mode: 'TEST'. - Use the test BVN and sample bank statement PDF that Ceviant provides. Ceviant's payment checkout runs in test mode, so no real money moves.
- Confirm that you receive
application.status_changedand thenapplication.funded, and that your signature check passes.
To expose a local webhook endpoint during development, use a tunnelling tool such as ngrok and set the tunnel's https URL as your webhook URL.
Go-live Checklist
- Live keys generated in the production Corporate Portal and stored in your server's secret store.
- Production webhook URL set and its signing secret stored.
- Production
{{baseUrl}}and SDK script in place, withmode: 'PROD'. - Product released only on
application.funded, or after confirming with the Loan API. - Repeated webhook
ids ignored, and signatures verified. PURCHASE_ABOVE_ELIGIBLE_AMOUNTand closed-without-funding cases handled in your checkout.
Security Best Practices
- Keep the secret key and the webhook signing secret on your server only. Never put them in a browser, a mobile app, logs or source control. If either is exposed, rotate it in the Corporate Portal.
- The session token is the only value that reaches the browser. It expires after 30 minutes and covers one application.
- Verify every webhook signature before acting on it.
- Confirm funding from the webhook or the Loan API before releasing a product.
- Serve your checkout over HTTPS.
Embedded Lending Support
For support and enquiries, contact the Embedded Lending team:
onlending.support@ceviant.co
Webhook Notification
Our system provides real-time webhook notifications to inform subscribed endpoints about significant account transactions. Webhooks are triggered automatically whenever there is a relevant event, ensuring that your systems are updated immediately with transaction details. Notifications cover both outward transfers and account inflows.
Request Headers
WEBHOOK_SECRET="your-webhook-secret"
PAYLOAD='{"transactionId":"123","amount":1000}'
# Compute HMAC SHA512 and Base64 encode
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha512 -hmac "$WEBHOOK_SECRET" -binary | base64)
echo "X_CEVIANT_WEBHOOK_SIGNATURE: $SIGNATURE"
@Override
public String getHMac512Hash(String key, String hashString) {
try {
LOGGER.info("Hash String: {}", hashString);
LOGGER.info("Hash key: {}", key);
String HMAC_SHA512 = "HmacSHA512";
byte[] byteKey = key.getBytes("UTF-8");
SecretKeySpec keySpec = new SecretKeySpec(byteKey, HMAC_SHA512);
Mac sha512_HMAC = Mac.getInstance(HMAC_SHA512);
sha512_HMAC.init(keySpec);
byte[] mac_data = sha512_HMAC.doFinal(hashString.getBytes("UTF-8"));
return new String(Base64.encodeBase64(mac_data));
} catch (NoSuchAlgorithmException | UnsupportedEncodingException |
InvalidKeyException ex) {
throw new SystemException(ex.getMessage(), ex);
}
}
require 'openssl'
require 'base64'
webhook_secret = "your-webhook-secret"
payload = '{"transactionId":"123","amount":1000}'
digest = OpenSSL::Digest.new('sha512')
hmac = OpenSSL::HMAC.digest(digest, webhook_secret, payload)
signature = Base64.strict_encode64(hmac)
puts "X_CEVIANT_WEBHOOK_SIGNATURE: #{signature}"
import hmac
import hashlib
import base64
webhook_secret = b'your-webhook-secret'
payload = b'{"transactionId":"123","amount":1000}'
hmac_digest = hmac.new(webhook_secret, payload, hashlib.sha512).digest()
signature = base64.b64encode(hmac_digest).decode()
print("X_CEVIANT_WEBHOOK_SIGNATURE:", signature)
const crypto = require('crypto');
const webhookSecret = 'your-webhook-secret';
const payload = '{"transactionId":"123","amount":1000}';
const hmac = crypto.createHmac('sha512', webhookSecret);
hmac.update(payload);
const signature = hmac.digest('base64');
console.log("X_CEVIANT_WEBHOOK_SIGNATURE:", signature);
Each webhook request contains the following headers. The most important header is X_CEVIANT_WEBHOOK_SIGNATURE, which is used to validate the authenticity of the request while other headers can be ignored
| Header Name | Description |
|---|---|
X_REQUEST_ID |
Unique ID for the request |
X_REQUEST_START |
Timestamp indicating when the request was initiated |
X_CEVIANT_CURRENT_ACTOR_ID |
Identifier of the actor performing the action |
X_CEVIANT_WEBHOOK_SIGNATURE |
HMAC SHA512 signature of the request body (see below for validation) |
X_CEVIANT_CURRENT_ACTOR_TYPE |
Type of the actor performing the action |
X_CEVIANT_REQUEST_CORRELATION_ID |
Correlation ID for tracing the request |
X_CEVIANT_SESSION_CORRELATION_ID |
Session correlation ID for tracing |
Validating X_CEVIANT_WEBHOOK_SIGNATURE
The signature is computed using HMAC SHA512 with the webhook secret provided by the client.
- Key: Webhook secret (random 16-character value provided by the client)
- Message: Raw request body of the webhook
- Encoding: Resulting hash is encoded in BASE64
Code Example: The code example is given in shell, ruby, python, javascript and java. Kindly click on each of the language tab
Outward Transfer
This webhook is triggered for outward transfers (funds moving out of an account to a beneficiary account). Notifications are sent when the transaction reaches a final state, either APPROVED or DECLINED.
Purpose:
To inform the receiving system about the status of the outward transfer, enabling automated updates or actions based on approval or failure.
Payload Example:
{
"statusReason": "SUCCESSFUL",
"requestId": "NEXUS_SVA-20250701163300-2003",
"sessionId": "999999250701130831392518058800",
"responseMessage": "Approved",
"recipientAccount": "9876543210",
"accountTransferId": "9a51c728-e531-456c-a81f-228d0ca9f07c",
"transactionId": "NIPMINI/000218250701140831805897667214/000218250701140831805897667214",
"status": "APPROVED"
}
Inflow into Account
This webhook is triggered when funds are received into an account. It provides details of the inflow transaction to enable real-time tracking, reconciliation, and automated processing.
Purpose:
To notify the receiving system immediately when funds are received into an account. This ensures downstream processing and reconciliation.
Payload Example:
{
"externalReference": "381113d-c573-4004-80f8-b8a52158c377",
"amount": 1320.00,
"originatorName": "Sender",
"originatorBankName": "Wema Bank",
"description": "Testing transaction Deposit into my new Virtual Account",
"sessionId": "091010210202020202020202",
"accountNumber": "6410000015",
"transactionId": "0d2ad44b-e3fb-4123-bbb9-4341de6df20c",
"originatorAccountNo": "00082123092"
}
Errors
The Ceviant API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The requested resource is forbidden |
| 404 | Not Found -- The specified object could not be found. |
| 405 | Method Not Allowed -- You tried to access an api with an invalid method. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |