Xend Finance Merchant API Documentation

Swagger Documentation

For a complete and interactive API reference, including all endpoints, request/response models, and the ability to try out API calls directly, visit our Swagger documentation pages.

Becoming a Merchant

Welcome to the Xend Finance Merchant API. Integrating with our powerful RESTful API and webhook service is the first step to leveraging our platform.

Merchant Data Structure

You will need to provide the following data. This Joi schema illustrates the required fields and their validation rules.

{
    merchantCompany: Joi.object({
        id: Joi.string().uuid(),
        name: Joi.string(),
        tagline: Joi.string(),
        companyEmail: Joi.string().email().lowercase(),
        countryCode: Joi.string().length(2),
        logoUrl: Joi.string().uri().optional(),
        websiteUrl: Joi.string().uri().optional(),
    }),
    merchantAccount: Joi.object({
        email: Joi.string().email().lowercase(),
        firstName: Joi.string(),
        lastName: Joi.string(),
        phoneNumber: Joi.string(),
        countryCode: Joi.string().length(2),
    }),
}

General API Response

All API responses follow a standardized JSON structure. This ensures consistency and predictability when you interact with our endpoints.

Response Object Structure

{
  "data": {},
  "status": "success",
  "statusCode": 200,
  "message": "Action Completed",
  "action": null,
  "messageLanguageCode": "app_001",
  "details": null,
  "cacheTTL": 20
}

Field Descriptions

How It Works

Xend Finance Exchange offers a suite of DeFi features. To manage interactions, our system defines five core user types.

Account Setup & Configuration

API Authentication

Our API uses a multi-layered authentication approach. The method you use depends on the type of action you are performing.

HMAC Signature (Proxy Member Session-Based)

For proxy member requests, first call POST /Merchant/proxy/member/{proxyMemberId}/auth to get accessToken and accessSecret. Use the token as Bearer auth and generate x-hmac-signature from {timestamp}:{jsonBody} using the access secret.

// Node.js Example
const crypto = require('crypto');

const generateHmacSignature = (secret, timestamp, payload) => {
  const message = `${timestamp}:${payload}`;
  return crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
};

const timestamp = Date.now();
const payload = JSON.stringify({ /* your request body */ });
const accessSecret = 'your_access_secret_from_login';
const hmacSignature = generateHmacSignature(accessSecret, timestamp, payload);

import hmac
import hashlib
import time
import json

def generate_hmac_signature(secret, timestamp, payload):
    message = f"{timestamp}:{payload}".encode('utf-8')
    secret_key = secret.encode('utf-8')
    signature = hmac.new(secret_key, message, hashlib.sha256).hexdigest()
    return signature

