Skip to main content

​
Introduction

The Payments API allows you to retrieve your merchant’s payment history programmatically. This is useful for building custom dashboards, integrating with accounting systems, or automating payment reconciliation.

​
Prerequisites

Before you begin, ensure you have:
  • An active merchant API key with Read Transactions permission
  • Your merchant ID (available in the dashboard)
If you haven’t created an API key yet, follow the Getting Started with API Keys tutorial first.

​
Retrieving Payments

​
Basic Request

curl -X GET "https://api.yourdomain.com/api/v1/merchants/{merchantID}/payments?limit=10&offset=0" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"

​
Response Format

[
  {
    "operationID": "wo_8b7c9d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
    "type": "payment",
    "amount": "5000.00",
    "phoneFrom": "+234 8123456781",
    "memo": "Invoice #1234",
    "blockchainID": "tx_abc123...",
    "createdAt": "2026-02-12T10:30:00Z"
  }
]

​
Searching Payments

You can search payments by phone number or memo using the search query parameter: 
curl -X GET "https://api.yourdomain.com/api/v1/merchants/{merchantID}/payments?search=8123456781&limit=10&offset=0" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"
The search parameter matches against both the sender’s phone number and the payment memo field.

​
Pagination

The API supports limit/offset pagination:
ParameterTypeDefaultDescription
limitinteger100Maximum number of payments to return (max: 1000)
offsetinteger0Number of payments to skip
searchstring-Optional search by phone number or memo

​
Pagination Example

async function getAllPayments(merchantID, apiKey) {
  const allPayments = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await axios.get(
      `https://api.yourdomain.com/api/v1/merchants/${merchantID}/payments`,
      {
        params: { limit, offset },
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );

    const payments = response.data;
    allPayments.push(...payments);

    hasMore = payments.length === limit;
    offset += limit;
  }

  return allPayments;
}

​
Use Cases

​
Daily Reconciliation

const axios = require('axios');

async function getDailyPayments(merchantID, apiKey) {
  const today = new Date();
  today.setHours(0, 0, 0, 0);

  const payments = await getAllPayments(merchantID, apiKey);

  const todayPayments = payments.filter(p =>
    new Date(p.createdAt) >= today
  );

  const totalAmount = todayPayments.reduce(
    (sum, p) => sum + parseFloat(p.amount), 0
  );

  console.log(`Today's payments: ${todayPayments.length}`);
  console.log(`Total amount: ${totalAmount.toFixed(2)}`);

  return { payments: todayPayments, total: totalAmount };
}

​
Export to CSV

import requests
import csv

def export_payments_csv(merchant_id, api_key, filename='payments.csv'):
    response = requests.get(
        f'https://api.yourdomain.com/api/v1/merchants/{merchant_id}/payments',
        params={'limit': 1000, 'offset': 0},
        headers={'Authorization': f'Bearer {api_key}'}
    )

    payments = response.json()

    with open(filename, 'w', newline='') as f:
        writer = csv.writer(f)
        writer.writerow(['Date', 'Amount', 'From', 'Memo', 'Transaction ID'])

        for p in payments:
            writer.writerow([
                p['createdAt'],
                p['amount'],
                p.get('phoneFrom', ''),
                p.get('memo', ''),
                p['operationID']
            ])

    print(f'Exported {len(payments)} payments to {filename}')

​
Next Steps

API Reference

Detailed endpoint specification

Get Balance

Check your merchant balance via API