โก Interactive API Sandbox & Live Console
Test live & sandbox API endpoints in real-time, inspect request payloads, and debug responses directly in your browser.
Response Inspector
// Click "๐ Send Request" above to execute API call and inspect the live response...
Generated Code Snippets (Synced)
Recent Session Calls
Introduction
Welcome to FIM DIGITAL VENTURES LIMITED
FIM DIGITAL VENTURES LIMITED is a modern, secure payment platform that empowers Nigerian businesses with seamless payment solutions. Integrate in minutes and start accepting payments today.
Base URL
All API requests should be made to:
For sandbox testing use:
Supported Features
- Accept card payments, bank transfers, and mobile checkout links
- Issue dedicated virtual bank accounts to customers (Static & Dynamic)
- Initiate bank transfers to any Nigerian account in real-time
- Real-time payment notifications via webhooks
- Automated real-time transaction reconciliation and balance tracking
- HMAC SHA-256 webhook signature verification
Need Help?
If you have questions, encounter issues, or need help with your integration, our support team is available:
Authentication
Authenticate your API requests by including your Secret Key (retrieved from Settings โ API Credentials) in the Authorization header of every request as a Bearer token.
The same Secret Key is used to authenticate requests in both Sandbox (/api/test) and Live (/api/v1) environments.
Key Types Reference
| Key Type | Prefix Format | Where it is Used | Purpose / Description |
|---|---|---|---|
| Secret Key | sk_live_...sk_test_... |
Request Header | Required for all server-side API requests. Sent in the Authorization: Bearer header. Must be kept confidential. |
| Public Key | pk_live_...pk_test_... |
Client-side SDK | Used in client-side widgets/checkouts to load payment forms. Safe to expose publicly. |
| Webhook Signing Key | whsec_live_...whsec_test_... |
Local Verification | Used to verify HMAC signatures of webhooks sent to your server. Never send this key in API request headers. |
Authorization: Bearer sk_live_your_secret_key_here
Content-Type: application/json
Your Secret Key grants full access to your account. Never expose it in client-side code, frontend repositories, or unsecured logs.
Quick Start Guide
Get up and running in just three steps
Sign up on the Dashboard and complete your business verification. Once approved, navigate to Settings โ API Credentials to retrieve your keys.
Include your Secret Key in the Authorization header of every API request.
Use the Initialize Payment endpoint to create a payment session and redirect your customer to the hosted checkout page.
Initialize Payment
Create a payment session. FIM DIGITAL VENTURES LIMITED returns a hosted checkout URL that you redirect your customer to. Once the payment is completed, the customer is automatically redirected back to your callback_url (or redirect_link) with ?reference=...&status=success appended.
Pass the amount in naira. For example, pass 100 to charge โฆ100.
You can pass "fee_bearer": "customer" or "fee_bearer": "merchant" in your API request.
โข "customer" (or "client"): The payment gateway fee is automatically added to the checkout amount so your customer pays amount + fee (e.g., โฆ5,000 + โฆ45 = โฆ5,045), and your merchant wallet is credited 100% of the base order amount (โฆ5,000).
โข "merchant": The customer pays the exact order amount (โฆ5,000), and the processing fee is deducted from your settlement.
โข What if omitted? If your website does not specify fee_bearer in the API payload, FimPaypoint automatically applies your preference configured in Dashboard → Settings → Checkout Experience. If unset, it safely defaults to "merchant".
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
first_name |
string | Required | Customer's first name. |
last_name |
string | Required | Customer's last name. |
email |
string | Required | Customer's email address for receipt delivery. |
phone |
string | Required | Customer's phone number. |
amount |
float | number | Required | Amount to charge the customer in Naira (NGN). Must be greater than โฆ50. |
fee_bearer |
string | Optional | Who pays the transaction fee: "customer" or "merchant". If omitted, falls back to your Dashboard Checkout Experience setting, or defaults to "merchant". |
callback_url |
string | Optional | URL to redirect the customer after payment is completed. Accepts interchangeable aliases: redirect_url, redirect_link, return_url. |
reference |
string | Optional | Unique custom transaction reference from your website/system for tracking. Accepts aliases: merchant_reference, tx_ref. |
metadata |
object | array | Optional | Key-value map or object with custom data (e.g. {"user_id": 123, "order_id": 45}). Echoed back in verification responses and webhooks. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/checkout/initialize" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Abiola",
"last_name": "Bayo",
"email": "[email protected]",
"phone": "08099887766",
"amount": 5000,
"fee_bearer": "customer",
"reference": "ORD_1795076650",
"callback_url": "https://fimpaypoint.com/payment/callback",
"metadata": {
"user_id": 123,
"custom_charge": 110
}
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/checkout/initialize',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"first_name": "Abiola",
"last_name": "Bayo",
"email": "[email protected]",
"phone": "08099887766",
"amount": 5000,
"fee_bearer": "customer",
"reference": "ORD_1795076650",
"callback_url": "https://fimpaypoint.com/payment/callback",
"metadata": {
"user_id": 123,
"custom_charge": 110
}
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/checkout/initialize"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"first_name": "Abiola",
"last_name": "Bayo",
"email": "[email protected]",
"phone": "08099887766",
"amount": 5000,
"fee_bearer": "customer",
"reference": "ORD_1795076650",
"callback_url": "https:\/\/fimpaypoint.com\/payment\/callback",
"metadata": {
"user_id": 123,
"custom_charge": 110
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'first_name' => 'Abiola',
'last_name' => 'Bayo',
'email' => '[email protected]',
'phone' => '08099887766',
'amount' => 5000.0,
'fee_bearer' => 'customer',
'reference' => 'ORD_1795076650',
'callback_url' => 'https://fimpaypoint.com/payment/callback',
'metadata' =>
array (
'user_id' => 123,
'custom_charge' => 110,
),
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/checkout/initialize",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"first_name\":\"Abiola\",\"last_name\":\"Bayo\",\"email\":\"[email protected]\",\"phone\":\"08099887766\",\"amount\":5000,\"fee_bearer\":\"customer\",\"reference\":\"ORD_1795076650\",\"callback_url\":\"https://fimpaypoint.com/payment/callback\",\"metadata\":{\"user_id\":123,\"custom_charge\":110}}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/checkout/initialize", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/checkout/initialize")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"first_name": "Abiola",
"last_name": "Bayo",
"email": "[email protected]",
"phone": "08099887766",
"amount": 5000,
"fee_bearer": "customer",
"reference": "ORD_1795076650",
"callback_url": "https:\/\/fimpaypoint.com\/payment\/callback",
"metadata": {
"user_id": 123,
"custom_charge": 110
}
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"first_name":"Abiola","last_name":"Bayo","email":"[email protected]","phone":"08099887766","amount":5000,"fee_bearer":"customer","reference":"ORD_1795076650","callback_url":"https://fimpaypoint.com/payment/callback","metadata":{"user_id":123,"custom_charge":110}}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/checkout/initialize" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/checkout/initialize");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"first_name\":\"Abiola\",\"last_name\":\"Bayo\",\"email\":\"[email protected]\",\"phone\":\"08099887766\",\"amount\":5000,\"fee_bearer\":\"customer\",\"reference\":\"ORD_1795076650\",\"callback_url\":\"https://fimpaypoint.com/payment/callback\",\"metadata\":{\"user_id\":123,\"custom_charge\":110}}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"message": "Authorization URL created",
"data": {
"authorization_url": "https://fimpaypoint.com/pay/FIM_CHK_202608250242205409",
"access_code": "59c52834ef1d00ee451ab384a05f1224f35d6d8e1a1bbdb75cb5d356bfd682ad",
"reference": "FIM_CHK_202608250242205409",
"merchant_reference": "ORD_1787234650",
"account_number": "9816500658",
"bank_name": "Wema Bank",
"bank_code": "035",
"account_name": "FIMGOHOSTWEBS/CHECKOUT FIMPAYPOINT",
"amount": 5045,
"base_amount": 5000,
"fee": 45,
"fee_bearer": "customer",
"settlement_amount": 5000,
"amount_kobo": 504500,
"metadata": {
"user_id": 123,
"custom_charge": 110
},
"expires_at": "2026-11-19 09:54:10",
"expiry_seconds": 1800
}
}
Verify Transaction (Server-Side)
Verify the real-time status of a transaction using its reference. When a customer finishes their transfer on the checkout page, they are redirected back to your callback_url?reference=...&status=success. Your backend server should call this verification endpoint synchronously before crediting the user or fulfilling the order. No webhook setup is strictly required.
If your website, SMM panel, or platform (e.g. CodeIgniter, Laravel, WordPress, WooCommerce) relies on synchronous verification on the return/callback URL, simply query this endpoint upon receiving the redirect callback to safely confirm payment.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
URL Path Parameter
| Parameter | Type | Required | Description |
|---|---|---|---|
reference |
string | Required | The transaction reference (e.g. FIM_CHK_2026082501509921) or your custom merchant_reference. |
Code Examples & Response
curl -X GET "https://fimpaypoint.com/api/v1/transaction/verify/FIM_CHK_2026082501509921" \
-H "Authorization: Bearer sk_live_your_secret_key" \
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'get',
url: 'https://fimpaypoint.com/api/v1/transaction/verify/FIM_CHK_2026082501509921',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/transaction/verify/FIM_CHK_2026082501509921"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/transaction/verify/FIM_CHK_2026082501509921",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var response = await client.GetAsync("https://fimpaypoint.com/api/v1/transaction/verify/FIM_CHK_2026082501509921");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/transaction/verify/FIM_CHK_2026082501509921")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/transaction/verify/FIM_CHK_2026082501509921" -Method GET -Headers $headers
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/transaction/verify/FIM_CHK_2026082501509921");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"message": "Verification successful",
"data": {
"id": 1042,
"status": "success",
"reference": "FIM_CHK_2026082501509921",
"merchant_reference": "ORD_1794104059",
"amount": 5045,
"base_amount": 5000,
"fee": 45,
"fee_bearer": "customer",
"amount_paid": 5045,
"settlement_amount": 5000,
"amount_kobo": 504500,
"currency": "NGN",
"metadata": {
"user_id": 123,
"custom_charge": 110
},
"transaction_date": "2026-08-25T01:50:00+01:00",
"paid_at": "2026-08-25T01:52:10+01:00",
"channel": "bank_transfer",
"gateway_response": "Successful",
"customer": {
"name": "John Doe",
"email": "[email protected]",
"phone": "08012345678"
},
"bank": {
"account_number": "8091234567",
"bank_name": "Wema Bank",
"account_name": "FIMPAYPOINT CHECKOUT"
}
}
}
Web Checkout Virtual Accounts
Generate an instant virtual bank account for customer web checkout and invoices. Perfect for e-commerce web checkouts, cart settlements, one-time invoice payments, and automated bank transfer checkout. The generated checkout account is tied directly to the customer's exact order amount, automatically verifies inbound payments, credits your wallet instantly, and fires webhooks to your callback URL.
โก Web Checkout vs. Dedicated Customer Accounts
Created instantly per order or cart checkout. No customer BVN or NIN required, zero setup friction, 30-minute expiry window, automatically matched to the exact order amount with automatic bank switch rejection of underpayments.
Permanent bank account assigned to a customer profile. Ideal for recurring customer wallet top-ups, permanent subscription billing, and customer sub-accounts.
When your customer completes the bank transfer, payments are settled directly to your wallet in real time and an instant webhook event is dispatched to your callback URL with the transaction details.
You can pass "fee_bearer": "customer" or "fee_bearer": "merchant" in your API request.
โข "customer" (or "client"): The processing fee is added to the checkout amount so your customer pays amount + fee, and your wallet receives 100% of the base order amount.
โข "merchant": The customer pays the exact order amount, and the fee is deducted from your settlement.
โข What if omitted? If your website does not pass fee_bearer, FimPaypoint automatically checks your preference configured in Dashboard → Settings → Checkout Experience. If unset, it safely defaults to "merchant".
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
amount |
float | number | Required | Expected transfer amount in NGN (e.g. 5000.00). Must be greater than โฆ50. |
email |
string | Required | Customer's email address for receipt and transaction resolution. |
first_name |
string | Optional | Customer's first name. |
last_name |
string | Optional | Customer's last name. |
phone |
string | Optional | Customer's mobile telephone number (e.g. 08012345678). |
fee_bearer |
string | Optional | Who pays the transaction fee: "customer" or "merchant". If omitted, falls back to your Dashboard Checkout Experience setting, or defaults to "merchant". |
callback_url |
string | Optional | URL to redirect customer after payment confirmation on the hosted checkout page. Accepts aliases: redirect_url, redirect_link, return_url. |
reference |
string | Optional | Your custom unique transaction reference from your website/system for tracking. Accepts aliases: merchant_reference, tx_ref. |
metadata |
object | array | Optional | Key-value map or object with custom data (e.g. {"user_id": 123, "order_id": 45}). Echoed back in verification responses and webhooks. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/dynamic-accounts" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"fee_bearer": "customer",
"reference": "ORD_1787234650",
"callback_url": "https://fimpaypoint.com/payment/callback",
"metadata": {
"user_id": 123,
"custom_charge": 110
}
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/dynamic-accounts',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"amount": 5000,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"fee_bearer": "customer",
"reference": "ORD_1787234650",
"callback_url": "https://fimpaypoint.com/payment/callback",
"metadata": {
"user_id": 123,
"custom_charge": 110
}
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/dynamic-accounts"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"amount": 5000,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"fee_bearer": "customer",
"reference": "ORD_1787234650",
"callback_url": "https:\/\/fimpaypoint.com\/payment\/callback",
"metadata": {
"user_id": 123,
"custom_charge": 110
}
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'amount' => 5000.0,
'email' => '[email protected]',
'first_name' => 'John',
'last_name' => 'Doe',
'phone' => '08012345678',
'fee_bearer' => 'customer',
'reference' => 'ORD_1787234650',
'callback_url' => 'https://fimpaypoint.com/payment/callback',
'metadata' =>
array (
'user_id' => 123,
'custom_charge' => 110,
),
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/dynamic-accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"amount\":5000,\"email\":\"[email protected]\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"phone\":\"08012345678\",\"fee_bearer\":\"customer\",\"reference\":\"ORD_1787234650\",\"callback_url\":\"https://fimpaypoint.com/payment/callback\",\"metadata\":{\"user_id\":123,\"custom_charge\":110}}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/dynamic-accounts", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/dynamic-accounts")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"amount": 5000,
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"fee_bearer": "customer",
"reference": "ORD_1787234650",
"callback_url": "https:\/\/fimpaypoint.com\/payment\/callback",
"metadata": {
"user_id": 123,
"custom_charge": 110
}
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"amount":5000,"email":"[email protected]","first_name":"John","last_name":"Doe","phone":"08012345678","fee_bearer":"customer","reference":"ORD_1787234650","callback_url":"https://fimpaypoint.com/payment/callback","metadata":{"user_id":123,"custom_charge":110}}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/dynamic-accounts" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/dynamic-accounts");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"amount\":5000,\"email\":\"[email protected]\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"phone\":\"08012345678\",\"fee_bearer\":\"customer\",\"reference\":\"ORD_1787234650\",\"callback_url\":\"https://fimpaypoint.com/payment/callback\",\"metadata\":{\"user_id\":123,\"custom_charge\":110}}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"service": "DYNAMIC_ACCOUNT_ALLOCATION",
"session_id": "cs_99a81b2c4e",
"reference": "FIM_CHK_2026082501509921",
"transaction_reference": "FIM_CHK_2026082501509921",
"merchant_reference": "ORD_1787234650",
"checkout_url": "https://fimpaypoint.com/pay/FIM_CHK_2026082501509921",
"authorization_url": "https://fimpaypoint.com/pay/FIM_CHK_2026082501509921",
"redirect_url": "https://fimpaypoint.com/payment/callback",
"account_number": "8091234567",
"bank_name": "Wema Bank",
"bank_code": "035",
"account_name": "FIMPAYPOINT CHECKOUT",
"amount": 5045,
"base_amount": 5000,
"fee": 45,
"fee_bearer": "customer",
"settlement_amount": 5000,
"metadata": {
"user_id": 123,
"custom_charge": 110
},
"expires_at": "2026-08-25 02:20:00",
"expiry_seconds": 1800
}
Verifying Web Checkout Payment Status
You can query the real-time status of a checkout session at any time by calling GET /api/v1/dynamic-accounts/{session_id_or_reference}. You can pass either the session_id (e.g. cs_...), the standard transaction reference (e.g. FIM_CHK_...), or your custom merchant_reference:
curl -X GET "https://fimpaypoint.com/api/v1/dynamic-accounts/FIM_CHK_2026082501509921" \
-H "Authorization: Bearer sk_live_your_secret_key" \
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'get',
url: 'https://fimpaypoint.com/api/v1/dynamic-accounts/FIM_CHK_2026082501509921',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/dynamic-accounts/FIM_CHK_2026082501509921"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/dynamic-accounts/FIM_CHK_2026082501509921",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var response = await client.GetAsync("https://fimpaypoint.com/api/v1/dynamic-accounts/FIM_CHK_2026082501509921");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/dynamic-accounts/FIM_CHK_2026082501509921")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/dynamic-accounts/FIM_CHK_2026082501509921" -Method GET -Headers $headers
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/dynamic-accounts/FIM_CHK_2026082501509921");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"session_id": "cs_99a81b2c4e",
"payment_status": "PAID",
"reference": "FIM_CHK_2026082501509921",
"merchant_reference": "ORD_1787234650",
"checkout_url": "https://fimpaypoint.com/pay/FIM_CHK_2026082501509921",
"authorization_url": "https://fimpaypoint.com/pay/FIM_CHK_2026082501509921",
"redirect_url": "https://fimpaypoint.com/payment/callback",
"account_number": "8091234567",
"bank_name": "Wema Bank",
"bank_code": "035",
"account_name": "FIMPAYPOINT CHECKOUT",
"amount": 5045,
"base_amount": 5000,
"fee": 45,
"fee_bearer": "customer",
"settlement_amount": 5000,
"amount_expected": 5045,
"amount_paid": 5045,
"net_amount": 5000,
"metadata": {
"user_id": 123,
"custom_charge": 110
},
"customer": {
"name": "John Doe",
"email": "[email protected]",
"phone": "08012345678"
},
"expires_at": "2026-08-25 02:20:00",
"is_expired": false,
"created_at": "2026-08-25 01:50:00"
}
Create Virtual Account
Reserve a dynamic or dedicated virtual bank account for your customer in a single integration step. If the customer does not exist in the database, they will be registered automatically under your business profile.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
first_name |
string | Required | Customer's first name as it appears on their legal ID. |
last_name |
string | Required | Customer's last name as it appears on their legal ID. |
phone |
string | Required | Customer's phone number (e.g. 08031112222). |
email |
string | Required | Customer's email address. Must be unique per account. |
merchant_id |
string | int | Required | Your unique merchant identifier number. |
bank |
string | Required | Bank code from the Bank List endpoint (e.g. 035, 50211) or bank name (e.g. wema, providus, palmpay). |
nin |
string | Conditional | Customer's 11-digit National Identity Number. Accepted by Providus Bank, SafeHaven, VFD Bank & 9PSB. |
bvn |
string | Conditional | Customer's 11-digit Bank Verification Number. Required for Providus Bank, VFD & SafeHaven permanent NUBANs. |
dob |
string | Conditional | Customer's date of birth (e.g. 12-sep-1988 or 1988-09-12). Required for VFD Bank permanent NUBAN creation. |
gender |
string | Optional | Customer's gender (Male or Female). Recommended for VFD Bank. |
address |
string | Optional | Customer's residential street address. Recommended for VFD Bank. |
middle_name |
string | Optional | Customer's middle name as it appears on their legal identification. |
๐ Partner Bank KYC & BVN / NIN Guidelines
Per Central Bank of Nigeria (CBN) compliance regulations and upstream bank partner APIs, virtual accounts carry specific identification requirements based on the banking rail:
| Partner Bank | Bank Code | BVN / NIN Requirement | Tier Limit / Compliance Notes |
|---|---|---|---|
| 9PSB (9 Payment Service Bank) | 120001 / 000040 |
Conditional (Recommended) | Optional for Tier-1 (basic transaction cap). 11-digit BVN or NIN recommended for Tier-2 / Tier-3 high-volume accounts. |
| Providus Bank | 50211 / 101 |
Mandatory (BVN or NIN) | Valid 11-digit BVN or NIN is strictly required to issue a static reserved NUBAN. |
| Wema Bank / ALAT | 035 |
Optional (Basic Tier-1) | BVN / NIN not mandatory. Dedicated business accounts can pass BVN for uncapped limits. |
| SafeHaven MFB | 090286 / 50849 |
Mandatory (BVN or NIN) | SafeHaven BaaS requires an 11-digit BVN or NIN matching the customer's legal name. |
| VFD Microfinance Bank | 566 / 090110 |
Mandatory (BVN or NIN) | Valid 11-digit BVN (or NIN) with date of birth (dob), gender, and address is required for permanent NUBAN creation. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/virtual-accounts" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"email": "[email protected]",
"merchant_id": "1001",
"bank": "wema",
"nin": "12345678901",
"bvn": "22233344455"
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/virtual-accounts',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"email": "[email protected]",
"merchant_id": "1001",
"bank": "wema",
"nin": "12345678901",
"bvn": "22233344455"
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/virtual-accounts"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"email": "[email protected]",
"merchant_id": "1001",
"bank": "wema",
"nin": "12345678901",
"bvn": "22233344455"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'first_name' => 'John',
'last_name' => 'Doe',
'phone' => '08012345678',
'email' => '[email protected]',
'merchant_id' => '1001',
'bank' => 'wema',
'nin' => '12345678901',
'bvn' => '22233344455',
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/virtual-accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"phone\":\"08012345678\",\"email\":\"[email protected]\",\"merchant_id\":\"1001\",\"bank\":\"wema\",\"nin\":\"12345678901\",\"bvn\":\"22233344455\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/virtual-accounts", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/virtual-accounts")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"email": "[email protected]",
"merchant_id": "1001",
"bank": "wema",
"nin": "12345678901",
"bvn": "22233344455"
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"first_name":"John","last_name":"Doe","phone":"08012345678","email":"[email protected]","merchant_id":"1001","bank":"wema","nin":"12345678901","bvn":"22233344455"}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/virtual-accounts" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/virtual-accounts");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"phone\":\"08012345678\",\"email\":\"[email protected]\",\"merchant_id\":\"1001\",\"bank\":\"wema\",\"nin\":\"12345678901\",\"bvn\":\"22233344455\"}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"service": "CREATE_VIRTUAL_ACCOUNT",
"merchant_id": 1001,
"banks": [
{
"bankName": "Wema Bank",
"accountNumber": "9900112233",
"accountName": "John Doe",
"bankCode": "035",
"status": "ACTIVE"
}
]
}
To guarantee 99.99% Virtual Account creation uptime during occasional upstream NIBSS or provider maintenance, configure your application with an array of preferred banks in priority order (e.g. 035 Wema → 50211 Providus → 999991 PalmPay → 090405 Moniepoint). If the primary bank times out or returns an error, your code immediately cascades to the next bank in milliseconds.
Cascading Fallback Implementation Samples
<?php
function createVirtualAccountWithFallback(array $customerData, string $secretKey, string $baseUrl) {
$preferredBanks = ['035', '50211', '999991', '090405']; // Wema -> Providus -> PalmPay -> Moniepoint
foreach ($preferredBanks as $bankCode) {
$customerData['bank'] = $bankCode;
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => rtrim($baseUrl, '/') . '/api/v1/virtual-accounts',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5, // 5s timeout before cascading
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($customerData),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $secretKey,
'Content-Type: application/json'
]
]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($httpCode === 200) {
$result = json_decode($response, true);
if (!empty($result['status'])) {
return $result;
}
}
}
throw new Exception("All fallback banks are currently unavailable.");
}
$customer = [
'first_name' => 'John',
'last_name' => 'Doe',
'phone' => '08012345678',
'email' => '[email protected]'
];
$account = createVirtualAccountWithFallback($customer, 'sk_live_your_secret_key', 'https://fimpaypoint.com');
print_r($account);
const axios = require('axios');
async function createVirtualAccountWithFallback(customerData, secretKey, baseUrl) {
const preferredBanks = ['035', '50211', '999991', '090405']; // Wema -> Providus -> PalmPay -> Moniepoint
for (const bankCode of preferredBanks) {
try {
const response = await axios.post(
`${baseUrl}/api/v1/virtual-accounts`,
{ ...customerData, bank: bankCode },
{
headers: {
'Authorization': `Bearer ${secretKey}`,
'Content-Type': 'application/json'
},
timeout: 5000 // 5-second timeout before trying next bank
}
);
if (response.data && response.data.status) {
console.log(`โ
Virtual account created via bank code: ${bankCode}`);
return response.data;
}
} catch (error) {
console.warn(`Bank ${bankCode} failed, cascading to next fallback bank...`);
}
}
throw new Error('All fallback banks are currently unavailable.');
}
createVirtualAccountWithFallback(
{ first_name: 'John', last_name: 'Doe', phone: '08012345678', email: '[email protected]' },
'sk_live_your_secret_key',
'https://fimpaypoint.com'
).then(acc => console.log(acc));
# Multi-Bank Cascading Fallback in Python
# Automatically loops through banks until an active virtual account is provisioned.
import requests
def create_virtual_account_with_fallback(customer_data, secret_key, base_url):
# Define preferred banks in priority order
preferred_banks = ['035', '50211', '999991', '090405'] # Wema -> Providus -> PalmPay -> Moniepoint
headers = {
'Authorization': f'Bearer {secret_key}',
'Content-Type': 'application/json'
}
for bank_code in preferred_banks:
payload = {**customer_data, 'bank': bank_code}
try:
res = requests.post(
f'{base_url}/api/v1/virtual-accounts',
json=payload,
headers=headers,
timeout=5 # 5-second timeout before trying next bank
)
data = res.json()
if res.status_code == 200 and data.get('status'):
print(f"โ
Virtual account created via bank: {bank_code}")
return data
except requests.RequestException:
print(f"Bank {bank_code} unavailable, trying next fallback bank...")
continue
raise Exception("All fallback banks are currently unavailable.")
# Usage Example:
account = create_virtual_account_with_fallback(
{'first_name': 'John', 'last_name': 'Doe', 'phone': '08012345678', 'email': '[email protected]'},
'sk_live_your_secret_key',
'https://fimpaypoint.com'
)
print(account)
{
"status": true,
"service": "CREATE_VIRTUAL_ACCOUNT",
"merchant_id": 1001,
"banks": [
{
"bankName": "Providus Bank",
"accountNumber": "9900456789",
"accountName": "John Doe",
"bankCode": "50211",
"status": "ACTIVE"
}
]
}
Fetch Virtual Accounts
Query or list active virtual bank accounts created under your merchant profile.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
merchant_id |
string | Optional | Filters accounts by your merchant ID. |
email |
string | Optional | Filters accounts by the customer's email address. |
accountNumber |
string | Optional | Locate details for a specific bank account number. |
Code Examples & Response
curl -X GET "https://fimpaypoint.com/api/v1/virtual-accounts?merchant_id=1001" \
-H "Authorization: Bearer sk_live_your_secret_key" \
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'get',
url: 'https://fimpaypoint.com/api/v1/virtual-accounts?merchant_id=1001',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/virtual-accounts?merchant_id=1001"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/virtual-accounts?merchant_id=1001",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var response = await client.GetAsync("https://fimpaypoint.com/api/v1/virtual-accounts?merchant_id=1001");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/virtual-accounts?merchant_id=1001")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/virtual-accounts?merchant_id=1001" -Method GET -Headers $headers
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/virtual-accounts?merchant_id=1001");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"service": "FETCH_VIRTUAL_ACCOUNT",
"merchant_id": 1001,
"accounts": [
{
"id": 1,
"name": "John Doe",
"bank": "palmpay",
"account": "9900112233",
"merchant_id": 1001,
"user_id": 2001,
"created_at": "2025-03-20T13:30:06.000000Z",
"updated_at": "2025-03-20T13:30:06.000000Z"
},
{
"id": 2,
"name": "Jane Doe",
"bank": "palmpay",
"account": "9900445566",
"merchant_id": 1001,
"user_id": 2002,
"created_at": "2025-03-20T13:30:06.000000Z",
"updated_at": "2025-03-20T13:30:06.000000Z"
}
]
}
Bank List
Retrieve a list of all active banks and codes supported by your configuration for virtual account creation. You can use the bank codes returned by this endpoint in the bank parameter when creating virtual accounts.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Try It Out
Execute a live test call against the Bank List API. Input your API key (secret key starting with sk_live_ or sk_test_) to fetch the active bank list.
Active Bank List
Update Customer
Update existing customer identity information such as National Identity Number (NIN) or Bank Verification Number (BVN).
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
merchant_id |
string | Required | Your unique merchant ID. |
email |
string | Required | Customer's registered email address. |
nin |
string | Optional | Customer's National Identity Number (NIN) to update. |
bvn |
string | Optional | Customer's Bank Verification Number (BVN) to update. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/customers/update" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"merchant_id": "1001",
"email": "[email protected]",
"nin": "12345678901"
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/customers/update',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"merchant_id": "1001",
"email": "[email protected]",
"nin": "12345678901"
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/customers/update"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"merchant_id": "1001",
"email": "[email protected]",
"nin": "12345678901"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'merchant_id' => '1001',
'email' => '[email protected]',
'nin' => '12345678901',
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/customers/update",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"merchant_id\":\"1001\",\"email\":\"[email protected]\",\"nin\":\"12345678901\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/customers/update", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/customers/update")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"merchant_id": "1001",
"email": "[email protected]",
"nin": "12345678901"
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"merchant_id":"1001","email":"[email protected]","nin":"12345678901"}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/customers/update" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/customers/update");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"merchant_id\":\"1001\",\"email\":\"[email protected]\",\"nin\":\"12345678901\"}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"service": "UPDATE_CUSTOMER_ACCOUNT",
"merchant_id": 1001,
"customers": {
"id": 2001,
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"email": "[email protected]",
"nin": "12345678901",
"bvn": "22233344455",
"merchant_id": 1001,
"created_at": "2026-08-14T21:47:56.000000Z",
"updated_at": "2026-08-14T22:31:00.000000Z"
}
}
Delete Customer
Remove a customer account from your business profile in Fimpaypoint.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
merchant_id |
string | Required | Your unique merchant ID. |
email |
string | Required | Customer's registered email address to delete. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/customers/delete" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"merchant_id": "1001",
"email": "[email protected]"
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/customers/delete',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"merchant_id": "1001",
"email": "[email protected]"
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/customers/delete"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"merchant_id": "1001",
"email": "[email protected]"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'merchant_id' => '1001',
'email' => '[email protected]',
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/customers/delete",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"merchant_id\":\"1001\",\"email\":\"[email protected]\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/customers/delete", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/customers/delete")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"merchant_id": "1001",
"email": "[email protected]"
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"merchant_id":"1001","email":"[email protected]"}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/customers/delete" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/customers/delete");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"merchant_id\":\"1001\",\"email\":\"[email protected]\"}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"service": "DELETE_CUSTOMER_ACCOUNT",
"message": "Customer deleted successfully."
}
Fetch All Customers
Retrieve a list of all customers associated with your business.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Query Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
merchant_id |
string | Required | Your unique merchant ID. |
Code Examples & Response
curl -X GET "https://fimpaypoint.com/api/v1/customers/fetch?merchant_id=1001" \
-H "Authorization: Bearer sk_live_your_secret_key" \
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'get',
url: 'https://fimpaypoint.com/api/v1/customers/fetch?merchant_id=1001',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/customers/fetch?merchant_id=1001"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/customers/fetch?merchant_id=1001",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var response = await client.GetAsync("https://fimpaypoint.com/api/v1/customers/fetch?merchant_id=1001");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/customers/fetch?merchant_id=1001")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/customers/fetch?merchant_id=1001" -Method GET -Headers $headers
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/customers/fetch?merchant_id=1001");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"service": "FETCH_CUSTOMER_ACCOUNT",
"customers": [
{
"id": 2001,
"first_name": "John",
"last_name": "Doe",
"phone": "08012345678",
"email": "[email protected]",
"nin": "12345678901",
"bvn": "22233344455",
"merchant_id": 1001,
"created_at": "2026-08-14T21:47:56.000000Z",
"updated_at": "2026-08-14T21:47:56.000000Z"
}
]
}
NIN Enquiry
Verify a customer's identity using their National Identity Number (NIN). Supports Basic (match check) and Enhanced (full data retrieval) lookup types.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
type |
string | Required | Must be set to basic or enhanced. |
verify_type |
string | Required | Must be set to nin. |
number |
string | Required | The 11-digit NIN to verify. |
gender |
string | Required | Gender of the individual โ Male or Female. |
birthday |
string | Required | Date of birth in YYYY-MM-DD format (e.g. 1999-08-09). |
firstName |
string | Required | First name to match against NIN records. |
middleName |
string | Required | Middle name to match against NIN records. |
lastName |
string | Required | Last name (surname) to match against NIN records. |
phoneNumber |
string | Required | Phone number registered with the NIN. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/verification" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"type": "basic",
"verify_type": "nin",
"number": "12345678901",
"gender": "Male",
"birthday": "1999-08-09",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"phoneNumber": "08012345678"
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/verification',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"type": "basic",
"verify_type": "nin",
"number": "12345678901",
"gender": "Male",
"birthday": "1999-08-09",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"phoneNumber": "08012345678"
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/verification"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"type": "basic",
"verify_type": "nin",
"number": "12345678901",
"gender": "Male",
"birthday": "1999-08-09",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"phoneNumber": "08012345678"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'type' => 'basic',
'verify_type' => 'nin',
'number' => '12345678901',
'gender' => 'Male',
'birthday' => '1999-08-09',
'firstName' => 'John',
'middleName' => 'Michael',
'lastName' => 'Doe',
'phoneNumber' => '08012345678',
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/verification",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"type\":\"basic\",\"verify_type\":\"nin\",\"number\":\"12345678901\",\"gender\":\"Male\",\"birthday\":\"1999-08-09\",\"firstName\":\"John\",\"middleName\":\"Michael\",\"lastName\":\"Doe\",\"phoneNumber\":\"08012345678\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/verification", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/verification")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"type": "basic",
"verify_type": "nin",
"number": "12345678901",
"gender": "Male",
"birthday": "1999-08-09",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"phoneNumber": "08012345678"
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"type":"basic","verify_type":"nin","number":"12345678901","gender":"Male","birthday":"1999-08-09","firstName":"John","middleName":"Michael","lastName":"Doe","phoneNumber":"08012345678"}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/verification" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/verification");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"type\":\"basic\",\"verify_type\":\"nin\",\"number\":\"12345678901\",\"gender\":\"Male\",\"birthday\":\"1999-08-09\",\"firstName\":\"John\",\"middleName\":\"Michael\",\"lastName\":\"Doe\",\"phoneNumber\":\"08012345678\"}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": "verified",
"data": {
"respCode": "00000000",
"respMsg": "success",
"data": {
"nameMatchRlt": "Exact Match",
"namesMatchPercentage": 100,
"birthdayMatchRlt": "Exact Match",
"genderMatchRlt": "Exact Match",
"phoneNumberMatchRlt": "Exact Match"
},
"needCost": true,
"requestId": "1000000000000650461675341656065"
},
"cached": false
}
BVN Enquiry
Verify a customer's identity using their Bank Verification Number (BVN). Supports Basic (match check) and Enhanced (full data retrieval) lookup types.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
type |
string | Required | Must be set to basic or enhanced. |
verify_type |
string | Required | Must be set to bvn. |
number |
string | Required | The 11-digit BVN to verify. |
gender |
string | Required | Gender of the individual โ Male or Female. |
birthday |
string | Required | Date of birth in YYYY-MM-DD format (e.g. 1999-08-09). |
firstName |
string | Required | First name to match against BVN records. |
middleName |
string | Required | Middle name to match against BVN records. |
lastName |
string | Required | Last name (surname) to match against BVN records. |
phoneNumber |
string | Required | Phone number registered with the BVN. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/verification" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"type": "basic",
"verify_type": "bvn",
"number": "22233344455",
"gender": "Male",
"birthday": "1999-08-09",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"phoneNumber": "08012345678"
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/verification',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"type": "basic",
"verify_type": "bvn",
"number": "22233344455",
"gender": "Male",
"birthday": "1999-08-09",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"phoneNumber": "08012345678"
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/verification"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"type": "basic",
"verify_type": "bvn",
"number": "22233344455",
"gender": "Male",
"birthday": "1999-08-09",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"phoneNumber": "08012345678"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'type' => 'basic',
'verify_type' => 'bvn',
'number' => '22233344455',
'gender' => 'Male',
'birthday' => '1999-08-09',
'firstName' => 'John',
'middleName' => 'Michael',
'lastName' => 'Doe',
'phoneNumber' => '08012345678',
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/verification",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"type\":\"basic\",\"verify_type\":\"bvn\",\"number\":\"22233344455\",\"gender\":\"Male\",\"birthday\":\"1999-08-09\",\"firstName\":\"John\",\"middleName\":\"Michael\",\"lastName\":\"Doe\",\"phoneNumber\":\"08012345678\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/verification", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/verification")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"type": "basic",
"verify_type": "bvn",
"number": "22233344455",
"gender": "Male",
"birthday": "1999-08-09",
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"phoneNumber": "08012345678"
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"type":"basic","verify_type":"bvn","number":"22233344455","gender":"Male","birthday":"1999-08-09","firstName":"John","middleName":"Michael","lastName":"Doe","phoneNumber":"08012345678"}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/verification" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/verification");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"type\":\"basic\",\"verify_type\":\"bvn\",\"number\":\"22233344455\",\"gender\":\"Male\",\"birthday\":\"1999-08-09\",\"firstName\":\"John\",\"middleName\":\"Michael\",\"lastName\":\"Doe\",\"phoneNumber\":\"08012345678\"}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": "verified",
"data": {
"respCode": "00000000",
"respMsg": "success",
"data": {
"nameMatchRlt": "Exact Match",
"namesMatchPercentage": 100,
"birthdayMatchRlt": "Exact Match",
"genderMatchRlt": "Exact Match",
"phoneNumberMatchRlt": "Exact Match"
},
"needCost": true,
"requestId": "1000000000000650462659411275777"
},
"cached": false
}
BVN Verification
Perform a real-time BVN record verification check. Returns government registry name, match confidence score, and phone matching. Billed directly to your merchant wallet balance.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
bvn |
string | Required | The 11-digit BVN number to verify. |
expected_name |
string | Optional | Customer's full name to calculate fuzzy match score against government records. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/verification/bvn" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"bvn": "22233344455",
"expected_name": "JOHN DOE"
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/verification/bvn',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"bvn": "22233344455",
"expected_name": "JOHN DOE"
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/verification/bvn"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"bvn": "22233344455",
"expected_name": "JOHN DOE"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'bvn' => '22233344455',
'expected_name' => 'JOHN DOE',
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/verification/bvn",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"bvn\":\"22233344455\",\"expected_name\":\"JOHN DOE\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/verification/bvn", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/verification/bvn")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"bvn": "22233344455",
"expected_name": "JOHN DOE"
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"bvn":"22233344455","expected_name":"JOHN DOE"}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/verification/bvn" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/verification/bvn");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"bvn\":\"22233344455\",\"expected_name\":\"JOHN DOE\"}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"verify_type": "BVN",
"bvn": "22233344455",
"resolved_name": "JOHN DOE",
"match_score": 95,
"is_approved": true,
"fee_charged": 100,
"details": {
"gender": "Male",
"dob": "1995-08-12",
"phone": "08012345678"
}
}
NIN Verification
Perform a real-time National Identity Number (NIN) lookup. Validates customer identity against NIMC database records. Billed directly to your merchant wallet balance.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
nin |
string | Required | The 11-digit National Identity Number. |
expected_name |
string | Optional | Customer's full name to calculate string match score against registered NIMC data. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/verification/nin" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"nin": "12345678901",
"expected_name": "JOHN DOE"
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/verification/nin',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"nin": "12345678901",
"expected_name": "JOHN DOE"
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/verification/nin"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"nin": "12345678901",
"expected_name": "JOHN DOE"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'nin' => '12345678901',
'expected_name' => 'JOHN DOE',
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/verification/nin",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"nin\":\"12345678901\",\"expected_name\":\"JOHN DOE\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/verification/nin", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/verification/nin")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"nin": "12345678901",
"expected_name": "JOHN DOE"
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"nin":"12345678901","expected_name":"JOHN DOE"}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/verification/nin" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/verification/nin");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"nin\":\"12345678901\",\"expected_name\":\"JOHN DOE\"}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"verify_type": "NIN",
"nin": "12345678901",
"resolved_name": "JOHN DOE",
"match_score": 100,
"is_approved": true,
"fee_charged": 120,
"details": {
"gender": "Male",
"dob": "1998-05-14",
"phone": "08012345678"
}
}
Initiate Transfer
Send money to any Nigerian bank account directly from your wallet balance in real-time.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Content-Type |
string | Required | Must be set to application/json. |
Request Body Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
amount |
number | Required | Amount to transfer in Naira (NGN). |
bank_code |
string | Required | Destination bank code from the Bank List endpoint. |
account_number |
string | Required | 10-digit recipient NUBAN account number. |
recipient_name |
string | Required | Recipient legal account name. |
narration |
string | Optional | Transaction memo or description. |
Code Examples & Response
curl -X POST "https://fimpaypoint.com/api/v1/payout/transfer" \
-H "Authorization: Bearer sk_live_your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 25000,
"recipient_name": "John Doe",
"account_number": "2086186105",
"bank_code": "011",
"narration": "Vendor payout settlement"
}'
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'post',
url: 'https://fimpaypoint.com/api/v1/payout/transfer',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
},
data: {
"amount": 25000,
"recipient_name": "John Doe",
"account_number": "2086186105",
"bank_code": "011",
"narration": "Vendor payout settlement"
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/payout/transfer"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
payload = {
"amount": 25000,
"recipient_name": "John Doe",
"account_number": "2086186105",
"bank_code": "011",
"narration": "Vendor payout settlement"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
<?php
$curl = curl_init();
$payload = json_encode(array (
'amount' => 25000,
'recipient_name' => 'John Doe',
'account_number' => '2086186105',
'bank_code' => '011',
'narration' => 'Vendor payout settlement',
));
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/payout/transfer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var json = "{\"amount\":25000,\"recipient_name\":\"John Doe\",\"account_number\":\"2086186105\",\"bank_code\":\"011\",\"narration\":\"Vendor payout settlement\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://fimpaypoint.com/api/v1/payout/transfer", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/payout/transfer")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"amount": 25000,
"recipient_name": "John Doe",
"account_number": "2086186105",
"bank_code": "011",
"narration": "Vendor payout settlement"
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
$body = '{"amount":25000,"recipient_name":"John Doe","account_number":"2086186105","bank_code":"011","narration":"Vendor payout settlement"}'
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/payout/transfer" -Method POST -Headers $headers -Body $body
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/payout/transfer");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"amount\":25000,\"recipient_name\":\"John Doe\",\"account_number\":\"2086186105\",\"bank_code\":\"011\",\"narration\":\"Vendor payout settlement\"}");
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": "success",
"reference": "FIM|WDR|985464",
"amount": 25000,
"fee": 50,
"status_message": "Transfer Queued for Instant Settlement"
}
Account Balance
Check your business wallet balance in real-time. This endpoint allows you to retrieve the current balance of your business account.
Headers
| Header | Type | Requirement | Description |
|---|---|---|---|
Authorization |
string | Required | Bearer token format: Bearer sk_live_your_secret_key or Bearer sk_test_your_secret_key. Always use your Secret Key (never use your Public Key or Webhook Signing Key). |
Query Parameters
No parameters are required for this request.
Code Examples & Response
curl -X GET "https://fimpaypoint.com/api/v1/account/balance" \
-H "Authorization: Bearer sk_live_your_secret_key" \
const axios = require('axios');
async function makeRequest() {
try {
const response = await axios({
method: 'get',
url: 'https://fimpaypoint.com/api/v1/account/balance',
headers: {
'Authorization': 'Bearer sk_live_your_secret_key',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error.response ? error.response.data : error.message);
}
}
makeRequest();
import requests
url = "https://fimpaypoint.com/api/v1/account/balance"
headers = {
"Authorization": "Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://fimpaypoint.com/api/v1/account/balance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer sk_live_your_secret_key",
"Content-Type": "application/json"
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program {
static async Task Main() {
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_secret_key");
var response = await client.GetAsync("https://fimpaypoint.com/api/v1/account/balance");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://fimpaypoint.com/api/v1/account/balance")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sk_live_your_secret_key"
request["Content-Type"] = "application/json"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.body
$headers = @{
"Authorization" = "Bearer sk_live_your_secret_key"
"Content-Type" = "application/json"
}
Invoke-RestMethod -Uri "https://fimpaypoint.com/api/v1/account/balance" -Method GET -Headers $headers
#include <iostream>
#include <curl/curl.h>
int main() {
CURL *curl = curl_easy_init();
if (curl) {
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer sk_live_your_secret_key");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://fimpaypoint.com/api/v1/account/balance");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
}
return 0;
}
{
"status": true,
"service": "ACCOUNT_BALANCE_CHECK",
"balance": 219500.5
}
Webhooks & Signature Verification
Webhooks let FimPaypoint notify your application in real time when a payment event occurs. Instead of polling the API, your server receives an HTTP POST request whenever a payment is completed, failed, or reversed.
Setting Up Your Webhook URL
1. Go to your Dashboard: Log in to the FimPaypoint Dashboard and navigate to Settings → Webhooks.
2. Add Your Endpoint URL: Enter the publicly accessible URL of your server that will receive webhook events, e.g. https://yoursite.com/webhook/fimpay.
3. Verify the Signature: Use the HTTP_FIMPAY_SIGNATURE header to verify that every incoming request is genuinely from FimPaypoint.
HTTP_FIMPAY_SIGNATURE header before processing any webhook data.
Webhook Request Headers
| Header Name | Description |
|---|---|
HTTP_FIMPAY_SIGNATURE / fimpay-signature |
HMAC SHA-512 signature of the request body signed with your Webhook Signing Key. |
Content-Type |
application/json |
Webhook Payload
FimPaypoint sends a JSON POST body with the following structure:
{
"event": "payment.received",
"order": {
"amount": "5045.00",
"base_amount": 5000.00,
"fee_bearer": "customer",
"settlement_amount": 5000.00,
"fee": 45.00,
"currency": "NGN",
"merchant_reference": "ORD_1787234650",
"description": "9816482569 received 5,045.00 from SENDER NAME (XXXXXX3515, Access Bank)"
},
"transaction": {
"reference": "FIM_CHK_202611199102",
"merchant_reference": "ORD_1787234650",
"amount": 5000.00,
"base_amount": 5000.00,
"fee": 45.00,
"fee_bearer": "customer",
"amount_paid": 5045.00,
"settlement_amount": 5000.00,
"virtual_account_number": "9816482569",
"customer_name": "John Doe",
"customer_email": "[email protected]",
"customer_phone": "09052105063",
"payer_name": "SENDER FULL NAME",
"payer_bank": "Access Bank",
"payer_account": "XXXXXX3515",
"status": "SUCCESSFUL",
"metadata": {
"user_id": 123,
"custom_charge": 110
},
"timestamp": "2026-11-19 09:24:10"
},
"merchant_reference": "ORD_1787234650",
"metadata": {
"user_id": 123,
"custom_charge": 110
},
"account_number": "9816482569",
"customer": {
"id": 1,
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "09052105063",
"created_at": "2026-11-19 09:24:10"
}
}
Payload Fields
| Field | Type | Description |
|---|---|---|
event |
string | Notification event name (e.g. payment.received). |
order.amount |
string | Total transaction amount paid in Naira (NGN). |
order.base_amount |
float | Base order amount before fee additions. |
order.fee_bearer |
string | Who paid the transaction fee ("customer" or "merchant"). |
order.settlement_amount |
float | Net credited merchant wallet amount after fees. |
order.fee |
float | Gateway processing fee charged. |
transaction.reference |
string | Unique platform transaction reference (URL-safe format, e.g. FIM_CHK_...). |
transaction.merchant_reference |
string | Your original custom order reference echoed back. |
transaction.metadata |
object | array | Your custom metadata object passed during checkout initialization. |
transaction.virtual_account_number |
string | Destination virtual NUBAN account that received payment. |
transaction.customer_name |
string | Customer name on file. |
transaction.payer_name |
string | Origin bank sender name resolved from interbank transfer narration. |
transaction.payer_bank |
string | Sender origin bank name. |
transaction.status |
string | Status of the transaction (SUCCESSFUL). |
customer.id |
integer | Unique sequential customer ID across the platform. |
Signature Verification Examples
<?php
$payload = file_get_contents('php://input');
// Headers sent: HTTP_FIMPAY_SIGNATURE or fimpay-signature
$signature = $_SERVER['HTTP_FIMPAY_SIGNATURE'] ?? $_SERVER['HTTP_X_FIMPAY_SIGNATURE'] ?? '';
// Webhook Signing Secret from Dashboard -> Settings -> Webhooks (starts with whsec_live_... or whsec_test_...)
// (FimPaypoint also allows your Secret API Key sk_live_... as a fallback)
$secret = "whsec_live_your_webhook_signing_secret";
$hashkey = hash_hmac('sha512', $payload, $secret);
if (hash_equals($signature, $hashkey)) {
$data = json_decode($payload, true);
$reference = $data['transaction']['reference'] ?? '';
$merchantRef = $data['transaction']['merchant_reference'] ?? '';
$metadata = $data['transaction']['metadata'] ?? [];
// Fulfill order, credit user wallet, or mark invoice as paid...
http_response_code(200);
echo json_encode(["message" => "success"]);
} else {
http_response_code(400);
echo json_encode(["message" => "Invalid signature"]);
}
const crypto = require('crypto');
app.post('/webhook/fimpay', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['http_fimpay_signature'] || req.headers['x-fimpay-signature'] || req.headers['fimpay-signature'];
// Webhook Signing Secret from Dashboard -> Settings -> Webhooks (whsec_live_...) or Secret Key (sk_live_...)
const secret = process.env.FIMPAY_WEBHOOK_SECRET || "whsec_live_your_webhook_signing_secret";
const payload = req.body.toString();
const hashkey = crypto
.createHmac('sha512', secret)
.update(payload)
.digest('hex');
if (signature !== hashkey) {
return res.status(400).json({ message: 'Invalid signature' });
}
const data = JSON.parse(payload);
const reference = data.transaction.reference;
const merchantRef = data.transaction.merchant_reference;
const metadata = data.transaction.metadata || data.metadata;
// Fulfill order, credit user wallet, or update database...
res.status(200).json({ message: 'success' });
});
Delivery & Retry Policy
FimPaypoint employs an automated in-flight retry schedule to ensure you never miss a payment notification due to momentary network hiccups or brief server delays:
Fired synchronously on payment confirmation.
Retried if attempt 1 returns 5xx or times out.
Second retry for temporary server lag.
Final automatic attempt before logging failed.
2xx (e.g. 200 OK) status code, all further retries are canceled immediately.
Developer Best Practices
- Fast 200 Acknowledgment: Acknowledge the webhook within 3 seconds to prevent FimPaypoint's client from triggering a retry.
- Idempotency (Double-Credit Defense): Always check if
transaction.referencehas already been marked as fulfilled in your database before crediting value. - Manual Dashboard Redelivery: If your server is offline for an extended duration, you can manually re-trigger delivery anytime via Dashboard โ Webhooks โ Resend.
- HTTPS Only: Production webhook endpoints must be served over valid SSL/TLS (HTTPS).
Errors & Status Codes
FIM DIGITAL VENTURES LIMITED uses standard HTTP response status codes along with unified JSON error objects to indicate the outcome of API requests.
Standard JSON Error Format
Every error response returns a structured JSON payload providing an application-specific error code and developer-friendly message:
{
"status": false,
"error_code": "INVALID_BANK_CODE",
"message": "The specified bank code '999' is not supported or currently inactive.",
"errors": {
"bank": ["Bank code must be a valid active bank from GET /api/v1/banks."]
}
}
HTTP Status Codes Reference
Application Error Codes Dictionary
๐ฆ Official SDKs & Integration Packages
Accelerate your time to market with official, pre-built packages featuring automatic HMAC-SHA512 signature checks, idempotent order processing, and unified payment rails.
WooCommerce Payment Gateway Plugin
v1.0.0Official WordPress / WooCommerce payment gateway. Accepts automated Dedicated Virtual Accounts, Cards, Transfers, and USSD with zero custom code.
4-Step Quick Installation
In WordPress Admin, navigate to Plugins โ Add New โ Upload Plugin and choose the downloaded zip.
Click Activate Plugin to register FimPaypoint inside WooCommerce Payment Gateways.
Go to WooCommerce โ Settings โ Payments โ FimPaypoint. Paste your Live Public & Secret keys.
Copy the Webhook URL (/wc-api/wc_gateway_fimpay) into your FimPaypoint Webhook Settings.