Wicomi API v1.0 (Latest)

API Documentation

Integrate Wicomi's powerful fintech infrastructure directly into your application. Generate virtual accounts, process global payouts, collect payments, upgrade business accounts, and access credit APIs.

Getting Started

Authentication
Virtual Accounts
Payment Links
Verify Transaction
Fetch Banks
Payouts (Transfers)
Business Upgrade API
Loans & Lending API
Webhooks
HTTP Status Codes

Tutorials

Sell In-App Coins

Get your API Keys

Authentication

All API requests require three headers for authentication. You can generate these keys from your Developer Dashboard (Requires an Approved Business Account).

Headers required

x-public-keyYour Wicomi Public Key (e.g. wicomi_pk_...)

x-secret-keyYour Wicomi Secret Key (e.g. wicomi_sk_...)

x-transaction-pinYour 4-Digit Transaction PIN

Create Virtual Account

Provision a dedicated bank account for your customer instantly. Any funds sent to this account will automatically be credited to your main Wicomi wallet and trigger a webhook on your server.

POSThttps://wicomiglobalservices.org/api/v1/virtual-accounts

Request Body (JSON)

{
  "email": "customer@example.com",
  "name": "John Doe",
  "bvn": "12345678901",
  "phonenumber": "08012345678"
}

Response (201 Created)

{
  "status": "success",
  "message": "Virtual account created successfully",
  "data": {
    "account_number": "1234567890",
    "bank_name": "Wema Bank",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "currency": "NGN"
  }
}

GEThttps://wicomiglobalservices.org/api/v1/virtual-accounts

Retrieve a paginated list of all virtual accounts generated by your business. You can optionally filter by customer email (e.g., ?email=customer@example.com).

Generate Payment Links

Generate dynamic hosted checkout links to accept payments via Card, USSD, Apple Pay, and Bank Transfers. Perfect for standard checkouts, in-app purchases, or invoice payments.

POSThttps://wicomiglobalservices.org/api/v1/payment-links

Request Body (JSON)

{
  "title": "Purchase 100 Gold Coins",
  "description": "In-app currency pack",
  "amount": 5000, 
  "currency": "NGN", // Supports USD, GBP, GHS, KES, etc.
  "customerName": "John Doe", // Pre-fills checkout form (Optional)
  "customerEmail": "john@example.com", // Pre-fills checkout form (Optional)
  "customRef": "MY_INTERNAL_ID_123", // Passes your own ID to the webhook (Optional)
  "redirectUrl": "https://yourwebsite.com/success?user=123" // Highly Recommended
}

Response (201 Created)

{
  "status": "success",
  "data": {
    "title": "Purchase 100 Gold Coins",
    "urlSlug": "a1b2c3d4",
    "checkout_url": "https://wicomiglobalservices.org/pay/a1b2c3d4"
  }
}

Verify Transaction (Secure Check)

Never trust a frontend redirect URL alone. Always query this endpoint from your backend to verify transaction status using its tx_ref before fulfilling orders.

Automatic 30-Minute Timeout: Unpaid payment links are automatically verified against payment providers and updated to status failed if unpaid after 30 minutes. A payment.failed webhook will also be dispatched to your server.

GEThttps://wicomiglobalservices.org/api/v1/verify-transaction/{tx_ref}

Response (200 OK)

{
  "status": "success",
  "message": "Transaction verified",
  "data": {
    "reference": "plink_abc123_1787847729573",
    "merchantRef": "MY_INTERNAL_ID_123",
    "type": "deposit",
    "amount": 5000,
    "status": "completed", // "completed" | "pending" | "failed"
    "createdAt": "2026-08-27T19:54:31.000Z"
  }
}

Fetch Banks & Branch Codes

Fetch supported destination banks using country code (NG, GH, KE, US, etc.). If a bank returns has_branches: true, you must fetch its branches using the bank's ID to retrieve the required destination_branch_code for payouts.

GEThttps://wicomiglobalservices.org/api/v1/banks?country=GH

Banks Response (200 OK)

{
  "status": "success",
  "data": [
    {
      "id": 272,
      "code": "GH170100",
      "name": "ACCESS BANK GHANA",
      "has_branches": true
    }
  ]
}

Fetch Bank Branches (If has_branches: true):

GEThttps://wicomiglobalservices.org/api/banks/branches?bank_id=272