timestamp = int(time.time() * 1000)
payload = json.dumps({ # your request body })
access_secret = 'your_access_secret_from_login'
hmac_signature = generate_hmac_signature(access_secret, timestamp, payload)

<?php

function generateHmacSignature($secret, $timestamp, $payload) {
    $message = $timestamp . ":" . $payload;
    return hash_hmac('sha256', $message, $secret);
}

$timestamp = round(microtime(true) * 1000);
$payload = json_encode([ /* your request body */ ]);
$accessSecret = 'your_access_secret_from_login';
$hmacSignature = generateHmacSignature($accessSecret, $timestamp, $payload);
?>

using System;
using System.Security.Cryptography;
using System.Text;

public class HmacGenerator
{
    public static string GenerateHmacSignature(string secret, long timestamp, string payload)
    {
        var message = $"{timestamp}:{payload}";
        var secretBytes = Encoding.UTF8.GetBytes(secret);
        var messageBytes = Encoding.UTF8.GetBytes(message);

        using (var hmac = new HMACSHA256(secretBytes))
        {
            var hash = hmac.ComputeHash(messageBytes);
            return BitConverter.ToString(hash).Replace("-", "").ToLower();
        }
    }

    public static void Main()
    {
        var timestamp = new DateTimeOffset(DateTime.UtcNow).ToUnixTimeMilliseconds();
        var payload = "{\\"key\\":\\"value\\"}"; // JSON string of your payload
        var accessSecret = "your_access_secret_from_login";
        var hmacSignature = GenerateHmacSignature(accessSecret, timestamp, payload);
    }
}

Proxy Member Sample: Get Member Profile

After proxy auth, call your member profile endpoint with the proxy member session credentials. Replace /Member/profile with your exact profile endpoint from Swagger if it differs.

// Proxy member profile request (Node.js)
import crypto from 'crypto';

const accessToken = 'proxy_member_access_token_from_auth_endpoint';
const accessSecret = 'proxy_member_access_secret_from_auth_endpoint';
const bodyObject = {}; // GET profile usually has empty body
const payload = JSON.stringify(bodyObject);
const timestamp = Date.now().toString();
const signature = crypto
    .createHmac('sha256', accessSecret)
    .update(`${timestamp}:${payload}`)
    .digest('hex');

const response = await fetch('https://api-solid-staging.xend.africa/Member/profile', {
    method: 'GET',
    headers: {
        Authorization: `Bearer ${accessToken}`,
        'x-request-timestamp': timestamp,
        'x-hmac-signature': signature,
        'Content-Type': 'application/json',
        Accept: 'application/json',
    },
});

const profile = await response.json();
console.log(profile);

RSA Signature (Stateless Merchant API)

For direct server-to-server API calls, you must use RSA signing. This method is stateless and does not require a login session. It proves the request is from you and that the payload has not been tampered with.

Verifying Your Uploaded Public Key

After uploading your public key you can prove that you still control the matching private key by calling POST /Merchant/lobby/company/public-key/verify. Sign a short metadata payload with your private key, send the signature to this endpoint, and we will reconstruct the same canonical string and verify it with the public key on file.

// verifyPublicKey.js
import crypto from 'crypto';
import fs from 'fs';

const metadata = {
  companyName: 'Acme Pay Ltd',
  contactEmail: '[email protected]',
  submittedBy: '[email protected]',
  timestamp: new Date().toISOString(),
  nonce: `verify-${Date.now()}`,
};

const canonicalString = Object.keys(metadata)
  .filter((key) => metadata[key] !== undefined && metadata[key] !== null && metadata[key] !== '')
  .sort()
  .map((key) => `${key}=${metadata[key]}`)
  .join('&');

const privateKey = fs.readFileSync('./private_key.pem', 'utf8');
const signer = crypto.createSign('RSA-SHA256');
signer.update(canonicalString);
const signature = signer.sign(privateKey, 'base64');

console.log(JSON.stringify({ metadata, signature }, null, 2));

curl -X POST "https://api-solid-staging.xend.africa/api/Merchant/lobby/company/public-key/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <MERCHANT_COMPANY_ID>" \
  -H "x-api-key: <GLOBAL_API_KEY>" \
  -d '{
    "metadata": {
      "companyName": "Acme Pay Ltd",
      "contactEmail": "[email protected]",
      "submittedBy": "[email protected]",
      "timestamp": "2025-01-15T09:30:00.000Z",
      "nonce": "2025-01-15T09:30:00Z#813472"
    },
    "signature": "<base64-signature-from-private-key>"
  }'

Generating Your RSA Key Pair

To get started with RSA authentication, you first need to generate a 2048-bit RSA key pair. Run one of the scripts below to create a private_key.pem and public_key.pem. Keep the private key secure and upload the contents of the public key to your merchant dashboard.

// Save as generateKeys.js and run `node generateKeys.js`
const { generateKeyPair } = require('crypto');
const fs = require('fs');

generateKeyPair('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
}, (err, publicKey, privateKey) => {
  if (err) { return console.error(err); }
  fs.writeFileSync('public_key.pem', publicKey);
  fs.writeFileSync('private_key.pem', privateKey);
  console.log('Public and private key files generated!');
});

# Requires: pip install cryptography
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import rsa

private_key = rsa.generate_private_key(
    public_exponent=65537,
    key_size=2048,
)

pem_private = private_key.private_bytes(
   encoding=serialization.Encoding.PEM,
   format=serialization.PrivateFormat.PKCS8,
   encryption_algorithm=serialization.NoEncryption()
)

public_key = private_key.public_key()
pem_public = public_key.public_bytes(
   encoding=serialization.Encoding.PEM,
   format=serialization.PublicFormat.SubjectPublicKeyInfo
)

with open('private_key.pem', 'wb') as f:
    f.write(pem_private)
with open('public_key.pem', 'wb') as f:
    f.write(pem_public)
print('Public and private key files generated!')

<?php
$config = [
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
];

// Create the private and public key
$res = openssl_pkey_new($config);

// Extract the private key
openssl_pkey_export($res, $private_key);
file_put_contents('private_key.pem', $private_key);

// Extract the public key
$public_key = openssl_pkey_get_details($res);
$public_key = $public_key["key"];
file_put_contents('public_key.pem', $public_key);

echo "Public and private key files generated!\n";
?>

// C# Example for RSA Key Generation
using System;
using System.IO;
using System.Security.Cryptography;

public class RsaKeyGenerator
{
    public static void Main()
    {
        using(var rsa = new RSACryptoServiceProvider(2048))
        {
            // Export the private key
            var privateKey = rsa.ExportRSAPrivateKeyPem();
            File.WriteAllText("private_key.pem", privateKey);

            // Export the public key
            var publicKey = rsa.ExportSubjectPublicKeyInfoPem();
            File.WriteAllText("public_key.pem", publicKey);

            Console.WriteLine("Public and private key files generated!");
        }
    }
}

RSA Signature Generation

// Node.js Example for RSA Signature
const crypto = require('crypto');
const fs = require('fs');

function generateRsaSignature(privateKey, payload) {
  // Create the exact same sorted string from the payload.
  // Filter out null/undefined values and handle nested objects.
  const stringToSign = Object.keys(payload)
    .filter(key => payload[key] != null && payload[key] !== '')
    .sort()
    .map(key => {
      const value = payload[key];
      // Handle nested objects by converting them to JSON strings
      if (typeof value === 'object' && value !== null) {
        return `${key}=${JSON.stringify(value)}`;
      }
      return `${key}=${value}`;
    })
    .join('&');

  // Sign the string with your private key.
  const signature = crypto
    .createSign('RSA-SHA256')
    .update(stringToSign)
    .sign(privateKey, 'base64');

  return signature;
}

