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

# Payments

> Monitor and audit payment transactions across all merchants.

## List Payments

`GET /payments`

Returns a list of payments processed by your merchants, with pagination and filtering options.

### Query Parameters

| Parameter | Type     | Default | Description                                                   |
| :-------- | :------- | :------ | :------------------------------------------------------------ |
| `limit`   | `number` | `50`    | Number of results per page (min 1, max 100).                  |
| `offset`  | `number` | `0`     | Number of results to skip.                                    |
| `status`  | `string` | -       | Filter by lifecycle status: `PENDING`, `CONFIRMED`, `FAILED`. |

### Example Request

```bash theme={null}
curl "https://api.taprails.com/api/v1/management/payments?status=CONFIRMED&limit=2" \
  -H "x-api-key: sk_live_your_key"
```

### Response

The response is a JSON object with a list of payments and pagination metadata.

| Field        | Type     | Description                      |
| :----------- | :------- | :------------------------------- |
| `payments`   | `array`  | A list of recent payments.       |
| `pagination` | `object` | Metadata for traversing results. |

#### Payment Object

| Field           | Type     | Description                                                      |
| :-------------- | :------- | :--------------------------------------------------------------- |
| `payment_id`    | `string` | Unique identifier for the payment request (e.g., `pay_abcd123`). |
| `status`        | `string` | Current status: `PENDING`, `CONFIRMED`, or `FAILED`.             |
| `amount`        | `string` | Payment amount in USDC decimal string.                           |
| `currency`      | `string` | Always `USDC`.                                                   |
| `merchant`      | `object` | Reference to the merchant receiving the payment.                 |
| `merchant.id`   | `string` | The merchant's unique ID.                                        |
| `merchant.name` | `string` | Display name of the merchant.                                    |
| `tx_hash`       | `string` | On-chain transaction hash on Base (once confirmed).              |
| `created_at`    | `string` | ISO 8601 timestamp of payment creation.                          |
| `expires_at`    | `string` | Time until the payment request expires.                          |
| `confirmed_at`  | `string` | Time of on-chain confirmation (if confirmed).                    |

### Sample Response

```json theme={null}
{
  "payments": [
    {
      "payment_id": "pay_xyz789",
      "status": "CONFIRMED",
      "amount": "12.50",
      "currency": "USDC",
      "merchant": {
        "id": "mch_abc123",
        "name": "Coffee Haven"
      },
      "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
      "created_at": "2026-03-28T21:00:00Z",
      "expires_at": "2026-03-28T22:00:00Z",
      "confirmed_at": "2026-03-28T21:05:00Z"
    },
    {
      "payment_id": "pay_ghi456",
      "status": "PENDING",
      "amount": "5.00",
      "currency": "USDC",
      "merchant": {
        "id": "mch_abc123",
        "name": "Coffee Haven"
      },
      "tx_hash": null,
      "created_at": "2026-03-31T01:45:00Z",
      "expires_at": "2026-03-31T02:45:00Z",
      "confirmed_at": null
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": false
  }
}
```