Querying Payments via API

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"

const axios = require('axios');

const merchantID = 'your-merchant-id';
const apiKey = 'uwk_YOUR_API_KEY_HERE';

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

console.log('Payments:', response.data);

import requests

merchant_id = 'your-merchant-id'
api_key = 'uwk_YOUR_API_KEY_HERE'

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

print('Payments:', response.json())

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"

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

response = requests.get(
    f'https://api.yourdomain.com/api/v1/merchants/{merchant_id}/payments',
    params={'search': '8123456781', 'limit': 10, 'offset': 0},
    headers={'Authorization': f'Bearer {api_key}'}
)

The search parameter matches against both the sender’s phone number and the payment memo field.

Pagination

The API supports limit/offset pagination:

Parameter	Type	Default	Description
`limit`	integer	100	Maximum number of payments to return (max: 1000)
`offset`	integer	0	Number of payments to skip
`search`	string	-	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}')

Overview

User Tutorials

API Tutorials

Introduction

Prerequisites

Retrieving Payments

Basic Request

Response Format

Searching Payments

Use Cases

Daily Reconciliation

Export to CSV

Next Steps

API Reference

Get Balance

​Introduction

​Prerequisites

​Retrieving Payments

​Basic Request

​Response Format

​Searching Payments

​Pagination

​Pagination Example

​Use Cases

​Daily Reconciliation

​Export to CSV

​Next Steps

API Reference

Get Balance

Introduction

Prerequisites

Retrieving Payments

Basic Request

Response Format

Searching Payments

Pagination

Pagination Example

Use Cases

Daily Reconciliation

Export to CSV

Next Steps