Branches Response (200 OK)

{
  "status": "success",
  "data": [
    {
      "id": 1052,
      "branch_code": "GH170101",
      "branch_name": "ACCRA MAIN BRANCH"
    }
  ]
}

Process Payouts (Transfers)

Programmatically send payouts globally to NGN bank accounts, foreign bank accounts (GHS, KES, USD), or Crypto wallet addresses (USDT). The equivalent NGN amount (plus standard fee) is deducted from your Wicomi wallet.

POSThttps://wicomiglobalservices.org/api/v1/payouts

Standard NGN Payout Request

{
  "amount": 10000,
  "bank_code": "058",
  "account_number": "0123456789",
  "narration": "Payout for services",
  "currency": "NGN"
}

International Payout Request (e.g. Ghana Cedis / Kenya Shilling)

{
  "amount": 500, // Destination currency amount (e.g. 500 GHS)
  "currency": "GHS",
  "bank_code": "GH170100",
  "account_number": "0123456789",
  "beneficiary_name": "Kwame Mensah",
  "destination_branch_code": "GH170101", // Required if bank requires branch code
  "narration": "Global Supplier Payment"
}

Crypto Payout Request (USDT)

{
  "amount": 50, // 50 USDT
  "currency": "USDT",
  "bank_code": "USDT",
  "account_number": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", // Crypto Wallet Address
  "network": "BEP20", // Supported: BEP20, TRC20, ERC20
  "beneficiary_name": "Crypto Beneficiary"
}

Business Account Upgrade API

Initiate business upgrade payments or verify company registration status programmatically.

POSThttps://wicomiglobalservices.org/api/business-upgrade/initiate

Request Body (JSON)

{
  "businessName": "Acme Global Enterprise Ltd",
  "businessAddress": "12 Commercial Avenue, Ikeja, Lagos",
  "rcNumber": "RC1234567"
}

Response (200 OK)

{
  "message": "Payment initiated",
  "paymentUrl": "https://checkout.flutterwave.com/v3/hosted/pay/...",
  "reference": "upgrade_biz_64f9b8c_178784772"
}

Loans & Credit Eligibility API

Check user loan eligibility metrics or submit credit requests programmatically.

GEThttps://wicomiglobalservices.org/api/loans/eligibility

Eligibility Response (200 OK)

{
  "accountType": "individual",
  "isEligible": true,
  "tenureMonths": 3.4,
  "requiredTenureMonths": 3,
  "totalTransactionVolume": 650000,
  "requiredVolume": 500000,
  "minLoan": 5000,
  "maxLoan": 1000000,
  "loans": []
}

Tutorial: Selling "In-App Coins"

Want to build an app where users can purchase virtual items, subscriptions, or "coins"? Here is the exact step-by-step flow on how to integrate Wicomi to process the payments.

User Clicks "Buy Coins"

When a user clicks "Buy 100 Coins for ₦5,000" on your website, your backend server makes a request to our/api/v1/payment-links endpoint.

Server-to-Server Webhooks

Webhooks guarantee your backend receives payment notifications in real time. Configure up to 5 Webhook URLs in your Developer Dashboard to receive POST requests signed with HMAC-SHA256 signature in the x-wicomi-signature header.

Event: payment.successful

{
  "event": "payment.successful",
  "data": {
    "reference": "plink_abc123_1787847729573",
    "merchantRef": "MY_INTERNAL_ID_123",
    "amount": 5000,
    "currency": "NGN",
    "status": "completed",
    "type": "payment_link",
    "customerEmail": "john@example.com"
  }
}

Event: payment.failed (Auto-expired links & Failed Payments)

{
  "event": "payment.failed",
  "data": {
    "reference": "plink_abc123_1787847729573",
    "merchantRef": "MY_INTERNAL_ID_123",
    "amount": 5000,
    "status": "failed",
    "type": "payment_link",
    "reason": "Payment link expired after 30 minutes without successful payment"
  }
}

HTTP Status Codes

Code	Description
200 OK	Request succeeded. Returns requested payload.
201 Created	Resource created successfully (e.g. payment link or virtual account).
400 Bad Request	Invalid parameters or missing required fields.
401 Unauthorized	Missing or invalid authentication headers / JWT token.
403 Forbidden	Insufficient permissions (e.g. non-admin attempting admin route).
500 Internal Error	Server error. Retry request or contact support.