⚡ Interactive API Sandbox & Live Console

Test live & sandbox API endpoints in real-time, inspect request payloads, and debug responses directly in your browser.

🔑 My API Keys

Testing Mode

🧪 Sandbox Test (Safe)

Sandbox Test Key (sk_test_...)

🔑

Choose API Endpoint

POST

⚡ Quick Parameter Controls (Auto-Syncs with JSON Body)

Merchant ID (merchant_id)

Customer Email (email)

First Name (first_name)

Last Name (last_name)

Header Key	Value
`Authorization`	`Bearer sk_test_demo_sandbox_fimpay`
`Content-Type`	`application/json`

Response Inspector 200 OK

HTTP Response Payload

// Click "🚀 Send Request" above to execute API call and inspect the live response...

Generated Code Snippets (Synced)

Recent Session Calls

Status	Method & Path	Time	Latency	Action
No requests made in this session yet.

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:

https://fimpaypoint.com/api/v1

For sandbox testing use:

https://fimpaypoint.com/api/test

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:

💬 WhatsApp Support +234 9052105063

✉️ Email Support support [at] fimpaypoint.com

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.

Header Authorization

Authorization: Bearer sk_live_your_secret_key_here
Content-Type: application/json

Keep your Secret Key safe

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

1

Create an Account

Sign up on the Dashboard and complete your business verification. Once approved, navigate to Settings → API Credentials to retrieve your keys.

2

Authenticate Your Requests

Include your Secret Key in the Authorization header of every API request.

3

Make Your First API Call

Use the Initialize Payment endpoint to create a payment session and redirect your customer to the hosted checkout page.

POST /api/v1/checkout/request

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 redirected to your redirect_link.

Amounts are in Naira (NGN)

Pass the amount in naira. For example, pass 100 to charge ₦100.

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`	string	Required	Amount to charge the customer in Naira (NGN).
`redirect_link`	string	Required	URL to redirect the customer after payment is completed.

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,
    "reference": "ORD_1790915091",
    "callback_url": "https://fimpaypoint.com/payment/callback"
}'

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,
    "reference": "ORD_1790915091",
    "callback_url": "https://fimpaypoint.com/payment/callback"
}
    });
    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,
    "reference": "ORD_1790915091",
    "callback_url": "https:\/\/fimpaypoint.com\/payment\/callback"
}

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,
  'reference' => 'ORD_1790915091',
  'callback_url' => 'https://fimpaypoint.com/payment/callback',
));

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,\"reference\":\"ORD_1790915091\",\"callback_url\":\"https://fimpaypoint.com/payment/callback\"}";
        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,
    "reference": "ORD_1790915091",
    "callback_url": "https:\/\/fimpaypoint.com\/payment\/callback"
})

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,"reference":"ORD_1790915091","callback_url":"https://fimpaypoint.com/payment/callback"}'

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,\"reference\":\"ORD_1790915091\",\"callback_url\":\"https://fimpaypoint.com/payment/callback\"}");
        CURLcode res = curl_easy_perform(curl);
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }
    return 0;
}

Response Body 200 OK

application/json

{
    "status": true,
    "message": "Authorization URL created",
    "data": {
        "authorization_url": "https://fimpaypoint.com/pay/FIM%7CCHK%7C202608250242205409",
        "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": 5000,
        "fee": 45,
        "expires_at": "2026-10-02 05:54:51",
        "expiry_seconds": 1800
    }
}

GET /api/v1/transaction/verify/{reference}

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.

💡 Synchronous Verification for Platforms Without Webhooks

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`) received on redirect callback or initialization response.

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;
}

Response Body 200 OK

application/json

{
    "status": true,
    "message": "Verification successful",
    "data": {
        "id": 1042,
        "status": "success",
        "reference": "FIM|CHK|2026082501509921",
        "amount": 5000,
        "amount_kobo": 500000,
        "fee": 0,
        "currency": "NGN",
        "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"
        }
    }
}

