> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uw.stargate.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Querying Payments via API

> Learn how to retrieve and search your merchant payment history programmatically

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

<Note>
  If you haven't created an API key yet, follow the [Getting Started with API Keys](/merchants/api-tutorials/api-keys) tutorial first.
</Note>

## Retrieving Payments

### Basic Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.yourdomain.com/api/v1/merchants/{merchantID}/payments?limit=10&offset=0" \
    -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

### Response Format

```json theme={null}
[
  {
    "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:

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript Node.js theme={null}
  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}` }
    }
  );
  ```

  ```python Python theme={null}
  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}'}
  )
  ```
</CodeGroup>

<Tip>
  The search parameter matches against both the sender's phone number and the payment memo field.
</Tip>

## 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

```javascript theme={null}
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

```javascript theme={null}
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

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/merchants/get-payments">
    Detailed endpoint specification
  </Card>

  <Card title="Get Balance" icon="wallet" href="/api-reference/merchants/get-balance">
    Check your merchant balance via API
  </Card>
</CardGroup>