// Example Usage:
const privateKey = fs.readFileSync('path/to/your_private_key.pem', 'utf-8');
const requestPayload = {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    countryCode: 'NG',
    phoneNumber: '08012345678',
    kycStandard: false,
    kycProofOfAddress: false,
    kycBusinessVerification: false,
    proxyKYCDetails: {
        idCardType: 'PASSPORT',
        idCardNumber: 'A12345678',
        countryOfIssue: 'NG'
    }
};

// Generate nonce for header
const nonceStr = crypto.randomBytes(16).toString('hex');

const rsaSignature = generateRsaSignature(privateKey, requestPayload);
// Send this rsaSignature in the 'x-rsa-signature' header.

# Python Example for RSA Signature
import time
import os
import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization

def generate_rsa_signature(private_key_pem, payload):
    # Create the exact same sorted string from the payload.
    string_to_sign = '&'.join([f"{k}={json.dumps(v) if isinstance(v, (dict, list)) else v}" for k, v in sorted(payload.items()) if v is not None and v != ''])

    private_key = serialization.load_pem_private_key(
        private_key_pem.encode(),
        password=None,
    )

    signature = private_key.sign(
        string_to_sign.encode('utf-8'),
        padding.PKCS1v15(),
        hashes.SHA256()
    )
    return base64.b64encode(signature).decode('utf-8')

# Example Usage:
with open('path/to/your_private_key.pem', 'r') as f:
    private_key_data = f.read()

request_payload = {
    'firstName': 'John',
    'lastName': 'Doe',
    'email': '[email protected]',
    'countryCode': 'NG',
    'phoneNumber': '08012345678',
    'kycStandard': False,
    'kycProofOfAddress': False,
    'kycBusinessVerification': False,
    'proxyKYCDetails': {
        'idCardType': 'PASSPORT',
        'idCardNumber': 'A12345678',
        'countryOfIssue': 'NG'
    }
}

# Generate nonce for header
nonce_str = os.urandom(16).hex()

rsa_signature = generate_rsa_signature(private_key_data, request_payload)
# Send this rsa_signature in the 'x-rsa-signature' header.

<?php

function generateRsaSignature($privateKey, $payload) {
    // Create the exact same sorted string from the payload.
    ksort($payload);
    $stringToSign = '';
    foreach ($payload as $key => $value) {
        if ($value !== null && $value !== '') {
            $stringToSign .= $key . '=' . $value . '&';
        }
    }
    $stringToSign = rtrim($stringToSign, '&');

    openssl_sign($stringToSign, $signature, $privateKey, OPENSSL_ALGO_SHA256);
    
    return base64_encode($signature);
}

// Example Usage:
$privateKey = file_get_contents('path/to/your_private_key.pem');
$requestPayload = [
    'requestTime' => round(microtime(true) * 1000),
    'amount' => 5000,
    'destinationAccount' => '0123456789'
];

// Generate nonce for header
$nonceStr = bin2hex(random_bytes(16));

$rsaSignature = generateRsaSignature($privateKey, $requestPayload);
// Send this $rsaSignature in the 'x-rsa-signature' header.
?>

// C# Example for RSA Signature
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

public class RsaGenerator
{
    public static string GenerateRsaSignature(string privateKeyPem, Dictionary<string, object> payload)
    {
        // Create the exact same sorted string from the payload.
        var stringToSign = string.Join("&", payload
            .Where(kvp => kvp.Value != null && kvp.Value.ToString() != "")
            .OrderBy(kvp => kvp.Key)
            .Select(kvp => $"{kvp.Key}={kvp.Value}"));

        using (var rsa = new RSACryptoServiceProvider())
        {
            // Import the private key.
            rsa.ImportFromPem(privateKeyPem);

            var dataBytes = Encoding.UTF8.GetBytes(stringToSign);
            var signatureBytes = rsa.SignData(dataBytes, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);

            return Convert.ToBase64String(signatureBytes);
        }
    }

    public static void Main()
    {
        var privateKey = File.ReadAllText(@"path\to\your_private_key.pem");
        var requestPayload = new Dictionary<string, object>
        {
            { "requestTime", new DateTimeOffset(DateTime.UtcNow).ToUnixTimeMilliseconds() },
            { "amount", 5000 },
            { "destinationAccount", "0123456789" }
        };

        // Generate nonce for header
        var nonceStr = Guid.NewGuid().ToString("N");

        var rsaSignature = GenerateRsaSignature(privateKey, requestPayload);
        // Send this rsaSignature in the 'x-rsa-signature' header.
    }
}

Outbound Webhooks

Xend Finance sends real-time event notifications to a URL you configure in your merchant dashboard. Each request is signed with our platform RSA private key and includes your merchant webhook secret so you can authenticate it on receipt.

All deliveries are logged in your dashboard under Developer → Webhooks. From there you can inspect the JSON payload, response, and per-attempt status, and trigger manual resends.