POST /api/v1/dynamic-accounts

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

Web Checkout Accounts (This Endpoint)

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.

Dedicated Customer Accounts (Next Section)

Permanent bank account assigned to a customer profile. Ideal for recurring customer wallet top-ups, permanent subscription billing, and customer sub-accounts.

🏦 Supported Banking Rails & Multi-Gateway Cascade

Dynamic Checkout accounts are dynamically provisioned across 10 institutional banking partners with intelligent multi-gateway failover: VFD Microfinance Bank (090110 / 566), SafeHaven MFB (090286), Wema Bank / ALAT (035), GTBank / Squad (058), Access Bank / Hydrogen (044), 9PSB / Anchor (120001), Providus Bank (50211), and Moniepoint (090405).

🛡️ Amount Validation & Overpayment Protection: Bank switches enforce exact transfer settlement (A4 / A0). Underpayments are rejected at the NIP switch level to protect your store from shortfall losses. In case of an overpayment, your cart/order is instantly marked PAID, your merchant wallet is credited with the exact expected order amount, and the excess surplus is safely quarantined in Platform Suspense Escrow for administrative refund or reconciliation.

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`).

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"
}'

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"
}
    });
    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"
}

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',
));

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\"}";
        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"
})

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"}'

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\"}");
        CURLcode res = curl_easy_perform(curl);
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }
    return 0;
}

Response Body 200 OK

application/json

{
    "status": true,
    "service": "DYNAMIC_ACCOUNT_ALLOCATION",
    "session_id": "cs_99a81b2c4e",
    "reference": "FIM|CHK|2026082501509921",
    "transaction_reference": "FIM|CHK|2026082501509921",
    "account_number": "8091234567",
    "bank_name": "Wema Bank",
    "bank_code": "035",
    "account_name": "FIMPAYPOINT CHECKOUT",
    "amount": 5000,
    "base_amount": 5000,
    "fee": 0,
    "fee_bearer": "MERCHANT",
    "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}:

curl -X GET "https://fimpaypoint.com/api/v1/dynamic-accounts/cs_99a81b2c4e" \
     -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/cs_99a81b2c4e',
      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/cs_99a81b2c4e"
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/cs_99a81b2c4e",
    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/cs_99a81b2c4e");
        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/cs_99a81b2c4e")
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/cs_99a81b2c4e" -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/cs_99a81b2c4e");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        CURLcode res = curl_easy_perform(curl);
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }
    return 0;
}

Response Body 200 OK

application/json

{
    "status": true,
    "session_id": "cs_99a81b2c4e",
    "payment_status": "PAID",
    "reference": "FIM|CHK|2026082501509921",
    "account_number": "8091234567",
    "bank_name": "Wema Bank",
    "account_name": "FIMPAYPOINT CHECKOUT",
    "amount_expected": 5000,
    "amount_paid": 5000,
    "fee": 0,
    "net_amount": 5000,
    "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"
}

POST /api/v1/virtual-accounts

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 (Anchor)	`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;
}

Response Body 200 OK

application/json

{
    "status": true,
    "service": "CREATE_VIRTUAL_ACCOUNT",
    "merchant_id": 1001,
    "banks": [
        {
            "bankName": "Wema Bank",
            "accountNumber": "9900112233",
            "accountName": "John Doe",
            "bankCode": "035",
            "status": "ACTIVE"
        }
    ]
}

💡 Recommended Best Practice: Multi-Bank Cascading Fallback

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)

Fallback Output / Response Body 200 OK

application/json (Resolved via Fallback Bank)

{
  "status": true,
  "service": "CREATE_VIRTUAL_ACCOUNT",
  "merchant_id": 1001,
  "banks": [
    {
      "bankName": "Providus Bank",
      "accountNumber": "9900456789",
      "accountName": "John Doe",
      "bankCode": "50211",
      "status": "ACTIVE"
    }
  ]
}

