1. Introduction & Overview

The Bridgenetic API provides a comprehensive RESTful interface for integrating payment infrastructure into your applications. Our API enables you to create virtual accounts, process transactions, manage withdrawals, accept card payments via checkout, and receive real-time webhook notifications.

Base URL:

https://bridgenetic.com/api/v1

API Version: v1 (current, stable)

Protocol: HTTPS only. All API requests must be made over HTTPS. Calls made over plain HTTP will be rejected.

Data Format: All request and response bodies are JSON-encoded. Dates are returned in ISO 8601 format.

2. Authentication

The Bridgenetic API supports two authentication methods. Choose the one that best fits your integration pattern.

Method 1: Bearer Token (Sanctum)

Use Bearer token authentication for server-to-server integrations where you authenticate with your merchant credentials first.

Step 1: Obtain a token by calling the login endpoint:

POST /api/v1/auth/login

{
  "business_email": "[email protected]",
  "password": "your_password"
}

Step 2: Include the token in subsequent requests:

Authorization: Bearer 1|abc123def456ghi789jkl012mno345pqr678stu901
Content-Type: application/json
Accept: application/json

Bearer tokens are issued via Laravel Sanctum and provide full access to all authenticated API endpoints under /api/v1/.

Method 2: API Key + Signature (HMAC)

Use API Key + Signature authentication for external integrations. This method uses your API key for identification and an HMAC-SHA256 signature for request integrity verification.

Generating API Keys: After completing KYC verification, navigate to your merchant dashboard under Settings > API Keys or call the API key generation endpoint.

API Key: Used for identifying your account (passed in X-Api-Key header)
Secret Key: Used for computing the request signature (never transmitted directly)

Required Headers:

X-Api-Key: your_api_key_here
X-Signature: computed_hmac_sha256_signature
Content-Type: application/json
Accept: application/json

Computing the Signature:

The signature is computed as an HMAC-SHA256 hash of the request body using your secret key:

// PHP
$signature = hash_hmac('sha256', $requestBody, $secretKey);

// JavaScript
const crypto = require('crypto');
const signature = crypto.createHmac('sha256', secretKey).update(requestBody).digest('hex');

For GET requests with no body, sign an empty string.

Security Best Practices

Never expose your secret key in client-side code, public repositories, or logs
Rotate your API keys periodically (at least every 90 days)
Use environment variables to store keys in your application
Restrict API key permissions to only what your application needs
Configure IP whitelisting in your merchant dashboard for additional security

3. Base URL & Headers

Every request to the Bridgenetic API must include the following headers:

Header	Value	Required
`Authorization`	`Bearer {your_token}`	Yes (Bearer auth)
`X-Api-Key`	`{your_api_key}`	Yes (API Key auth)
`X-Signature`	`{hmac_sha256_signature}`	Yes (API Key auth)
`Content-Type`	`application/json`	Yes (for POST/PUT/PATCH)
`Accept`	`application/json`	Yes
`X-Idempotency-Key`	Unique string (UUID recommended)	Recommended for POST

Example Request (Bearer Token)

curl -X GET https://bridgenetic.com/api/v1/virtual-accounts \
  -H "Authorization: Bearer 1|abc123def456ghi789jkl012mno345pqr678stu901" \
  -H "Accept: application/json"

Example Request (API Key + Signature)

curl -X POST https://bridgenetic.com/api/v1/virtual-accounts/create \
  -H "X-Api-Key: your_api_key_here" \
  -H "X-Signature: computed_hmac_sha256_of_request_body" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"customer_name":"John Doe","email":"[email protected]","phone":"08012345678","narration":"John Doe"}'

4. Rate Limiting

To ensure fair usage and platform stability, API requests are rate-limited per merchant account.

Default Limit: 60 requests per minute per merchant.

Rate Limit Headers

Every API response includes rate limit information in the following headers:

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed per window (e.g., 60)
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets

Example Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1717200060

Handling 429 Responses

When you exceed the rate limit, you will receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717200060

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 30 seconds.",
    "retry_after": 30
  }
}

Implement exponential backoff in your integration to handle rate limits gracefully. Respect the Retry-After header value before sending subsequent requests.

5. Authentication Endpoints

Manage merchant authentication and session tokens.

Register

POST /api/v1/auth/register

Create a new merchant account.

Request Body

{
  "first_name": "Adebayo",
  "last_name": "Ogunlesi",
  "email": "[email protected]",
  "password": "SecureP@ss123",
  "password_confirmation": "SecureP@ss123",
  "business_name": "Ogunlesi Ventures",
  "phone": "+2348012345678"
}

Response (201 Created)

{
  "success": true,
  "message": "Registration successful. Please verify your email.",
  "data": {
    "merchant_id": "mrc_01HX7A1B2C3D4E5F6G7H8I9J0K",
    "email": "[email protected]",
    "token": "1|abc123def456ghi789jkl012mno345pqr678stu901"
  }
}

Login

POST /api/v1/auth/login

Authenticate and receive a Bearer token.

Request Body

{
  "business_email": "[email protected]",
  "password": "SecureP@ss123"
}

Response (200 OK)

{
  "status": "success",
  "data": {
    "token": "1|abc123def456ghi789jkl012mno345pqr678stu901",
    "merchant": {
      "id": "mrc_01HX7A1B2C3D4E5F6G7H8I9J0K",
      "email": "[email protected]",
      "business_name": "Ogunlesi Ventures",
      "status": "active"
    }
  }
}

Logout

POST /api/v1/auth/logout

Revoke the current Bearer token. Requires authentication.

Response (200 OK)

{
  "success": true,
  "message": "Logged out successfully"
}

Forgot Password

POST /api/v1/auth/forgot-password

Request a password reset link. An email with reset instructions will be sent to the registered address.

Request Body

{
  "email": "[email protected]"
}

Response (200 OK)

{
  "success": true,
  "message": "Password reset link sent to your email."
}

Reset Password

POST /api/v1/auth/reset-password

Reset the merchant password using the token received via email.

Request Body

{
  "email": "[email protected]",
  "token": "reset_token_from_email",
  "password": "NewSecureP@ss456",
  "password_confirmation": "NewSecureP@ss456"
}

Response (200 OK)

{
  "success": true,
  "message": "Password reset successfully."
}

6. Merchant Profile

Manage your merchant profile information.

Get Merchant Profile

GET /api/v1/merchant/profile

