Wallet API

The Wallet API allows merchants to view and manage their Zikopay wallet balances. Each merchant account has one or more wallets (based on supported currencies) to hold funds from payment transactions and to fund outgoing payouts.

Get Wallet Balances

This endpoint retrieves the current balances for all your wallets.

Endpoint

GET /wallet

Headers

Name	Description
`X-API-Key`	Your Zikopay API Key
`X-API-Secret`	Your Zikopay API Secret
`Accept`	Must be `application/json`

Example Request

GET https://api.payment.zikopay.com/v1/wallet

Success Response

{
  "wallets": [
    {
      "id": "wal_5f3a9b2e8c4d7",
      "currency": "XAF",
      "balance": 150000.00,
      "pending_balance": 15000.00,
      "reserved_balance": 5000.00,
      "available_balance": 130000.00,
      "last_updated": "2025-04-18T08:30:15Z"
    },
    {
      "id": "wal_6e2b8c3f9d5a6",
      "currency": "XOF",
      "balance": 75000.00,
      "pending_balance": 7500.00,
      "reserved_balance": 2500.00,
      "available_balance": 65000.00,
      "last_updated": "2025-04-18T09:15:22Z"
    }
  ]
}

Error Response

{
  "success": false,
  "message": "Failed to retrieve wallets",
  "errors": {
    "authentication": ["Invalid API credentials"]
  }
}

Response Parameters

Parameter	Type	Description
`id`	string	Unique wallet identifier
`currency`	string	Wallet currency code
`balance`	number	Total wallet balance
`pending_balance`	number	Funds that are pending settlement
`reserved_balance`	number	Funds reserved for pending payouts
`available_balance`	number	Funds available for payouts (balance - reserved_balance)
`last_updated`	string	ISO8601 timestamp when balance was last updated

Get Wallet Transactions

This endpoint retrieves transaction history for a specific wallet or all wallets.

Endpoint

GET /wallet/transactions

Headers

Name	Description
`X-API-Key`	Your Zikopay API Key
`X-API-Secret`	Your Zikopay API Secret
`Accept`	Must be `application/json`

Query Parameters

Parameter	Type	Required	Description
`wallet_id`	string	No	Filter by specific wallet ID
`currency`	string	No	Filter by currency (e.g., XAF, XOF)
`type`	string	No	Filter by transaction type (payin, payout, adjustment)
`status`	string	No	Filter by transaction status
`from_date`	string	No	Start date for filtering (YYYY-MM-DD)
`to_date`	string	No	End date for filtering (YYYY-MM-DD)
`page`	integer	No	Page number for pagination (default: 1)
`limit`	integer	No	Number of records per page (default: 20, max: 100)

Example Request

GET https://api.payment.zikopay.com/v1/wallet/transactions?currency=XAF&from_date=2025-04-01&to_date=2025-04-18&limit=10

Success Response

{
  "success": true,
  "message": "Transactions retrieved successfully",
  "data": {
    "transactions": [
      {
        "id": "txn_8f7e6d5c4b3a2",
        "reference": "TXN174506674372585E",
        "type": "payin",
        "amount": 10000.00,
        "fee": 350.00,
        "net_amount": 9650.00,
        "currency": "XAF",
        "status": "completed",
        "operator": "orange_cm",
        "customer_name": "John Doe",
        "description": "Payment for order #12345",
        "created_at": "2025-04-15T14:30:45Z"
      },
      {
        "id": "txn_7e6d5c4b3a2f1",
        "reference": "TXN174506674372586F",
        "type": "payout",
        "amount": 5000.00,
        "fee": 175.00,
        "net_amount": 5175.00,
        "currency": "XAF",
        "status": "completed",
        "operator": "mtn_cm",
        "customer_name": "Jane Smith",
        "description": "Vendor payment",
        "created_at": "2025-04-16T10:15:30Z"
      }
      // Additional transactions...
    ],
    "pagination": {
      "total": 45,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "total_pages": 5,
      "links": {
        "next": "https://api.payment.zikopay.com/v1/wallet/transactions?page=2&limit=10&currency=XAF&from_date=2025-04-01&to_date=2025-04-18"
      }
    }
  }
}