Configuration

1. Set your Webhook URL on the merchant dashboard (Settings → API & Webhooks). It must be HTTPS and publicly reachable.
2. Copy your Webhook Secret — sent on every request as the x-webhook-secret header.
3. Copy the platform Webhook RSA Public Key — used to verify the x-rsa-signature header.
4. Optionally pick which events to subscribe to via Manage Subscription. By default merchants receive all events; if you select a subset, events outside that subset are recorded with delivery status SKIPPED and errorMessage: "Event not in enabledWebhookEvents" — no HTTP request is sent.

Subscribing to Specific Events

The merchant company has an enabledWebhookEvents field with the following semantics:

• null (default) — subscribed to all events.
• [] — subscribed to no events; nothing is delivered (everything is logged as SKIPPED).
• Array of event keys — only the listed events are delivered. Valid keys come from the merchantWebhookEvents public enum.

Update the subscription via the merchant dashboard, or programmatically by sending the enabledWebhookEvents field on PUT /Merchant/lobby/company/profile/update.

Request Headers

Payload Envelope

Every webhook body has the same top-level shape. The data object varies per event.

{
  "event": "MEMBER_STATUS_CHANGED",
  "eventId": "7fbc6e04-9d6c-4f7c-8e0e-1a1b2c3d4e5f",
  "merchantCompanyId": "a3f1...",
  "referenceId": "member-uuid",
  "occurredAt": "2026-04-30T10:14:22.413Z",
  "data": { "memberId": "...", "previousStatus": "ACTIVE", "newStatus": "SUSPENDED" }
}

Verifying the Signature

1. Read the raw request body as a UTF-8 string.
2. Build a canonical string: re-serialize the parsed JSON with all object keys sorted alphabetically (recursively). This is what we sign on our side.
3. Base64-decode the x-rsa-signature header.
4. Verify with RSA-SHA256 using the platform Webhook Public Key.
5. Additionally, compare the x-webhook-secret header to your stored secret.
6. Respond 2xx within 15 seconds to acknowledge.

// Node.js (Express)
const crypto = require('crypto');

function canonicalize(value) {
  return JSON.stringify(value, (_k, v) =>
    v && typeof v === 'object' && !Array.isArray(v)
      ? Object.keys(v).sort().reduce((a, k) => (a[k] = v[k], a), {})
      : v
  );
}

app.post('/webhooks/xend', express.json({ limit: '1mb' }), (req, res) => {
  if (req.get('x-webhook-secret') !== process.env.XEND_WEBHOOK_SECRET) {
    return res.status(401).end();
  }
  const sig = Buffer.from(req.get('x-rsa-signature') || '', 'base64');
  const ok = crypto.createVerify('RSA-SHA256')
    .update(canonicalize(req.body))
    .verify(process.env.XEND_WEBHOOK_PUBLIC_KEY, sig);
  if (!ok) return res.status(400).end();

  // Idempotency: store req.body.eventId; ignore duplicates.
  // Process req.body.event + req.body.data
  res.status(200).json({ received: true });
});

Retries & Delivery Guarantees

• At-least-once delivery. Always de-duplicate using eventId.
• 3 attempts maximum. Initial attempt + retries at +1 minute, +10 minutes, +1 hour.
• Any non-2xx response or network/timeout error counts as a failure. After 3 attempts the delivery moves to EXHAUSTED.
• Request timeout: 15 seconds. Acknowledge first, process asynchronously.
• Manually resend any delivery from the dashboard. Resends re-sign the payload with the current platform key.

Event Catalog

Sample Payloads

Each example below is the full request body posted to your webhook URL. Field names inside data are stable; new optional fields may be added later, so parse defensively.

{
  "event": "MEMBER_CREATED",
  "eventId": "7fbc6e04-9d6c-4f7c-8e0e-1a1b2c3d4e5f",
  "merchantCompanyId": "a3f1b2c4-...",
  "referenceId": "mem_01HZX...",
  "occurredAt": "2026-04-30T10:14:22.413Z",
  "data": {
    "memberId": "mem_01HZX...",
    "externalRef": "merchant-user-123",
    "email": "[email protected]",
    "phoneNumber": "+2348012345678",
    "firstName": "Jane",
    "lastName": "Doe",
    "status": "PENDING",
    "createdAt": "2026-04-30T10:14:22.000Z"
  }
}

{
  "event": "MEMBER_UPDATED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "mem_01HZX...",
  "occurredAt": "2026-04-30T10:20:00.000Z",
  "data": {
    "memberId": "mem_01HZX...",
    "changedFields": ["phoneNumber", "lastName"],
    "phoneNumber": "+2348099999999",
    "lastName": "Doe-Smith"
  }
}

{
  "event": "MEMBER_STATUS_CHANGED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "mem_01HZX...",
  "occurredAt": "2026-04-30T10:25:00.000Z",
  "data": {
    "memberId": "mem_01HZX...",
    "previousStatus": "ACTIVE",
    "newStatus": "SUSPENDED",
    "reason": "Suspended by merchant admin"
  }
}