Retrieve the authenticated merchant's profile details.

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "mrc_01HX7A1B2C3D4E5F6G7H8I9J0K",
    "business_name": "Ogunlesi Ventures",
    "email": "[email protected]",
    "phone": "+2348012345678",
    "status": "active",
    "kyc_status": "approved",
    "available_balance": 1250000.00,
    "currency": "NGN",
    "webhook_url": "https://yourapp.com/webhooks/bridgenetic",
    "created_at": "2024-06-01T10:00:00.000000Z"
  }
}

Update Merchant Profile

PUT /api/v1/merchant/profile

Update the authenticated merchant's profile information.

Request Body

{
  "business_name": "Ogunlesi Ventures Ltd",
  "phone": "+2348012345679"
}

Response (200 OK)

{
  "success": true,
  "message": "Profile updated successfully.",
  "data": {
    "id": "mrc_01HX7A1B2C3D4E5F6G7H8I9J0K",
    "business_name": "Ogunlesi Ventures Ltd",
    "email": "[email protected]",
    "phone": "+2348012345679",
    "status": "active",
    "kyc_status": "approved",
    "available_balance": 1250000.00,
    "currency": "NGN",
    "webhook_url": "https://yourapp.com/webhooks/bridgenetic",
    "created_at": "2024-06-01T10:00:00.000000Z"
  }
}

Set Webhook URL

POST /api/v1/merchant/webhook

Configure or update the webhook URL where event notifications will be delivered.

Request Body

{
  "webhook_url": "https://yourapp.com/webhooks/bridgenetic"
}

Response (200 OK)

{
  "success": true,
  "message": "Webhook URL updated successfully.",
  "data": {
    "webhook_url": "https://yourapp.com/webhooks/bridgenetic"
  }
}

Get Balance Overview

GET /api/v1/merchant/balance

Retrieve your current wallet balance and summary.

Response (200 OK)

{
  "success": true,
  "data": {
    "available_balance": 1250000.00,
    "currency": "NGN",
    "total_deposits": 5800000.00,
    "total_withdrawals": 4550000.00,
    "pending_withdrawals": 0.00
  }
}

Get Transaction History

GET /api/v1/merchant/transactions

Retrieve transaction history with summary statistics for the authenticated merchant.

Get Virtual Account List

GET /api/v1/merchant/virtual-accounts

Retrieve all virtual accounts with summary data for the authenticated merchant.

Get Withdrawal List

GET /api/v1/merchant/withdrawals

Retrieve withdrawal history for the authenticated merchant.

Get Settlement Logs

GET /api/v1/merchant/settlements

Retrieve settlement history showing when funds were settled to your account.

Get Webhook Delivery Logs

GET /api/v1/merchant/webhook-deliveries

Retrieve a log of all webhook delivery attempts, including successes and failures.

Get API Usage

GET /api/v1/merchant/api-usage

Retrieve API usage statistics for your merchant account, including request counts and rate limit usage.

Get Fee Breakdown

GET /api/v1/merchant/fee-breakdown

Retrieve a breakdown of fees charged on your transactions.

Get Payment Analytics

GET /api/v1/merchant/analytics

Retrieve payment analytics including volume trends, payment method breakdown, and success rates.

7. API Keys

Generate and manage API keys for authenticating external integrations.

Generate API Key

POST /api/v1/api-keys/generate

Generate a new API key pair. The secret key is only shown once at creation time — store it securely.

Response (201 Created)

{
  "success": true,
  "message": "API key generated successfully. Store your secret key securely — it will not be shown again.",
  "data": {
    "api_key": "gw_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "secret_key": "gw_secret_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0",
    "created_at": "2024-06-15T10:00:00.000000Z"
  }
}

Important: The secret_key is only returned once during generation. If you lose it, you must generate a new key pair.

Regenerate API Key

POST /api/v1/api-keys/regenerate

Regenerate your API key pair. This invalidates the previous key immediately.

Response (201 Created)

{
  "success": true,
  "message": "API key regenerated successfully. Store your new secret key securely.",
  "data": {
    "api_key": "gw_live_q1w2e3r4t5y6u7i8o9p0a1s2d3f4g5h6",
    "secret_key": "gw_secret_z1x2c3v4b5n6m7k8j9h0g1f2d3s4a5p6o7i8u9y0",
    "created_at": "2024-08-20T14:00:00.000000Z"
  }
}

8. Customers API

Customers represent the end-users who receive virtual accounts and make payments. You can create and manage customer records to track payment activity per individual.

Create a Customer

POST /api/v1/customers/create

Create a new customer record linked to your merchant account.

Request Body

{
  "customer_name": "Adebayo Ogunlesi",
  "customer_email": "[email protected]",
  "customer_phone": "+2348012345678"
}

Required Fields

Field	Type	Description
`customer_name`	string	Full name of the customer (required)
`customer_email`	string	Valid email address (required)
`customer_phone`	string	Phone number (required)

Response (201 Created)

{
  "success": true,
  "message": "Customer created successfully.",
  "data": {
    "id": "cust_01HX7K9M2N3P4Q5R",
    "customer_name": "Adebayo Ogunlesi",
    "customer_email": "[email protected]",
    "customer_phone": "+2348012345678",
    "created_at": "2024-06-15T10:00:00.000000Z"
  }
}

List Customers

GET /api/v1/customers

Retrieves a paginated list of all customers for your merchant account.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 15, max: 100)
`search`	string	Search by name, email, or phone

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "cust_01HX7K9M2N3P4Q5R",
      "customer_name": "Adebayo Ogunlesi",
      "customer_email": "[email protected]",
      "customer_phone": "+2348012345678",
      "created_at": "2024-06-15T10:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  }
}

Get a Customer

GET /api/v1/customers/{id}

Retrieves details of a specific customer.

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "cust_01HX7K9M2N3P4Q5R",
    "customer_name": "Adebayo Ogunlesi",
    "customer_email": "[email protected]",
    "customer_phone": "+2348012345678",
    "virtual_accounts_count": 2,
    "total_deposits": 850000.00,
    "created_at": "2024-06-15T10:00:00.000000Z"
  }
}

9. Virtual Accounts API

Virtual accounts are dedicated bank account numbers provisioned for your customers to receive payments via bank transfer. When a customer transfers money to their assigned virtual account, the funds are automatically credited to your merchant wallet and a webhook notification is sent.

Create a Virtual Account

POST /api/v1/virtual-accounts/create

Creates a new virtual account. Simply provide the customer's name, email, phone, and a narration — the system handles everything else internally. A dedicated bank account number is provisioned and returned immediately.

Request Body

{
  "customer_name": "John Doe",
  "email": "[email protected]",
  "phone": "08012345678",
  "narration": "John Doe"
}

Required Fields

