Skip to main content
GET
/
api
/
v1
/
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"

[
  {
    "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"
  }
]

​
Endpoint

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

​
Authentication

​
Authorization
string
required
Bearer token with your API key. Must have Read Transactions permission.

​
Path Parameters

​
merchantID
string
required
The unique identifier of the merchant. Must match the merchant ID associated with the API key.

​
Query Parameters

​
limit
integer
default:"100"
Maximum number of payments to return. Maximum value: 1000.
​
offset
integer
default:"0"
Number of payments to skip for pagination.
​
search
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).
​
payments
array
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"

[
  {
    "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"
  }
]

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