{
  "event": "MEMBER_KYC_STATUS_CHANGED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "mem_01HZX...",
  "occurredAt": "2026-04-30T10:30:00.000Z",
  "data": {
    "memberId": "mem_01HZX...",
    "previousStatus": "SUBMITTED",
    "newStatus": "APPROVED",
    "submissionType": "STANDARD_KYC"
  }
}

{
  "event": "WALLET_CREDITED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "txn_01HZY...",
  "occurredAt": "2026-04-30T10:40:00.000Z",
  "data": {
    "transactionId": "txn_01HZY...",
    "memberId": "mem_01HZX...",
    "walletForm": "FUNDING",
    "currency": "USDT",
    "amount": "125.50",
    "balanceAfter": "1450.75",
    "transactionForm": "DEPOSIT",
    "source": "CONNECTED_WALLET",
    "txHash": "0xabc..."
  }
}

{
  "event": "WALLET_DEBITED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "txn_01HZZ...",
  "occurredAt": "2026-04-30T10:45:00.000Z",
  "data": {
    "transactionId": "txn_01HZZ...",
    "memberId": "mem_01HZX...",
    "walletForm": "FUNDING",
    "currency": "USDT",
    "amount": "50.00",
    "balanceAfter": "1400.75",
    "transactionForm": "WITHDRAWAL"
  }
}

{
  "event": "PROXY_TRANSFER_COMPLETED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "itr_01J0A...",
  "occurredAt": "2026-04-30T10:50:00.000Z",
  "data": {
    "transferId": "itr_01J0A...",
    "fromMemberId": "mem_01HZX...",
    "toMemberId": "mem_01HZW...",
    "currency": "USDT",
    "amount": "20.00",
    "fee": "0.00",
    "narration": "Internal payout"
  }
}

{
  "event": "SWAP_COMPLETED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "swp_01J0B...",
  "occurredAt": "2026-04-30T10:55:00.000Z",
  "data": {
    "swapId": "swp_01J0B...",
    "memberId": "mem_01HZX...",
    "fromCurrency": "USDT",
    "toCurrency": "NGN",
    "fromAmount": "100.00",
    "toAmount": "152300.00",
    "rate": "1523.00",
    "fee": "0.50",
    "protocol": "ASSET_SWAP"
  }
}

{
  "event": "SWAP_FAILED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "swp_01J0C...",
  "occurredAt": "2026-04-30T11:00:00.000Z",
  "data": {
    "swapId": "swp_01J0C...",
    "memberId": "mem_01HZX...",
    "fromCurrency": "USDT",
    "toCurrency": "NGN",
    "fromAmount": "100.00",
    "reason": "Slippage exceeded tolerance",
    "status": "REVERTED"
  }
}

{
  "event": "FIAT_OFFRAMP_STATUS_CHANGED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "fwd_01J0D...",
  "occurredAt": "2026-04-30T11:05:00.000Z",
  "data": {
    "withdrawalId": "fwd_01J0D...",
    "memberId": "mem_01HZX...",
    "currency": "NGN",
    "amount": "50000.00",
    "previousStatus": "PROCESSING",
    "newStatus": "SUCCESS",
    "bankAccount": { "accountNumber": "****1234", "bankCode": "044" }
  }
}

{
  "event": "BILL_PAYMENT_STATUS_CHANGED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "bil_01J0E...",
  "occurredAt": "2026-04-30T11:10:00.000Z",
  "data": {
    "billPurchaseId": "bil_01J0E...",
    "memberId": "mem_01HZX...",
    "billType": "AIRTIME",
    "provider": "MTN",
    "recipient": "+2348012345678",
    "amount": "500.00",
    "currency": "NGN",
    "previousStatus": "PROCESSING",
    "newStatus": "COMPLETED"
  }
}

{
  "event": "SAVINGS_DEPOSIT_COMPLETED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "sav_01J0F...",
  "occurredAt": "2026-04-30T11:15:00.000Z",
  "data": {
    "investmentId": "sav_01J0F...",
    "memberId": "mem_01HZX...",
    "savingsType": "FIXED_SAVINGS",
    "currency": "USDT",
    "amount": "500.00",
    "durationDays": 90,
    "apy": "8.5"
  }
}

{
  "event": "SAVINGS_REDEEM_COMPLETED",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "sav_01J0F...",
  "occurredAt": "2026-04-30T11:20:00.000Z",
  "data": {
    "investmentId": "sav_01J0F...",
    "memberId": "mem_01HZX...",
    "savingsType": "FIXED_SAVINGS",
    "currency": "USDT",
    "principal": "500.00",
    "interestPaid": "10.41",
    "penaltyFee": "0.00",
    "isEarlyRedemption": false
  }
}

{
  "event": "SAVINGS_INTEREST_PAID",
  "eventId": "...",
  "merchantCompanyId": "a3f1...",
  "referenceId": "sav_01J0F...",
  "occurredAt": "2026-04-30T11:25:00.000Z",
  "data": {
    "investmentId": "sav_01J0F...",
    "memberId": "mem_01HZX...",
    "savingsType": "MONEY_MARKET",
    "currency": "USDT",
    "interestAmount": "0.1156",
    "periodStart": "2026-04-29T00:00:00.000Z",
    "periodEnd": "2026-04-30T00:00:00.000Z"
  }
}