Field	Type	Description
`customer_name`	string	Full name of the customer (required, max 255 chars)
`email`	string	Valid email address of the customer (required)
`phone`	string	Customer phone number (required, max 20 chars)
`narration`	string	Account narration — this becomes the account name displayed on the virtual account (required, 3-50 characters)

How It Works

Submit a POST request with customer_name, email, phone, and narration
The system validates the request fields and narration rules
A virtual account is provisioned through the banking infrastructure
The account number, bank name, and account name are returned
The virtual account is immediately active and can receive bank transfers
When a deposit is received, a deposit.success webhook event is dispatched to your configured URL

Narration Rules

Length: Between 3 and 50 characters
Allowed characters: Alphanumeric characters, spaces, hyphens (-), and apostrophes (')
Pattern: /^[a-zA-Z0-9\s\-']{3,50}$/
Blacklisted words: The narration must not contain any blacklisted words configured by the platform administrator

Response (201 Created)

{
  "status": "success",
  "data": {
    "account_number": "9907083132",
    "bank_name": "PalmPay",
    "account_name": "John Doe"
  }
}

Error Response — Validation Failed (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "narration": ["The narration must be between 3 and 50 characters."]
    }
  }
}

Error Response — KYC Required (422)

{
  "status": false,
  "error_category": "account_creation_failed",
  "message": "KYC verification required. Please complete your merchant verification."
}

List Virtual Accounts

GET /api/v1/virtual-accounts

Retrieves a paginated list of all virtual accounts for your merchant.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 15, max: 100)
`status`	string	Filter by status: active, inactive, closed
`search`	string	Search by account number or customer name

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "va_01HX7K9M2N3P4Q5R6S7T8U9V0W",
      "account_number": "9907083132",
      "account_name": "John Doe",
      "bank_name": "Wema Bank",
      "status": "active",
      "currency": "NGN",
      "created_at": "2024-06-15T10:30:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}

Get a Virtual Account

GET /api/v1/virtual-accounts/{id}

Retrieves details of a specific virtual account.

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "va_01HX7K9M2N3P4Q5R6S7T8U9V0W",
    "account_number": "9907083132",
    "account_name": "John Doe",
    "bank_name": "Wema Bank",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "status": "active",
    "currency": "NGN",
    "total_received": 1250000.00,
    "transaction_count": 8,
    "created_at": "2024-06-15T10:30:00.000000Z",
    "expires_at": null
  }
}

10. Transactions API

Transactions represent money movement through your virtual accounts. Each deposit received or withdrawal processed generates a transaction record.

List Transactions

GET /api/v1/transactions

Retrieves a paginated list of transactions with optional filters.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 15, max: 100)
`status`	string	Filter: successful, pending, failed, reversed
`type`	string	Filter: deposit, withdrawal
`from`	date	Start date (YYYY-MM-DD)
`to`	date	End date (YYYY-MM-DD)
`min_amount`	numeric	Minimum amount filter
`max_amount`	numeric	Maximum amount filter
`reference`	string	Search by transaction reference

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "txn_01HX8A2B3C4D5E6F7G8H9I0J1K",
      "reference": "BRG-TXN-20240615-ABC123",
      "type": "deposit",
      "amount": 150000.00,
      "fee": 750.00,
      "net_amount": 149250.00,
      "currency": "NGN",
      "status": "successful",
      "description": "Transfer from John Doe",
      "sender_name": "JOHN DOE",
      "sender_bank": "GTBank",
      "sender_account": "012****890",
      "virtual_account_number": "9907083132",
      "session_id": "000015240615120000000001234567",
      "created_at": "2024-06-15T12:00:00.000000Z",
      "settled_at": "2024-06-15T12:00:05.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 12,
    "per_page": 15,
    "total": 178
  }
}

Get a Transaction by Reference

GET /api/v1/transactions/{ref}

Retrieves a specific transaction by its unique reference.

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "txn_01HX8A2B3C4D5E6F7G8H9I0J1K",
    "reference": "BRG-TXN-20240615-ABC123",
    "type": "deposit",
    "amount": 150000.00,
    "fee": 750.00,
    "net_amount": 149250.00,
    "currency": "NGN",
    "status": "successful",
    "description": "Transfer from John Doe",
    "sender_name": "JOHN DOE",
    "sender_bank": "GTBank",
    "sender_account": "0123456890",
    "virtual_account_number": "9907083132",
    "session_id": "000015240615120000000001234567",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "settled_at": "2024-06-15T12:00:05.000000Z"
  }
}

Transaction Status Values

Status	Description
`successful`	Transaction completed and funds credited to wallet
`pending`	Transaction received but awaiting confirmation
`failed`	Transaction could not be processed
`reversed`	Transaction was reversed after initial success

11. Withdrawals API

Withdrawals allow you to transfer funds from your merchant wallet to any Nigerian bank account. The system handles bank account verification, fee calculation, and transfer processing.

Create a Withdrawal

POST /api/v1/withdrawals/create

Request Body

{
  "amount": 500000.00,
  "bank_code": "058",
  "account_number": "0123456789",
  "account_name": "Emeka Okafor",
  "narration": "Vendor payment - June 2024",
  "reference": "WDR-2024-06-001"
}

Required Fields

Field	Type	Description
`amount`	numeric	Amount to transfer in NGN (minimum: 100.00)
`bank_code`	string	Destination bank code (from bank list endpoint)
`account_number`	string	10-digit destination account number
`account_name`	string	Name on the destination account
`narration`	string	Transfer description/narration (required)
`reference`	string	Your unique reference for this withdrawal (optional, auto-generated if omitted)

Withdrawal Flow

Submit a POST request with the withdrawal details
The system validates the request, verifies sufficient wallet balance (amount + fee), and checks for duplicate references
The withdrawal fee is calculated and the total debit (amount + fee) is deducted from your wallet
The transfer is initiated and enters processing status
Upon successful delivery, the status transitions to completed and a withdrawal.success webhook is sent
If the transfer fails, the status transitions to failed, a withdrawal.failed webhook is sent, and the deducted amount is reversed to your wallet

Fee Deduction

Withdrawal fees are deducted from your wallet balance at the time of initiation:

total_debit = amount + fee

If the withdrawal fails, the full total_debit amount is reversed back to your wallet.

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "wdr_01HXA4C5D6E7F8G9H0I1J2K3L4",
    "reference": "WDR-2024-06-001",
    "amount": 500000.00,
    "fee": 50.00,
    "total_debit": 500050.00,
    "currency": "NGN",
    "status": "processing",
    "bank_code": "058",
    "bank_name": "GTBank",
    "account_number": "0123456789",
    "account_name": "Emeka Okafor",
    "narration": "Vendor payment - June 2024",
    "created_at": "2024-06-15T16:00:00.000000Z",
    "completed_at": null
  }
}

