Wicomi API v1.0

API Documentation

Integrate Wicomi's powerful fintech infrastructure directly into your application. Generate virtual accounts, process global payouts, and collect payments natively.

Authentication

All API requests require two 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_...)

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-account
Request Body (JSON)
{
  "email": "customer@example.com",
  "bvn": "12345678901",
  "is_permanent": true
}
Response (201 Created)
{
  "status": "success",
  "message": "Virtual account created successfully",
  "data": {
    "account_number": "1234567890",
    "bank_name": "Wema Bank",
    "currency": "NGN",
    "reference": "flw_ref_123abc"
  }
}

Verify Transaction (Secure Check)

Never trust a frontend redirect URL alone, as malicious users can spoof it. Always use this endpoint from your secure backend to verify the true status of a transaction using its tx_ref before providing value to your users.

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", 
    "createdAt": "2026-08-27T19:54:31.000Z"
  }
}

💡 PRO TIP: Validating the Response

  • Status: Wicomi's completed transaction status is always "completed" (not "successful"). Always check if (response.data.status === 'completed').
  • Amount: The final amount might be slightly higher than what you requested if the user was charged a payment gateway fee. Always validate using if (response.data.amount >= expectedAmount) instead of strict equality to avoid rejecting valid payments.

Fetch Available Banks

Before initiating a payout, you must fetch the available banks and their `bank_code` for the destination country. We support pulling bank lists for Nigeria (NG), USA (US), Ghana (GH), Kenya (KE), and more.

GEThttps://wicomiglobalservices.org/api/v1/banks?country=NG
Response (200 OK)
{
  "status": "success",
  "data": [
    {
      "id": 132,
      "code": "044",
      "name": "Access Bank"
    },
    {
      "id": 120,
      "code": "058",
      "name": "Guaranty Trust Bank"
    }
    // ...
  ]
}

Process Payouts (Transfers)

Programmatically withdraw funds from your Wicomi wallet to any external bank account. The amount (plus a standard ₦50 withdrawal fee) will be immediately deducted from your Wicomi wallet balance.

POSThttps://wicomiglobalservices.org/api/v1/payouts
Request Body (JSON)
{
  "amount": 10000,
  "bank_code": "058", // Pulled from the GET /banks endpoint
  "account_number": "0123456789",
  "narration": "Withdrawal for freelance services",
  "currency": "NGN"
}

Crypto Payouts (Stablecoins)

Wicomi automatically supports USDT and USDC payouts via Flutterwave's Stablecoin API. To initiate a crypto payout, you must use a supported blockchain network name as the bank_codeand the wallet address as the account_number.

  • Supported bank_code values: POLYGON, ETHEREUM, SOLANA, BASE.
  • Supported currency values: USDT, USDC.
  • Fee: A flat fee of $1 is deducted from your wallet for crypto payouts.
Crypto Request Example
{
  "amount": 50,
  "bank_code": "POLYGON", // The blockchain network
  "account_number": "0xd0c7...", // The wallet address
  "narration": "USDT Withdrawal",
  "currency": "USDT" // USDT or USDC
}
Response (200 OK)
{
  "status": "success",
  "message": "Payout initiated successfully",
  "data": {
    "reference": "payout_abc123",
    "amount_deducted": 10050, // Includes ₦50 fee
    "status": "processing"
  }
}

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 and instantly credit your users.

1

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.

Crucial Step: Set the redirectUrl to your website's success page, and attach the user's ID as a query parameter so you know who paid!

POST /api/v1/payment-links { "title": "100 Gold Coins", "amount": 5000, "redirectUrl": "https://yourwebsite.com/verify-payment?user_id=89234" }
2

Redirect to Wicomi

Wicomi will return a checkout_url. Simply redirect your user's browser to this URL. They will see a beautiful, secure payment page to enter their Card, USSD, or Bank Transfer details.

3

Auto-Redirect back to your Website

Once the payment is successful, Wicomi immediately credits your merchant wallet, and automatically redirects the user's browser back to the redirectUrl you provided:

https://yourwebsite.com/verify-payment?user_id=89234&status=completed&tx_ref=plink_xxx

⚠️ SECURITY WARNING

Do not trust the status=completed in the URL! A malicious user could manually type this URL to steal coins without paying. You MUST verify it via your backend in the next step.

💡 PRO TIP: URL Conflict

Wicomi automatically appends its own tx_ref=plink_xxx to your redirect URL. If you want to pass your own internal ID in the URL, do NOT name it tx_ref (e.g. name it my_ref=... instead). Otherwise, your backend will get confused by duplicate parameters!

4

Secure Verification & Crediting

On your website's /verify-payment route, your backend server must take the tx_ref from the URL and securely call the Wicomi Verification API:

GET /api/v1/verify-transaction/plink_xxx Headers: { "x-secret-key": "wicomi_sk_..." }

If Wicomi's backend responds with "status": "completed", you can safely update your database to give User #89234 their 100 Gold Coins!

Meanwhile, the ₦5,000 is already sitting safely in your Wicomi dashboard Wallet, ready for you to withdraw to any bank using the Payouts API!

Server-to-Server Webhooks

Webhooks are the industry standard for guaranteeing your backend receives payment notifications, even if the user closes their browser before redirecting. Configure your Webhook URL in your Wicomi Dashboard to receive real-time POST requests for successful payments.

Webhook Payload Example
{
  "event": "payment.successful",
  "data": {
    "reference": "plink_abc123_1787847729573",
    "merchantRef": "MY_INTERNAL_ID_123",
    "atc_ref": "MY_INTERNAL_ID_123",
    "amount": 5000,
    "currency": "NGN",
    "status": "completed",
    "type": "payment_link",
    "customerEmail": "john@example.com",
    "paymentLinkId": "64f9b8c7e4b0a1a2b3c4d5e6"
  }
}

Securing your Webhooks (Crucial)

To prevent hackers from spoofing webhooks, Wicomi signs every webhook payload using HMAC SHA256 and your highly secure Webhook Secret Hash (available in your dashboard). Wicomi includes this signature in the x-wicomi-signature header. You MUST verify this header in your backend code.

Node.js (Express) Verification Example

const crypto = require('crypto');

app.post('/api/webhooks/wicomi', express.json(), (req, res) => {
  const signature = req.headers['x-wicomi-signature'];
  const payloadString = JSON.stringify(req.body);
  const secret = process.env.WICOMI_WEBHOOK_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadString)
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature! Hacker detected.');
  }

  // Signature is valid. Safely process the payment!
  if (req.body.event === 'payment.successful') {
    console.log("Crediting user...", req.body.data);
  }

  res.status(200).send('OK');
});