Verifying Webhooks

To ensure the security and integrity of data sent to your webhook URL, all outgoing requests from Xend Finance are signed. We include a signature in the request body. You must verify this signature using the Xend Finance Public Key, which is available for you to copy from your merchant dashboard.

This process guarantees that the webhook was sent by Xend Finance and that its content has not been altered.

Webhook Verification Flow

1. Get Public Key: Copy the Xend Finance Public Key from your merchant dashboard.
2. Receive Webhook: Your server receives a POST request at your configured webhook URL.
3. Extract Signature: Remove the `signature` field from the webhook's JSON payload.
4. Construct String-to-Verify: Create a canonical string from the rest of the payload by sorting the keys alphabetically and joining them (e.g., `amount=5000&status=success...`).
5. Verify Signature: Use the Xend Finance Public Key to verify that the extracted signature matches the string you constructed. If it's valid, process the webhook. Otherwise, discard the request.

Important: Handling Nested Objects

Webhook Verification Examples

// Node.js Example for Webhook Verification
const crypto = require('crypto');

function verifyWebhookSignature(publicKey, payload) {
  const { signature, ...dataToVerify } = payload;
  if (!signature) return false;

  const stringToVerify = Object.keys(dataToVerify)
    .filter(key => dataToVerify[key] != null && dataToVerify[key] !== '')
    .sort()
    .map(key => {
      const value = dataToVerify[key];
      if (typeof value === 'object' && value !== null) {
        return `${key}=${JSON.stringify(value)}`;
      }
      return `${key}=${value}`;
    })
    .join('&');

  const isVerified = crypto
    .createVerify('RSA-SHA256')
    .update(stringToVerify)
    .verify(publicKey, signature, 'base64');

  return isVerified;
}

// Example Usage in an Express.js route
app.post('/webhook', (req, res) => {
  const xendPublicKey = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----'; // From your dashboard
  const isValid = verifyWebhookSignature(xendPublicKey, req.body);

  if (isValid) {
    console.log('Webhook verified successfully.');
    res.status(200).send('OK');
  } else {
    console.error('Webhook verification failed.');
    res.status(400).send('Invalid signature');
  }
});

# Python Example for Webhook Verification
import base64
import json
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