Withdrawal Status Lifecycle

Status	Description
`processing`	Withdrawal initiated and being processed by the bank
`completed`	Funds successfully transferred to recipient account
`failed`	Transfer failed (invalid account, bank error, etc.) — funds reversed

List Withdrawals

GET /api/v1/withdrawals

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 15, max: 100)
`status`	string	Filter: processing, completed, failed
`from`	date	Start date (YYYY-MM-DD)
`to`	date	End date (YYYY-MM-DD)

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "wdr_01HXA4C5D6E7F8G9H0I1J2K3L4",
      "reference": "WDR-2024-06-001",
      "amount": 500000.00,
      "fee": 50.00,
      "currency": "NGN",
      "status": "completed",
      "bank_name": "GTBank",
      "account_number": "0123456789",
      "account_name": "Emeka Okafor",
      "created_at": "2024-06-15T16:00:00.000000Z",
      "completed_at": "2024-06-15T16:02:30.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 15,
    "total": 56
  }
}

12. Hosted Checkout

The Bridgenetic Checkout system allows merchants to accept payments via bank transfer, USSD, OPay wallet, and direct bank debit through a professional, branded checkout experience. Customers never leave your website — the checkout opens as a modal overlay or can be used via redirect.

Integration Methods

Bridgenetic offers three integration methods:

Inline Mode (Recommended): Checkout opens as a modal overlay on your page. Customer stays on your site.
Popup Mode: Checkout opens in a new browser window.
Redirect Mode: Customer is redirected to the Bridgenetic checkout page.

Quick Start — Inline Checkout (Recommended)

Add the SDK script to your page and call BridgeneticCheckout.open():

<script src="https://bridgenetic.com/sdk/checkout.v1.js"></script>
<script>
  document.getElementById('pay-btn').addEventListener('click', function() {
    BridgeneticCheckout.open({
      public_key: 'gw_live_xxxxxxxxxxxxx',
      amount: 5000,
      currency: 'NGN',
      email: '[email protected]',
      customer_name: 'John Doe',
      reference: 'ORDER-12345',
      callback: function(data) {
        // Payment successful!
        // data = { reference: 'BGN_xxx', amount: 5000, status: 'successful' }
        console.log('Payment complete:', data.reference);
        // Verify on your server before fulfilling order
      },
      onClose: function() {
        // Customer closed the checkout without completing payment
        console.log('Checkout closed');
      },
      onError: function(error) {
        console.error('Checkout error:', error);
      }
    });
  });
</script>

Configuration Options

Parameter	Type	Required	Description
`public_key`	string	Yes	Your API key (gw_live_xxx)
`amount`	number	Yes	Amount to charge (in major currency unit)
`currency`	string	Yes	Currency code (e.g. "NGN")
`email`	string	Yes	Customer email address
`mode`	string	No	"inline" (default), "popup", or "redirect"
`reference`	string	No	Unique transaction reference (auto-generated if omitted)
`customer_name`	string	No	Customer full name
`callback_url`	string	No	Redirect URL after payment (redirect mode)
`callback`	function	No	Success callback (inline/popup mode)
`onClose`	function	No	Called when customer closes checkout
`onError`	function	No	Called on initialization error
`metadata`	object	No	Custom data attached to the transaction

Server-Side: Initialize Checkout Session

For server-to-server integrations, create a checkout session via API:

POST /api/v1/checkout/initialize

Headers:
  X-Api-Key: gw_live_xxxxxxxxxxxxx
  Content-Type: application/json

Body:
{
  "amount": 5000,
  "currency": "NGN",
  "customer_email": "[email protected]",
  "customer_name": "John Doe",
  "transaction_reference": "ORDER-12345",
  "redirect_url": "https://yoursite.com/payment-complete",
  "metadata": { "order_id": 123 }
}

Response:

{
  "status": true,
  "message": "Checkout session created",
  "data": {
    "reference": "BGN_a1qv4dn9VXfrTEKO3bgZ",
    "checkout_url": "https://bridgenetic.com/pay/BGN_a1qv4dn9VXfrTEKO3bgZ",
    "expires_at": "2025-01-15T12:30:00+01:00"
  }
}

The checkout_url can be used to redirect the customer, or passed to the SDK.

Verify Payment

After receiving the success callback, always verify the payment on your server:

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

Headers:
  X-Api-Key: gw_live_xxxxxxxxxxxxx
  X-Signature: {hmac_sha256_signature}

Response:

{
  "status": true,
  "message": "Payment session retrieved",
  "data": {
    "reference": "BGN_a1qv4dn9VXfrTEKO3bgZ",
    "status": "successful",
    "amount": "5000.00",
    "currency": "NGN",
    "payment_method": "bank_transfer",
    "paid_at": "2025-01-15T12:05:30+01:00",
    "transaction_reference": "ORDER-12345"
  }
}

Checkout Webhook Notification

When a checkout payment is completed (via any payment method), Bridgenetic sends a webhook to your registered URL:

{
  "event": "checkout.success",
  "data": {
    "reference": "BGN_a1qv4dn9VXfrTEKO3bgZ",
    "transaction_reference": "ORDER-12345",
    "amount": "5000.00",
    "currency": "NGN",
    "fee": "85.00",
    "net_amount": "4915.00",
    "payment_method": "bank_transfer",
    "customer_email": "[email protected]",
    "paid_at": "2025-01-15T12:05:30+01:00",
    "metadata": { "order_id": 123 }
  }
}

Payment Methods Supported

Bank Transfer: Pay via bank transfer to a generated temporary account
USSD: Pay by dialing a generated USSD code from supported banks
OPay: Pay directly from OPay wallet (redirect-based authorization)
Bank Debit: Direct debit from customer's Nigerian bank account (redirect-based authorization)

13. Payment Links

Create shareable payment links that customers can use to make payments without any integration. Perfect for invoices, subscriptions, and one-time payments.

Create Payment Link (API)

POST /api/v1/payment-links/create

Headers:
  X-Api-Key: gw_live_xxxxxxxxxxxxx
  X-Signature: {hmac_sha256_signature}
  Content-Type: application/json

Body:
{
  "title": "Monthly Subscription",
  "description": "Pay for your monthly plan",
  "amount": 5000,
  "currency": "NGN",
  "usage_limit": 100,
  "expires_at": "2025-12-31T23:59:59"
}

Note: Omit amount to create a dynamic link where the customer enters their own amount.