Error Response

{
  "success": false,
  "message": "Failed to retrieve transactions",
  "errors": {
    "from_date": ["Invalid date format, use YYYY-MM-DD"]
  }
}

Response Parameters

Transaction Object

Parameter	Type	Description
`id`	string	Unique transaction identifier
`reference`	string	Transaction reference
`type`	string	Transaction type: `payin`, `payout`, or `adjustment`
`amount`	number	Transaction amount
`fee`	number	Fee charged for the transaction
`net_amount`	number	Net amount (payins: amount - fee, payouts: amount + fee)
`currency`	string	Transaction currency
`status`	string	Transaction status
`operator`	string	Payment operator used
`customer_name`	string	Customer name
`description`	string	Transaction description
`created_at`	string	ISO8601 timestamp when the transaction was created

Pagination Object

Parameter	Type	Description
`total`	integer	Total number of transactions matching the criteria
`count`	integer	Number of transactions in the current page
`per_page`	integer	Number of transactions per page
`current_page`	integer	Current page number
`total_pages`	integer	Total number of pages
`links`	object	Navigation links for pagination

Get Wallet Balance Summary

This endpoint provides a summary of all wallet balances across currencies.

Endpoint

GET /wallet/summary

Headers

Name	Description
`X-API-Key`	Your Zikopay API Key
`X-API-Secret`	Your Zikopay API Secret
`Accept`	Must be `application/json`

Example Request

GET https://api.payment.zikopay.com/v1/wallet/summary

Success Response

{
  "success": true,
  "message": "Wallet summary retrieved successfully",
  "data": {
    "total_balance_summary": [
      {
        "currency": "XAF",
        "total_balance": 150000.00,
        "total_available": 130000.00,
        "total_pending": 15000.00,
        "total_reserved": 5000.00
      },
      {
        "currency": "XOF",
        "total_balance": 75000.00,
        "total_available": 65000.00,
        "total_pending": 7500.00,
        "total_reserved": 2500.00
      }
    ],
    "transaction_summary": {
      "last_30_days": {
        "total_payin_count": 120,
        "total_payin_amount": 250000.00,
        "total_payout_count": 45,
        "total_payout_amount": 125000.00,
        "total_fee_amount": 9375.00
      }
    }
  }
}

Code Examples

Get Wallet Balances

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payment.zikopay.com/v1/wallet",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "X-API-Key: your_api_key",
    "X-API-Secret: your_api_secret"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  $data = json_decode($response, true);
  if ($data['success']) {
    foreach ($data['data'] as $wallet) {
      echo "Currency: " . $wallet['currency'] . "\n";
      echo "Available Balance: " . $wallet['available_balance'] . "\n";
      echo "Total Balance: " . $wallet['balance'] . "\n";
      echo "-------------------\n";
    }
  } else {
    echo "Error: " . $data['message'];
  }
}
?>

JavaScript

const getWalletBalances = async () => {
  try {
    const response = await fetch('https://api.payment.zikopay.com/v1/wallet', {
      method: 'GET',
      headers: {
        'Accept': 'application/json',
        'X-API-Key': 'your_api_key',
        'X-API-Secret': 'your_api_secret'
      }
    });

    const data = await response.json();

    if (data.success) {
      data.data.forEach(wallet => {
        console.log(`Currency: ${wallet.currency}`);
        console.log(`Available Balance: ${wallet.available_balance}`);
        console.log(`Total Balance: ${wallet.balance}`);
        console.log('-------------------');
      });
      return data.data;
    } else {
      console.error('Failed to retrieve wallets:', data.message);
      return null;
    }
  } catch (error) {
    console.error('Error:', error);
    return null;
  }
};

Python

import requests

url = "https://api.payment.zikopay.com/v1/wallet"