GET /api/v1/virtual-accounts

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;
}

Response Body 200 OK

application/json

{
    "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"
        }
    ]
}

GET /api/v1/banks

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.

Secret API Key

Try It Response

Active Bank List

#	Bank Name	Code	Status
1	9PSB (9 Payment Service Bank)	`120001`	Active
2	Providus Bank	`50211`	Active

Code Examples & Response

curl -X GET "https://fimpaypoint.com/api/v1/banks" \
     -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/banks',
      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/banks"
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/banks",
    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/banks");
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://fimpaypoint.com/api/v1/banks")
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/banks" -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/banks");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        CURLcode res = curl_easy_perform(curl);
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }
    return 0;
}

Response Body 200 OK

application/json

{
    "status": "success",
    "banks": [
        {
            "id": 1,
            "code": "120001",
            "name": "9PSB (9 Payment Service Bank)"
        },
        {
            "id": 2,
            "code": "50211",
            "name": "Providus Bank"
        }
    ]
}

POST /api/v1/customers/update

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;
}

Response Body 200 OK

application/json

{
    "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"
    }
}

POST /api/v1/customers/delete

Delete Customer

Remove a customer account from your business profile in FimPay.

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;
}

Response Body 200 OK

application/json

{
    "status": true,
    "service": "DELETE_CUSTOMER_ACCOUNT",
    "message": "Customer deleted successfully."
}

GET /api/v1/customers/fetch

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;
}

Response Body 200 OK

application/json

{
    "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"
        }
    ]
}

POST /api/v1/verification

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;
}

Response Body 200 OK

application/json

{
    "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
}

POST /api/v1/verification

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;
}

Response Body 200 OK

application/json

{
    "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
}

POST /api/v1/verification/bvn

Fee: ₦100.00 / query

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;
}

Response Body 200 OK

application/json

{
    "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"
    }
}

POST /api/v1/verification/nin

Fee: ₦120.00 / query

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;
}

Response Body 200 OK

application/json

{
    "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"
    }
}

POST /api/v1/payout/transfer

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;
}

Response Body 200 OK

application/json

{
    "status": "success",
    "reference": "FIM|WDR|915370",
    "amount": 25000,
    "fee": 50,
    "status_message": "Transfer Queued for Instant Settlement"
}

GET /api/v1/account/balance

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;
}

Response Body 200 OK

application/json

{
    "status": true,
    "service": "ACCOUNT_BALANCE_CHECK",
    "balance": 219500.5
}

Webhooks & Signature Verification

Webhooks let FimPay 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 FimPay 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 FimPay.

⚠️ Always verify signatures Skipping signature verification exposes your application to spoofed webhook requests. Always validate the 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

FimPay sends a JSON POST body with the following structure:

application/json

{
  "event": "payment.received",
  "order": {
    "amount": "1000.00",
    "settlement_amount": 991.00,
    "fee": 9.00,
    "currency": "NGN",
    "description": "9816482569 received 1,000.00 from SENDER NAME (XXXXXX3515, Access Bank)"
  },
  "transaction": {
    "reference": "FIM|DEP|202610026711",
    "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",
    "timestamp": "2026-10-02 05:24:51"
  },
  "account_number": "9816482569",
  "customer": {
    "id": 1,
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "09052105063",
    "created_at": "2026-10-02 05:24:51"
  }
}

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.settlement_amount`	float	Net credited merchant wallet amount after fees.
`order.fee`	float	Gateway processing fee charged.
`transaction.reference`	string	Unique platform transaction reference.
`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');
$signature = $_SERVER['HTTP_FIMPAY_SIGNATURE'] ?? $_SERVER['HTTP_FIMPAY_SIGNATURE'] ?? '';
$secret = "YOUR_SECRET_KEY";

$hashkey = hash_hmac('sha512', $payload, $secret);