Response:

{
  "status": true,
  "message": "Payment link created",
  "data": {
    "reference": "PL_Yn4y1qS95rVeSOHZWlZb",
    "link_url": "https://bridgenetic.com/pay/link/PL_Yn4y1qS95rVeSOHZWlZb",
    "title": "Monthly Subscription",
    "amount": "5000.00"
  }
}

List Payment Links

GET /api/v1/payment-links

Headers:
  X-Api-Key: gw_live_xxxxxxxxxxxxx
  X-Signature: {hmac_sha256_signature}

Payment Link Features

Fixed Amount: Set a specific amount customers must pay
Dynamic Amount: Let customers enter any amount (omit amount field)
Usage Limits: Limit how many times a link can be used
Expiration: Set an expiry date for the link
Dashboard Management: Create and manage links from your merchant dashboard

14. Webhooks

Webhooks allow you to receive real-time HTTP POST notifications when events occur in your Bridgenetic account. Configure your webhook URL via the API (POST /api/v1/merchant/webhook) or in the merchant dashboard under Settings > Webhooks.

Event Types

Event	Description
`deposit.success`	A payment was successfully received and credited to your wallet
`withdrawal.success`	A withdrawal was successfully completed
`withdrawal.failed`	A withdrawal attempt failed (funds reversed to wallet)
`checkout.success`	A checkout payment was successfully completed

Webhook Payload Format

All webhook payloads follow this structure with three top-level fields: event, timestamp, and data.

deposit.success Payload

{
  "event": "deposit.success",
  "timestamp": "2024-06-15T12:00:05.000000Z",
  "data": {
    "reference": "BRG-TXN-20240615-ABC123",
    "amount": 150000.00,
    "fee": 750.00,
    "net_amount": 149250.00,
    "currency": "NGN",
    "status": "successful",
    "payer_name": "JOHN DOE",
    "payer_bank": "GTBank",
    "account_number": "9907083132",
    "customer_id": "cust_01HX7K9M2N3P",
    "timestamp": "2024-06-15T12:00:00.000000Z"
  }
}

withdrawal.success Payload

{
  "event": "withdrawal.success",
  "timestamp": "2024-06-15T16:02:30.000000Z",
  "data": {
    "transaction_id": "wdr_01HXA4C5D6E7F8G9H0I1J2K3L4",
    "reference": "WDR-2024-06-001",
    "type": "withdrawal",
    "amount": 500000.00,
    "fee": 50.00,
    "currency": "NGN",
    "status": "completed",
    "bank_name": "GTBank",
    "account_number": "0123456789",
    "account_name": "Emeka Okafor",
    "narration": "Vendor payment - June 2024",
    "created_at": "2024-06-15T16:00:00.000000Z",
    "completed_at": "2024-06-15T16:02:30.000000Z"
  }
}

withdrawal.failed Payload

{
  "event": "withdrawal.failed",
  "timestamp": "2024-06-15T16:01:15.000000Z",
  "data": {
    "transaction_id": "wdr_01HXA4C5D6E7F8G9H0I1J2K3L4",
    "reference": "WDR-2024-06-002",
    "type": "withdrawal",
    "amount": 250000.00,
    "fee": 50.00,
    "currency": "NGN",
    "status": "failed",
    "bank_name": "Access Bank",
    "account_number": "9876543210",
    "account_name": "Invalid Account",
    "narration": "Salary payment",
    "failure_reason": "Invalid account number",
    "created_at": "2024-06-15T16:00:00.000000Z",
    "failed_at": "2024-06-15T16:01:15.000000Z"
  }
}

Webhook Signature Verification

Every webhook request includes a signature in the X-Bridgenetic-Signature header. This signature is computed as an HMAC-SHA512 hash of the raw request body using your webhook secret. You must verify this signature to ensure the webhook is authentic and has not been tampered with.

Your webhook secret can be found in the merchant dashboard under Settings > Webhooks.

PHP Verification Example

<?php
// Get the raw request body (do NOT parse it first)
$payload = file_get_contents('php://input');

// Get the signature from the request header
$signature = $_SERVER['HTTP_X_BRIDGENETIC_SIGNATURE'] ?? '';

// Your secret key (shown once when you generated your API keys)
$secret = 'your_secret_key';

// Compute the expected signature using HMAC-SHA512
$expected = hash_hmac('sha512', $payload, $secret);

// Use timing-safe comparison to prevent timing attacks
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Signature is valid - process the webhook
$event = json_decode($payload, true);

if ($event['event'] === 'deposit.success') {
    $data = $event['data'];
    $reference = $data['reference'];
    $amount = $data['amount'];
    // Credit user, fulfill order, etc.
}

http_response_code(200);
echo json_encode(['status' => 'received']);

JavaScript (Node.js) Verification Example

const crypto = require('crypto');
const express = require('express');
const app = express();

// Use raw body for signature verification
app.post('/webhooks/bridgenetic', express.raw({ type: 'application/json' }), (req, res) => {
  const payload = req.body.toString();
  const signature = req.headers['x-bridgenetic-signature'] || '';
  const secret = process.env.BRIDGENETIC_WEBHOOK_SECRET;

  // Compute the expected signature using HMAC-SHA512
  const expectedSignature = crypto
    .createHmac('sha512', secret)
    .update(payload)
    .digest('hex');

  // Use timing-safe comparison to prevent timing attacks
  const signatureBuffer = Buffer.from(signature, 'hex');
  const expectedBuffer = Buffer.from(expectedSignature, 'hex');

  if (signatureBuffer.length !== expectedBuffer.length ||
      !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Signature is valid - process the webhook
  const event = JSON.parse(payload);

  switch (event.event) {
    case 'deposit.success':
      // Handle successful deposit
      const { reference, amount } = event.data;
      // Update your records...
      break;

    case 'withdrawal.success':
      // Handle successful withdrawal
      break;

    case 'withdrawal.failed':
      // Handle failed withdrawal
      const { failure_reason } = event.data;
      // Notify your team...
      break;
  }

  res.status(200).json({ received: true });
});

Retry Policy

If your endpoint does not return a 2xx response, Bridgenetic will retry the webhook delivery up to 5 times with increasing intervals:

Retry 1: After 1 minute
Retry 2: After 5 minutes
Retry 3: After 15 minutes
Retry 4: After 30 minutes

After all retries are exhausted, the webhook is marked as permanently failed and you'll receive an email notification. You can manually retry failed webhooks from your dashboard.

Best Practices:

Return a 200 OK response immediately, then process the event asynchronously
Implement idempotency — the same event may be delivered more than once
Use the event field to route to the appropriate handler
Always verify the signature before processing any webhook data
Log all received webhooks for debugging purposes

15. Error Handling

The Bridgenetic API uses conventional HTTP status codes to indicate the success or failure of requests. All error responses follow a consistent format.

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "amount": ["The amount field is required."],
      "bank_code": ["The selected bank code is invalid."]
    }
  }
}