def verify_webhook_signature(public_key_pem, payload):
    signature_b64 = payload.pop('signature', None)
    if signature_b64 is None:
        return False

    string_to_verify = '&'.join([f"{k}={json.dumps(v) if isinstance(v, (dict, list)) else v}" for k, v in sorted(payload.items()) if v is not None and v != ''])
    
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    signature = base64.b64decode(signature_b64)

    try:
        public_key.verify(
            signature,
            string_to_verify.encode(),
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except InvalidSignature:
        return False

# Example Usage in a Flask route
@app.route('/webhook', methods=['POST'])
def webhook_handler():
    xend_public_key = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----' # From your dashboard
    payload = request.get_json()
    is_valid = verify_webhook_signature(xend_public_key, payload)
    if is_valid:
        return 'OK', 200
    else:
        return 'Invalid signature', 400

<?php

function verifyWebhookSignature($publicKey, $payload) {
    if (!isset($payload['signature'])) {
        return false;
    }
    $signature = base64_decode($payload['signature']);
    unset($payload['signature']);

    ksort($payload);
    $stringToVerify = '';
    foreach ($payload as $key => $value) {
        if ($value !== null && $value !== '') {
            if (is_array($value) || is_object($value)) {
                $stringToVerify .= $key . '=' . json_encode($value) . '&';
            } else {
                $stringToVerify .= $key . '=' . $value . '&';
            }
        }
    }
    $stringToVerify = rtrim($stringToVerify, '&');

    $result = openssl_verify($stringToVerify, $signature, $publicKey, OPENSSL_ALGO_SHA256);

    return $result === 1;
}

// Example Usage
$xendPublicKey = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----'; // From your dashboard
$payload = json_decode(file_get_contents('php://input'), true);
$isValid = verifyWebhookSignature($xendPublicKey, $payload);

if ($isValid) {
    http_response_code(200);
    echo 'OK';
} else {
    http_response_code(400);
    echo 'Invalid signature';
}
?>

// C# Example for Webhook Verification
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json.Linq;

public class WebhookVerifier
{
    public static bool VerifyWebhookSignature(string publicKeyPem, string jsonPayload)
    {
        var payload = JObject.Parse(jsonPayload);
        var signatureToken = payload.GetValue("signature", StringComparison.OrdinalIgnoreCase);
        if (signatureToken == null) return false;

        var signature = Convert.FromBase64String(signatureToken.ToString());
        payload.Remove("signature");

        var stringToVerify = string.Join("&", payload
            .Properties()
            .Where(p => p.Value.Type != JTokenType.Null && p.Value.ToString() != "")
            .OrderBy(p => p.Name)
            .Select(p => {
                var value = p.Value;
                if (value.Type == JTokenType.Object || value.Type == JTokenType.Array) {
                    return $"{p.Name}={JsonConvert.SerializeObject(value)}";
                }
                return $"{p.Name}={value}";
            }));

        using (var rsa = new RSACryptoServiceProvider())
        {
            rsa.ImportFromPem(publicKeyPem);
            var dataBytes = Encoding.UTF8.GetBytes(stringToVerify);
            return rsa.VerifyData(dataBytes, signature, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
        }
    }
}

HTTPS Request Samples

Below are sample code examples showing how to make authenticated HTTPS requests to the Merchant API. These examples demonstrate the proper headers and authentication flow required for all merchant endpoints using RSA signatures.

Required Headers

All merchant API requests require the following headers for authentication and security:

Request Sample Code

Here's a complete example of how to make authenticated requests to the Merchant API using RSA signatures:

// Node.js Example - Merchant API Request with RSA Signature
const crypto = require('crypto');
const fs = require('fs');
const axios = require('axios');

const generateRsaSignature = (privateKey, payload) => {
  // Create the exact same sorted string from the payload
  const stringToSign = Object.keys(payload)
    .filter(key => payload[key] != null && payload[key] !== '')
    .sort()
    .map(key => `${key}=${payload[key]}`)
    .join('&');

  // Sign the string with your private key
  const signature = crypto
    .createSign('RSA-SHA256')
    .update(stringToSign)
    .sign(privateKey, 'base64');

  return signature;
};

const makeMerchantRequest = async (
  baseUrl,
  method,
  url,
  payload,
  merchantId,
  apiKey,
  privateKey,
  countryCode = 'WORLD'
) => {
  try {
    const rsaSignature = generateRsaSignature(privateKey, payload);
    
    const headers = {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
      'Authorization': `Bearer ${merchantId}`,
      'x-rsa-signature': rsaSignature,
      'x-country-code': countryCode
    };

    const config = {
      method: method.toLowerCase(),
      url: `${baseUrl}${url}`,
      headers: headers,
      data: method.toLowerCase() !== 'get' ? payload : undefined
    };

    const response = await axios(config);
    return response.data;
  } catch (error) {
    console.error(`Error during request to ${url}:`, error.response?.data || error.message);
    throw error;
  }
};

// Example usage
const exampleRequest = async () => {
  const privateKey = fs.readFileSync('path/to/your_private_key.pem', 'utf-8');
  const merchantId = 'your_merchant_id';
  const apiKey = 'your_api_key';
  const baseUrl = 'https://api-solid-staging.xend.africa';
  
  // Example: Get merchant profile
  const payload = {
    requestTime: Date.now()
  };
  
  // Generate nonce for header
  const nonceStr = crypto.randomBytes(16).toString('hex');
  
  const response = await makeMerchantRequest(
    baseUrl,
    'GET',
    '/api/Merchant/profile',
    payload,
    merchantId,
    apiKey,
    privateKey,
    'NG'
  );
  
  console.log('Response:', response);
};

import requests
import time
import os
import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization

def generate_rsa_signature(private_key_pem, payload):
    # Create the exact same sorted string from the payload
    string_to_sign = '&'.join([f"{k}={json.dumps(v) if isinstance(v, (dict, list)) else v}" for k, v in sorted(payload.items()) if v is not None and v != ''])

    private_key = serialization.load_pem_private_key(
        private_key_pem.encode(),
        password=None,
    )

    signature = private_key.sign(
        string_to_sign.encode('utf-8'),
        padding.PKCS1v15(),
        hashes.SHA256()
    )
    return base64.b64encode(signature).decode('utf-8')

def make_merchant_request(base_url, method, url, payload, merchant_id, api_key, private_key, country_code='WORLD'):
    try:
        rsa_signature = generate_rsa_signature(private_key, payload)
        
        headers = {
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'x-api-key': api_key,
            'Authorization': f'Bearer {merchant_id}',
            'x-rsa-signature': rsa_signature,
            'x-country-code': country_code
        }
        
        full_url = f"{base_url}{url}"
        
        if method.lower() == 'get':
            response = requests.get(full_url, headers=headers)
        elif method.lower() == 'post':
            response = requests.post(full_url, headers=headers, json=payload)
        elif method.lower() == 'put':
            response = requests.put(full_url, headers=headers, json=payload)
        elif method.lower() == 'delete':
            response = requests.delete(full_url, headers=headers)
        else:
            raise ValueError(f"Unsupported method: {method}")
        
        return response.json()
        
    except Exception as error:
        print(f"Error during request to {url}: {error}")
        raise error

# Example usage
def example_request():
    with open('path/to/your_private_key.pem', 'r') as f:
        private_key_data = f.read()

    merchant_id = "your_merchant_id"
    api_key = "your_api_key"
    base_url = "https://api-solid-staging.xend.africa"
    
    # Example: Get merchant profile
    payload = {
        'requestTime': int(time.time() * 1000)
    }
    
    # Generate nonce for header
    nonce_str = os.urandom(16).hex()
    
    response = make_merchant_request(
        base_url,
        "GET",
        "/api/Merchant/profile",
        payload,
        merchant_id,
        api_key,
        private_key_data,
        "NG"
    )
    
    print("Response:", response)

# cURL Example - Merchant API Request with RSA Signature
# Replace the following variables with your actual values:
# - YOUR_API_KEY: Your API key
# - YOUR_MERCHANT_ID: Your merchant ID
# - YOUR_PRIVATE_KEY_PATH: Path to your private key file
# - TIMESTAMP: Current timestamp in milliseconds
# - NONCE_STRING: Random 32-character string
# - RSA_SIGNATURE: Generated RSA signature

# Step 1: Generate timestamp and nonce
TIMESTAMP=$(date +%s)000
NONCE_STRING=$(openssl rand -hex 16)

# Step 2: Prepare payload (for POST/PUT requests)
PAYLOAD='{"requestTime":"'$TIMESTAMP'"}'

# Step 3: Generate RSA signature
# Note: You'll need to implement this in your shell or use a tool
# RSA_SIGNATURE=$(echo -n "nonceStr=$NONCE_STRING&requestTime=$TIMESTAMP" | openssl dgst -sha256 -sign YOUR_PRIVATE_KEY_PATH | base64 -w 0)

# Step 4: Make the request
curl -X GET "https://api-solid-staging.xend.africa/api/Merchant/profile" \
  -H "Accept: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_MERCHANT_ID" \
  -H "x-rsa-signature: RSA_SIGNATURE" \
  -H "x-request-timestamp: $TIMESTAMP" \
  -H "x-nonce-string: $NONCE_STRING" \
  -H "x-country-code: NG"

# Example POST request with payload
curl -X POST "https://api-solid-staging.xend.africa/api/Merchant/proxyfunds/transfer" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_MERCHANT_ID" \
  -H "x-rsa-signature: RSA_SIGNATURE" \
  -H "x-request-timestamp: $TIMESTAMP" \
  -H "x-nonce-string: $NONCE_STRING" \
  -H "x-country-code: NG" \
  -d "$PAYLOAD"

Header Explanations

Proxy Members

Proxy Members are your users, registered and managed on Xend Finance through the API. This allows you to build a seamless experience where your users can interact with Xend Finance's features without leaving your application. API calls for proxy members use the session-based HMAC authentication method.

Register a Proxy Member

Use this endpoint to create a new user on Xend Finance under your merchant account. The response will include an `accessToken` and `accessSecret` specific to that user, which you can use to make API calls on their behalf.

Important: Only the externalProxyMemberUniqueId field is required. This is the unique identifier for the proxy member in your own merchant system and cannot be changed after creation. All other fields are optional.

Endpoint: POST /Merchant/proxymember/add

Sample Response

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "accessSecret": "random-secret-string",
    "sessionExpiryTime": "2h",
    "memberId": "64f1b1b1b1b1b1b1b1b1b1b1",
    "mid": 20123456,
    "email": "uniqueID123@[email protected]",
    "profile": { ... }
  }
}