headers = {
  'Accept': 'application/json',
  'X-API-Key': 'your_api_key',
  'X-API-Secret': 'your_api_secret'
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    if data['success']:
        for wallet in data['data']:
            print(f"Currency: {wallet['currency']}")
            print(f"Available Balance: {wallet['available_balance']}")
            print(f"Total Balance: {wallet['balance']}")
            print('-------------------')
    else:
        print(f"Error: {data['message']}")
else:
    print(f"HTTP Error: {response.status_code}")

Get Wallet Transactions

PHP

<?php
// Set parameters
$params = [
  'currency' => 'XAF',
  'from_date' => '2025-04-01',
  'to_date' => '2025-04-18',
  'limit' => 10
];

$queryString = http_build_query($params);
$url = "https://api.payment.zikopay.com/v1/wallet/transactions?" . $queryString;

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => $url,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "X-API-Key: your_api_key",
    "X-API-Secret: your_api_secret"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  $data = json_decode($response, true);
  if ($data['success']) {
    // Display transaction information
    foreach ($data['data']['transactions'] as $transaction) {
      echo "Reference: " . $transaction['reference'] . "\n";
      echo "Type: " . $transaction['type'] . "\n";
      echo "Amount: " . $transaction['amount'] . " " . $transaction['currency'] . "\n";
      echo "Status: " . $transaction['status'] . "\n";
      echo "Date: " . $transaction['created_at'] . "\n";
      echo "-------------------\n";
    }

    // Display pagination information
    echo "Page " . $data['data']['pagination']['current_page'] . " of " . $data['data']['pagination']['total_pages'] . "\n";
    echo "Total records: " . $data['data']['pagination']['total'] . "\n";
  } else {
    echo "Error: " . $data['message'];
  }
}
?>

Understanding Wallet Balances

Zikopay wallets maintain several balance types to accurately track funds:

Balance Types

Total Balance: The sum of all funds in the wallet
Available Balance: Funds available for immediate use (Total Balance - Reserved Balance)
Pending Balance: Funds that are being processed but have not yet settled
Reserved Balance: Funds that are allocated for pending payouts

How Balances Change

Pay-ins: When a customer makes a payment, the funds initially go to Pending Balance
Settlement: After the payment processor settles funds (typically 1-2 business days), they move from Pending to Available Balance
Payout Initiation: When you initiate a payout, the funds move from Available to Reserved Balance
Payout Completion: After the payout is processed, the funds (plus fees) are deducted from Reserved Balance

Regional Considerations

Currency Support: Different countries use different currencies (XAF, XOF, NGN, GHS)
Settlement Times: Settlement times vary by country and payment method
Foreign Exchange: Currently, Zikopay does not support automatic currency conversion between wallets

Best Practices

Regular Reconciliation: Reconcile your Zikopay wallet balance with your internal accounting systems regularly
Reserve Planning: Maintain sufficient balance for planned payouts
Balance Monitoring: Implement automated monitoring for low balances
Transaction Review: Regularly review wallet transactions to identify anomalies

Notes

Wallet balances are updated in real-time
Historical transaction data is available for the past 90 days via the API
For older transactions, please contact Zikopay support
All balance queries are subject to the standard API rate limits

Get Wallet Balances​

Endpoint​

Headers​

Example Request​

Success Response​

Error Response​

Response Parameters​

Get Wallet Transactions​

Endpoint​

Headers​

Query Parameters​

Example Request​

Success Response​

Error Response​

Response Parameters​

Transaction Object​

Pagination Object​

Get Wallet Balance Summary​

Endpoint​

Headers​

Example Request​

Success Response​

Code Examples​

Get Wallet Balances​

PHP​

JavaScript​

Python​

Get Wallet Transactions​

PHP​

Understanding Wallet Balances​

Balance Types​

How Balances Change​

Regional Considerations​

Best Practices​

Notes​

Get Wallet Balances

Endpoint

Headers

Example Request

Success Response

Error Response

Response Parameters

Get Wallet Transactions

Endpoint

Headers

Query Parameters

Example Request

Success Response

Error Response

Response Parameters

Transaction Object

Pagination Object

Get Wallet Balance Summary

Endpoint

Headers

Example Request

Success Response

Code Examples

Get Wallet Balances

PHP

JavaScript

Python

Get Wallet Transactions

PHP

Understanding Wallet Balances

Balance Types

How Balances Change

Regional Considerations

Best Practices

Notes