HTTP Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource successfully created
`400`	Bad Request	Invalid request format or parameters
`401`	Unauthorized	Missing or invalid authentication credentials
`403`	Forbidden	Valid credentials but insufficient permissions
`404`	Not Found	Requested resource does not exist
`422`	Unprocessable Entity	Validation errors in request body
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Something went wrong on our end
`503`	Service Unavailable	Service temporarily unavailable (try again later)

Error Codes Reference

Error Code	HTTP Status	Description
`INVALID_API_KEY`	401	The provided API key is invalid, expired, or has been revoked. Generate a new key from your merchant dashboard.
`INVALID_SIGNATURE`	401	The HMAC signature does not match. Verify you are signing the correct request body with the correct secret key.
`VALIDATION_ERROR`	422	Request body failed validation rules. Check the `details` field for specific field errors.
`INSUFFICIENT_BALANCE`	422	Your wallet balance is too low to cover the withdrawal amount plus fees.
`DUPLICATE_REFERENCE`	409	A transaction with this reference already exists. Each reference must be unique across your account.
`INVALID_BANK_ACCOUNT`	422	The bank account could not be verified. Check the account number and bank code are correct.
`RATE_LIMIT_EXCEEDED`	429	Too many requests in the current window. Respect the `Retry-After` header and implement backoff.
`RESOURCE_NOT_FOUND`	404	The requested resource does not exist or does not belong to your account.
`KYC_REQUIRED`	403	Your merchant account has not completed KYC verification. Complete verification in the dashboard.
`ACCOUNT_SUSPENDED`	403	Your merchant account has been suspended. Contact support for assistance.
`NARRATION_BLACKLISTED`	422	The narration contains a blacklisted word or phrase.

Error Response Examples

Invalid API Key (401):

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Insufficient Balance (422):

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Required: NGN 500,050.00, Available: NGN 250,000.00"
  }
}

Duplicate Reference (409):

{
  "success": false,
  "error": {
    "code": "DUPLICATE_REFERENCE",
    "message": "A transaction with reference 'WDR-2024-06-001' already exists."
  }
}

Resource Not Found (404):

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

16. SDKs & Libraries

Official client libraries to accelerate your integration with Bridgenetic.

PHP SDK

Installation:

composer require bridgenetic/php-sdk

Usage:

<?php
use Bridgenetic\BridgeneticClient;

$client = new BridgeneticClient('your_api_key', 'your_secret_key');

// Create a virtual account
$account = $client->virtualAccounts->create([
    'customer_name' => 'John Doe',
    'email' => '[email protected]',
    'phone' => '08012345678',
    'narration' => 'John Doe',
]);

echo $account->account_number; // "9907083132"
echo $account->bank_name;      // "Wema Bank"

// List transactions
$transactions = $client->transactions->list([
    'status' => 'successful',
    'from' => '2024-06-01',
    'per_page' => 50,
]);

// Create a withdrawal
$withdrawal = $client->withdrawals->create([
    'amount' => 500000.00,
    'bank_code' => '058',
    'account_number' => '0123456789',
    'account_name' => 'Emeka Okafor',
    'narration' => 'Vendor payment',
]);

Node.js SDK

Installation:

npm install @bridgenetic/node-sdk

Usage:

const Bridgenetic = require('@bridgenetic/node-sdk');

const client = new Bridgenetic({
  apiKey: 'your_api_key',
  secretKey: 'your_secret_key',
});

// Create a virtual account
const account = await client.virtualAccounts.create({
  customerName: 'John Doe',
  email: '[email protected]',
  phone: '08012345678',
  narration: 'John Doe',
});

console.log(account.accountNumber); // "9907083132"
console.log(account.bankName);      // "Wema Bank"

// List transactions with filters
const transactions = await client.transactions.list({
  status: 'successful',
  from: '2024-06-01',
  perPage: 50,
});

// Create a withdrawal
const withdrawal = await client.withdrawals.create({
  amount: 500000.00,
  bankCode: '058',
  accountNumber: '0123456789',
  accountName: 'Emeka Okafor',
  narration: 'Vendor payment',
});

Python SDK

Installation:

pip install bridgenetic

Usage:

from bridgenetic import BridgeneticClient

client = BridgeneticClient(
    api_key="your_api_key",
    secret_key="your_secret_key",
)

# Create a virtual account
account = client.virtual_accounts.create(
    customer_name="John Doe",
    email="[email protected]",
    phone="08012345678",
    narration="John Doe",
)

print(account.account_number)  # "9907083132"
print(account.bank_name)       # "Wema Bank"

# List transactions
transactions = client.transactions.list(
    status="successful",
    from_date="2024-06-01",
    per_page=50,
)

# Create a withdrawal
withdrawal = client.withdrawals.create(
    amount=500000.00,
    bank_code="058",
    account_number="0123456789",
    account_name="Emeka Okafor",
    narration="Vendor payment",
)

17. Bill Payments API

The Bill Payments API allows merchants to purchase airtime, data bundles, electricity tokens, cable TV subscriptions, internet services, and other bill payments for their customers. Successful purchases earn cashback rewards (if enabled by the platform admin).

Supported Categories

Category	ID	Description
Airtime	`airtime`	Mobile airtime top-up (MTN, Airtel, Glo, 9Mobile)
Internet Data	`data`	Mobile data bundles (MTN, Airtel, Glo, 9Mobile)
Electricity	`electricity`	Prepaid/postpaid meter token purchase (all DISCOs)
Cable TV	`cabletv`	DSTV, GOtv, Startimes subscriptions
Internet	`internet`	Smile, Swift, and other ISP services
Other	`other`	Government payments, religious, schools, transport, etc.

Get Bill Categories

GET /api/v1/bills/categories

Returns the list of available bill payment categories with item counts.

Response (200 OK)

{
  "status": true,
  "message": "Bill categories retrieved",
  "data": [
    { "id": "airtime", "name": "Airtime", "icon": "fa-mobile-alt", "count": 4 },
    { "id": "data", "name": "Internet Data", "icon": "fa-wifi", "count": 62 },
    { "id": "electricity", "name": "Electricity", "icon": "fa-bolt", "count": 24 },
    { "id": "cabletv", "name": "Cable TV", "icon": "fa-tv", "count": 75 },
    { "id": "internet", "name": "Internet", "icon": "fa-globe", "count": 21 },
    { "id": "other", "name": "Other", "icon": "fa-ellipsis-h", "count": 79 }
  ]
}