Refresh Proxy Member Token

When a proxy member's token expires, or before any member-level request, first generate a new session token using the proxy member ID in the path.

Endpoint: POST /Merchant/proxy/member/{proxyMemberId}/auth

Proxy Member Auth Session

This is the recommended session flow for merchants integrating proxy members. It ensures your app always has a valid token and HMAC secret for member-level actions.

Session Flow

1. Create the proxy member once: POST /Merchant/proxy/member/add.
2. Store the returned memberId in your database and map it to your own user ID.
3. At login/session start, get a fresh proxy token: POST /Merchant/proxy/member/{proxyMemberId}/auth.
4. Use the returned accessToken as Bearer token and sign every request using the returned accessSecret.
5. If you get 403 hmac_secret_missing, re-authenticate the proxy member and retry with the new session credentials.

See sample: Proxy member profile request with HMAC.

Important Behavior

Proxy member tokens are accepted on member-scoped endpoints. Internally, the token carries userType: ProxyMember, and the platform validates HMAC using the proxy member's active access secret.

HMAC Formula

signature = HMAC_SHA256(accessSecret, "{timestamp}:{jsonBody}")

• x-request-timestamp: Must be current time in milliseconds.
• x-hmac-signature: Hex digest of the formula above.
• Body for GET: Use {} when request body is empty.

Member Proxy Transfers

This feature is crucial for managing user balances. It allows you to move funds between your main custodial wallet (e.g., `WITHHOLDING_CUSTODIAL`) and the wallets of your proxy members. This enables you to sync balances between your local application and the Xend Finance platform.

Example Flow:

1. A user wants to move funds from their wallet in your app to their Xend Finance trading wallet.
2. You debit the user's balance in your local database.
3. You call the Proxy Funds Transfer endpoint to credit the corresponding proxy member's wallet on Xend Finance.

Endpoint: POST /Merchant/proxyfunds/transfer

POS Agent - Crypto Payment Processing

POS (Point of Sale) Agents are proxy members who can receive cryptocurrency payments from customers and provide fiat cash in return. This feature enables On-Ramp/Off-Ramp processes where customers can pay with crypto and receive fiat currency.

Pagination

Endpoints that return a list of items are paginated. You can control the pagination using the following parameters in your request payload.