if ($signature === $hashkey) {
    $data = json_decode($payload, true);
    $reference = $data['transaction']['reference'];
    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'];
    const secret = process.env.FIMPAY_SECRET_KEY;
    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;
    res.status(200).json({ message: 'success' });
});

Delivery & Retry Policy

FimPay employs an automated in-flight retry schedule to ensure you never miss a payment notification due to momentary network hiccups or brief server delays:

ATTEMPT 1 Immediate

Fired synchronously on payment confirmation.

ATTEMPT 2 +3 Seconds

Retried if attempt 1 returns 5xx or times out.

ATTEMPT 3 +15 Seconds

Second retry for temporary server lag.

ATTEMPT 4 +30 Seconds

Final automatic attempt before logging failed.

💡 Early Termination: As soon as your server responds with any 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 FimPay's client from triggering a retry.
Idempotency (Double-Credit Defense): Always check if transaction.reference has 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:

Error Response Schema (4xx / 5xx)

{
  "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

HTTP Code	Summary	Description & Action
`200 OK`	Success	Request completed successfully.
`400 Bad Request`	Invalid Input / Payload	Missing required parameters, invalid JSON body, or duplicate transaction reference.
`401 Unauthorized`	Authentication Failed	Authorization header missing, expired, or invalid secret API key.
`403 Forbidden`	Permission Denied	Merchant account is inactive/unverified or calling IP is not in your security whitelist.
`404 Not Found`	Resource Missing	The requested virtual account, customer, or transaction reference was not found.
`422 Unprocessable`	Validation Failed	Bank name enquiry mismatch, invalid NUBAN, or unverified account.
`429 Too Many Req`	Rate Limit Exceeded	Request burst rate limit exceeded. Retry with exponential backoff.
`500 / 503`	Server / Gateway Error	Internal platform exception or upstream interbank network timeout.

Application Error Codes Dictionary

Error Code	Trigger Condition	Recommended Handling
`INVALID_PAYLOAD`	Required request body parameter is missing or format is malformed.	Check the parameters table for the endpoint and validate types.
`INVALID_BANK_CODE`	The bank code passed is not found or is currently deactivated.	Query `GET /api/v1/banks` to list all active bank codes.
`DUPLICATE_REFERENCE`	A transaction with the given reference ID already exists.	Generate a unique random or UUID reference for each new transaction.
`INVALID_CREDENTIALS`	Bearer token is incorrect or does not match active merchant keys.	Verify secret key under Dashboard → Settings → API Credentials.
`INSUFFICIENT_FUNDS`	Wallet balance is insufficient to cover transfer amount + fee.	Fund your merchant wallet before initiating outgoing payouts.
`ACCOUNT_NOT_FOUND`	No matching virtual account or customer could be found.	Confirm customer ID or account number before querying.
`RATE_LIMIT_EXCEEDED`	More than 60 requests per minute dispatched from this API key.	Throttle requests or batch calls where supported.
`GATEWAY_DOWNTIME`	Selected upstream banking switch is experiencing temporary downtime.	Retry in 10-30 seconds or allocate through alternative bank provider.

📦 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.0

Official WordPress / WooCommerce payment gateway. Accepts automated Dedicated Virtual Accounts, Cards, Transfers, and USSD with zero custom code.

⬇️ Download fimpay-woocommerce.zip

4-Step Quick Installation

1 Upload Plugin

In WordPress Admin, navigate to Plugins → Add New → Upload Plugin and choose the downloaded zip.

2 Activate

Click Activate Plugin to register FimPay inside WooCommerce Payment Gateways.

3 Enter API Keys

Go to WooCommerce → Settings → Payments → FimPay. Paste your Live Public & Secret keys.

4 Set Webhook

Copy the Webhook URL (/wc-api/wc_gateway_fimpay) into your FimPay Webhook Settings.

✓ Built-in Double-Credit Defense: The WooCommerce gateway automatically checks order payment status idempotently to guarantee that orders are fulfilled exactly once.