Get Billers / Providers

GET /api/v1/bills/billers?category={category_id}

Returns the list of billers/providers for a specific category.

Query Parameters

Parameter	Type	Required	Description
`category`	string	Yes	Category ID: airtime, data, electricity, cabletv, internet, other

Response (200 OK) — Example for `data`

{
  "status": true,
  "message": "Billers retrieved",
  "data": [
    { "id": 1, "name": "MTN Data Bundle", "biller_code": "BIL108", "item_code": "MD141", "plan_count": 38 },
    { "id": 2, "name": "GLO Data Bundle", "biller_code": "BIL109", "item_code": "MD147", "plan_count": 9 },
    { "id": 3, "name": "AIRTEL Data Bundle", "biller_code": "BIL110", "item_code": "MD135", "plan_count": 11 },
    { "id": 4, "name": "9MOBILE Data Bundle", "biller_code": "BIL111", "item_code": "MD152", "plan_count": 4 }
  ]
}

Get Bill Items / Plans

GET /api/v1/bills/items?biller_code={biller_code}

Returns all available plans/items for a specific biller. Use this to show available data plans, TV packages, etc.

Query Parameters

Parameter	Type	Required	Description
`biller_code`	string	Yes	The biller_code from the billers endpoint (e.g., BIL108)

Response (200 OK)

{
  "status": true,
  "message": "Bill items fetched from catalog",
  "data": [
    {
      "id": 1,
      "biller_code": "BIL108",
      "name": "MTN 1GB data purchase (1 day)",
      "biller_name": "MTN 1GB data purchase (1 day)",
      "item_code": "MD489",
      "short_name": "MTN 1GB data purchase (1 day)",
      "amount": 500,
      "fee": 0,
      "label_name": "Mobile Number",
      "is_airtime": false,
      "is_resolvable": false
    }
  ]
}

Verify Customer

POST /api/v1/bills/verify

Validate a customer's identifier before making a bill purchase. Required for electricity (meter number) and cable TV (smartcard/IUC number). Check is_resolvable from the items endpoint to know if verification is needed.

Request Body

{
  "biller_identifier": "BIL112",
  "customer_identifier": "45702025995",
  "item_code": "UB157"
}

Fields

Field	Type	Required	Description
`biller_identifier`	string	Yes	The biller_code (e.g., BIL112 for EKEDC)
`customer_identifier`	string	Yes	Meter number, smartcard number, phone, etc.
`item_code`	string	No	The item_code for the specific service

Response (200 OK)

{
  "status": true,
  "message": "Validated",
  "data": {
    "customer_name": "JOHN DOE",
    "customer": "45702025995",
    "response_code": "00"
  }
}

Purchase Bill

POST /api/v1/bills/purchase

Purchase a bill for a customer. Debits from your wallet balance. On success, you receive cashback (if enabled).

Request Body

{
  "category": "data",
  "biller_identifier": "BIL108",
  "biller_name": "MTN Data Bundle",
  "item_code": "MD489",
  "customer_identifier": "08012345678",
  "amount": 500,
  "phone": "08012345678"
}

Required Fields

Field	Type	Required	Description
`category`	string	Yes	Bill category (airtime, data, electricity, cabletv, internet, other)
`biller_identifier`	string	Yes	The biller_code from billers/items endpoint
`item_code`	string	Yes*	The item_code from items endpoint. *Required for: data, electricity, cabletv, internet, other. NOT required for airtime.
`customer_identifier`	string	Yes	Phone number, meter number, decoder number, etc.
`amount`	numeric	Yes	Amount in Naira (minimum ₦50). Must match catalog price for fixed-price items.
`phone`	string	Yes	Customer phone number
`biller_name`	string	No	Human-readable biller name
`customer_name`	string	No	Customer name (from verify endpoint)

Response (201 Created)

{
  "status": true,
  "message": "Bill payment successful",
  "data": {
    "reference": "BILL-A1B2C3D4E5F6",
    "pin": null,
    "status": "successful",
    "cashback_amount": 15.00
  }
}

Notes:

For airtime, set category to "airtime" and use the biller_identifier from the billers endpoint. item_code is optional.
For fixed-price items (data, cable), the amount must exactly match the catalog price or the request will be rejected.
For variable-price items (airtime, electricity), you can specify any valid amount.
cashback_amount shows how much was credited back to your wallet as a reward.

Bill Payment Flow

The recommended flow for integrating bill payments:

Get categories → GET /api/v1/bills/categories
Get billers for category → GET /api/v1/bills/billers?category=data
Get plans for biller → GET /api/v1/bills/items?biller_code=BIL108
Verify customer (if is_resolvable is true) → POST /api/v1/bills/verify
Purchase bill → POST /api/v1/bills/purchase
Check status (for tokens/PINs) → GET /api/v1/bills/{reference}/status

Get Bill History

GET /api/v1/bills/history

Returns a paginated list of your bill payment transactions.

Query Parameters

Parameter	Type	Description
`category`	string	Filter by category (optional)
`status`	string	Filter by status: successful, pending, failed (optional)

Check Bill Status

GET /api/v1/bills/{reference}/status

Check the status of a bill purchase. Use this to retrieve tokens/PINs for electricity purchases. You can only check the status of your own transactions.

Response (200 OK)

{
  "status": true,
  "message": "Status fetched",
  "data": {
    "status": "successful",
    "amount": 5000,
    "pin": "TOKEN1147XXXX5707123"
  }
}

Bill Payment Webhook Events

After a bill purchase is processed, a webhook is sent to your configured webhook URL with one of these events:

Event	Description
`bill.airtime.success`	Airtime purchase succeeded
`bill.airtime.failed`	Airtime purchase failed
`bill.data.success`	Data purchase succeeded
`bill.data.failed`	Data purchase failed
`bill.electricity.success`	Electricity payment succeeded
`bill.electricity.failed`	Electricity payment failed
`bill.cabletv.success`	Cable TV subscription succeeded
`bill.cabletv.failed`	Cable TV subscription failed
`bill.internet.success`	Internet service payment succeeded
`bill.other.success`	Other bill payment succeeded

Webhook Payload (Success)

