Get Payments

curl -X GET "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments?limit=10&offset=0" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"

curl -X GET "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments?search=8123456781&limit=10&offset=0" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"

const axios = require('axios');

const response = await axios.get(
  'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments',
  {
    params: {
      limit: 10,
      offset: 0,
      search: '8123456781' // optional
    },
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'
    }
  }
);

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

import requests

response = requests.get(
    'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments',
    params={'limit': 10, 'offset': 0, 'search': '8123456781'},
    headers={'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'}
)

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

[
  {
    "operationID": "wo_8b7c9d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
    "type": "payment",
    "amount": "5000.00",
    "from": "+234 8123456781",
    "fromType": "individual",
    "memo": "Invoice #1234",
    "blockchainID": "tx_abc123...",
    "createdAt": "2026-02-12T10:30:00Z"
  },
  {
    "operationID": "wo_7a6b5c4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d",
    "type": "payment",
    "amount": "15000.00",
    "from": "XYZ Trading",
    "fromType": "merchant",
    "fromShortCode": 100001,
    "memo": "Wholesale order",
    "blockchainID": "tx_ghi789...",
    "createdAt": "2026-02-12T11:00:00Z"
  },
  {
    "operationID": "wo_9c8d0e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "type": "cash-in",
    "amount": "50000.00",
    "from": "PAPSS Distributor",
    "fromType": "distributor",
    "memo": "Monthly deposit",
    "blockchainID": "tx_def456...",
    "createdAt": "2026-02-12T09:15:00Z"
  }
]

{
  "type": "/problems/access-forbidden",
  "status": 403,
  "title": "Access Forbidden",
  "detail": "API key does not have Read Transactions permission"
}

GET

api

merchants

{merchantID}

payments

curl -X GET "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments?limit=10&offset=0" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"

curl -X GET "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments?search=8123456781&limit=10&offset=0" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"

const axios = require('axios');

const response = await axios.get(
  'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments',
  {
    params: {
      limit: 10,
      offset: 0,
      search: '8123456781' // optional
    },
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'
    }
  }
);

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

import requests

response = requests.get(
    'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments',
    params={'limit': 10, 'offset': 0, 'search': '8123456781'},
    headers={'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'}
)

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

[
  {
    "operationID": "wo_8b7c9d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
    "type": "payment",
    "amount": "5000.00",
    "from": "+234 8123456781",
    "fromType": "individual",
    "memo": "Invoice #1234",
    "blockchainID": "tx_abc123...",
    "createdAt": "2026-02-12T10:30:00Z"
  },
  {
    "operationID": "wo_7a6b5c4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d",
    "type": "payment",
    "amount": "15000.00",
    "from": "XYZ Trading",
    "fromType": "merchant",
    "fromShortCode": 100001,
    "memo": "Wholesale order",
    "blockchainID": "tx_ghi789...",
    "createdAt": "2026-02-12T11:00:00Z"
  },
  {
    "operationID": "wo_9c8d0e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "type": "cash-in",
    "amount": "50000.00",
    "from": "PAPSS Distributor",
    "fromType": "distributor",
    "memo": "Monthly deposit",
    "blockchainID": "tx_def456...",
    "createdAt": "2026-02-12T09:15:00Z"
  }
]

{
  "type": "/problems/access-forbidden",
  "status": 403,
  "title": "Access Forbidden",
  "detail": "API key does not have Read Transactions permission"
}

Endpoint

GET /api/v1/merchants/{merchantID}/payments

Authentication

string

required

Bearer token with your API key. Must have Read Transactions permission.

Path Parameters

string

required

The unique identifier of the merchant. Must match the merchant ID associated with the API key.

Query Parameters

integer

default:"100"

Maximum number of payments to return. Maximum value: 1000.

integer

default:"0"

Number of payments to skip for pagination.

string

Optional search query. Matches against sender phone number and payment memo.

Response

Returns an array of payment objects, sorted by creation date (newest first).

array

Show Payment Object

string

Unique identifier for the wallet operation

string

Operation type: payment (from individual or merchant) or cash-in (from distributor)

string

Payment amount as decimal string

string

Sender identifier: phone number (individual), merchant name, or distributor name

string

Source type: individual, merchant, or distributor

integer

Sender merchant short code (only present when fromType is merchant)

string | null

Optional payment memo/reference

string

Blockchain transaction identifier

string

ISO 8601 timestamp of payment

curl -X GET "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments?limit=10&offset=0" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"

curl -X GET "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments?search=8123456781&limit=10&offset=0" \
  -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"

const axios = require('axios');

const response = await axios.get(
  'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments',
  {
    params: {
      limit: 10,
      offset: 0,
      search: '8123456781' // optional
    },
    headers: {
      'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'
    }
  }
);

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

import requests

response = requests.get(
    'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments',
    params={'limit': 10, 'offset': 0, 'search': '8123456781'},
    headers={'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'}
)

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

[
  {
    "operationID": "wo_8b7c9d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
    "type": "payment",
    "amount": "5000.00",
    "from": "+234 8123456781",
    "fromType": "individual",
    "memo": "Invoice #1234",
    "blockchainID": "tx_abc123...",
    "createdAt": "2026-02-12T10:30:00Z"
  },
  {
    "operationID": "wo_7a6b5c4d-3e2f-1a0b-9c8d-7e6f5a4b3c2d",
    "type": "payment",
    "amount": "15000.00",
    "from": "XYZ Trading",
    "fromType": "merchant",
    "fromShortCode": 100001,
    "memo": "Wholesale order",
    "blockchainID": "tx_ghi789...",
    "createdAt": "2026-02-12T11:00:00Z"
  },
  {
    "operationID": "wo_9c8d0e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "type": "cash-in",
    "amount": "50000.00",
    "from": "PAPSS Distributor",
    "fromType": "distributor",
    "memo": "Monthly deposit",
    "blockchainID": "tx_def456...",
    "createdAt": "2026-02-12T09:15:00Z"
  }
]

{
  "type": "/problems/access-forbidden",
  "status": 403,
  "title": "Access Forbidden",
  "detail": "API key does not have Read Transactions permission"
}

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);

    // If we got fewer results than the limit, we've reached the end
    hasMore = payments.length === limit;
    offset += limit;
  }

  return allPayments;
}

Filtering Payments

You can use the search query parameter for server-side filtering by phone number or memo. For additional client-side filtering:

// Get payments from the last 24 hours
const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
const recentPayments = payments.filter(p =>
  new Date(p.createdAt) > yesterday
);

// Get payments above a certain amount
const largePayments = payments.filter(p =>
  parseFloat(p.amount) > 10000
);

// Get payments for a specific phone number
const userPayments = payments.filter(p =>
  p.phoneFrom === '+234 8123456781'
);

Distributor API

Merchant API

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Filtering Payments

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Response

​Pagination Example

​Filtering Payments

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Pagination Example

Filtering Payments