{
  "event": "bill.airtime.success",
  "data": {
    "reference": "BILL-A1B2C3D4E5F6",
    "category": "airtime",
    "biller_identifier": "BIL099",
    "biller_name": "MTN VTU",
    "customer_identifier": "08012345678",
    "amount": 500.00,
    "cashback_amount": 12.50,
    "status": "successful",
    "phone": "08012345678",
    "processed_at": "2024-01-15T10:30:00+01:00",
    "network": "MTN"
  }
}

Webhook Payload (Failed)

{
  "event": "bill.data.failed",
  "data": {
    "reference": "BILL-X1Y2Z3A4B5C6",
    "category": "data",
    "biller_identifier": "BIL108",
    "biller_name": "MTN Data Bundle",
    "customer_identifier": "08098765432",
    "amount": 1000.00,
    "cashback_amount": 0,
    "status": "failed",
    "phone": "08098765432",
    "failure_reason": "Insufficient float on provider"
  }
}

Cashback

Successful bill purchases may earn cashback rewards credited instantly to your wallet. The cashback amount is shown in:

The purchase API response (data.cashback_amount)
The webhook payload (data.cashback_amount)
Your wallet ledger as a "cashback" entry

Cashback rates are configured by the platform administrator per category and may vary.

18. WHMCS Integration

Bridgenetic provides an official WHMCS module that enables two features for your WHMCS installation:

Payment Gateway — Customers pay invoices via Bridgenetic Checkout (Bank Transfer, USSD, OPay, Bank Debit)
Account Funding — Customers generate a virtual bank account on their dashboard and fund their WHMCS credit balance via bank transfer

Download

⬇ Download WHMCS Module (ZIP)

Installation

Download and extract the ZIP file
Upload the modules folder to your WHMCS root directory (merge with existing)
In WHMCS Admin → Setup → Payments → Payment Gateways → Activate Bridgenetic
In WHMCS Admin → Setup → Addon Modules → Activate Bridgenetic Account Funding
Enter your API Key and Secret Key in both modules
Configure webhook URL in Bridgenetic dashboard: https://your-whmcs.com/modules/gateways/callback/bridgenetic.php

How Invoice Payments Work

Customer views an unpaid invoice and clicks "Pay Now"
Customer is redirected to Bridgenetic's hosted checkout page
Customer pays using Bank Transfer, USSD, OPay, or Bank Debit
Bridgenetic sends a checkout.success webhook to your WHMCS
Invoice is automatically marked as paid

How Account Funding Works

Customer visits the "Fund Account" page in their WHMCS client area
Clicks "Generate My Account" to get a dedicated virtual bank account
The account number is stored permanently (one per client)
Customer transfers any amount to that account at any time
Bridgenetic sends a deposit.success webhook to your WHMCS
Customer's WHMCS credit balance is automatically increased
Customer can use their balance to pay any invoice on the site

Webhook URL

Configure this URL in your Bridgenetic merchant dashboard under Settings → Webhooks:

https://your-whmcs-domain.com/modules/gateways/callback/bridgenetic.php

Module Contents

modules/
├── gateways/
│   ├── bridgenetic.php              (Payment Gateway)
│   └── callback/
│       └── bridgenetic.php          (Webhook Handler)
└── addons/
    └── bridgenetic_funding/         (Account Funding Addon)
        ├── bridgenetic_funding.php
        └── templates/
            └── clientarea.tpl

Requirements

WHMCS 7.0 or later
PHP 7.4+ with cURL extension
Active Bridgenetic merchant account with completed KYC
NGN currency configured in WHMCS

19. Changelog

Track changes and updates to the Bridgenetic API.

v2.0.0 — May 2025

Hosted Checkout system (bank transfer, USSD, OPay, bank debit)
JavaScript SDK with inline modal, popup, and redirect modes
Payment Links (fixed and dynamic amount)
OPay wallet payments (redirect-based)
Nigeria Account Charge / Bank Debit (direct debit with bank authorization)
Checkout branding customization (logo, colors, button text)
Checkout analytics and payment method breakdown
Real-time payment status polling (auto-confirms bank transfers)
Bill Payments API (Airtime, Data, Electricity, Cable TV, Betting)
Multi-provider support (Flutterwave + Kuda) with per-feature routing
WHMCS payment gateway module

v1.3.0 — June 2024

Added idempotency key support for POST requests
Introduced merchant profile API endpoints
Added X-RateLimit-Reset header to all responses
Improved webhook retry logic with exponential backoff

v1.2.0 — April 2024

Added webhook URL configuration endpoint
Introduced transaction search by reference
Added API key generation endpoint
Python SDK released

v1.1.0 — February 2024

Added virtual account listing and detail endpoints
Introduced amount filters for transaction listing
Node.js SDK released
Added webhook signature verification (HMAC-SHA512)

v1.0.0 — December 2023

Initial API release
Virtual Accounts API (create, list, get)
Transactions API (list, get by reference)
Withdrawals API (create, list)
Webhook notifications (deposit.success, withdrawal.success, withdrawal.failed)
Bearer token and API Key + Signature authentication

API Documentation

1. Introduction & Overview

2. Authentication

Method 1: Bearer Token (Sanctum)

Method 2: API Key + Signature (HMAC)

Security Best Practices

3. Base URL & Headers

Example Request (Bearer Token)

Example Request (API Key + Signature)

4. Rate Limiting

Rate Limit Headers

Example Response Headers

Handling 429 Responses

5. Authentication Endpoints

Register

Request Body

Response (201 Created)

Login

Request Body

Response (200 OK)

Logout

Response (200 OK)

Forgot Password

Request Body

Response (200 OK)

Reset Password

Request Body

Response (200 OK)

6. Merchant Profile

Get Merchant Profile

Response (200 OK)

Update Merchant Profile

Request Body

Response (200 OK)

Set Webhook URL

Request Body

Response (200 OK)

Get Balance Overview

Response (200 OK)

Get Transaction History

Get Virtual Account List

Get Withdrawal List

Get Settlement Logs

Get Webhook Delivery Logs

Get API Usage

Get Fee Breakdown

Get Payment Analytics

7. API Keys

Generate API Key

Response (201 Created)

Regenerate API Key

Response (201 Created)

8. Customers API

Create a Customer

Request Body

Required Fields

Response (201 Created)

List Customers

Query Parameters

Response (200 OK)

Get a Customer

Response (200 OK)

9. Virtual Accounts API

Create a Virtual Account

Request Body

Required Fields

How It Works

Narration Rules

Response (201 Created)

Error Response — Validation Failed (422)

Error Response — KYC Required (422)

List Virtual Accounts

Query Parameters

Response (200 OK)

Get a Virtual Account

Response (200 OK)

10. Transactions API

List Transactions

Query Parameters

Response (200 OK)

Response (200 OK) — Example for `data`