> For the complete documentation index, see [llms.txt](https://docs.netauthpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.netauthpay.com/guides/payment-history.md).

# Payment History

**Get payment by ID**

**`GET /api/payments/:paymentId?agentId=:agentId`**

Returns a single payment. For privacy, only the sender or recipient can see it; pass `agentId` as the requesting agent.

**Response:** `200 OK` — payment object; `404` if not found or not allowed.

***

**Get payments for an agent**

**`GET /api/payments/agent/:agentId`**

Returns all payments where the agent is sender or recipient.

**Query parameters (all optional):**

| Parameter | Type   | Description                                                    |
| --------- | ------ | -------------------------------------------------------------- |
| `limit`   | number | Max number of payments to return (capped by server, e.g. 100). |
| `offset`  | number | Number of payments to skip (for pagination).                   |
| `status`  | string | Filter by `pending`, `processing`, `completed`, or `failed`.   |

* **Without** `limit`/`offset`/`status`: response is a **JSON array** of payments.
* **With** any of these: response is a **paginated object**:

```json
{
  "payments": [ ... ],
  "total": 42,
  "limit": 20,
  "offset": 0
}
```

**Response:** `200 OK`; `500` on error.

***

#### Payment Object Shape

Payments in responses use this structure:

```json
{
  "id": "pay_...",
  "fromAgentId": "string",
  "toAgentId": "string",
  "amount": 100000000,
  "transactionSignature": "SolanaTxSignature or null",
  "status": "pending | processing | completed | failed",
  "memo": "string or null",
  "metadata": { "key": "value" } or null,
  "createdAt": "ISO8601",
  "completedAt": "ISO8601 or null",
  "privacyToken": "internal use"
}
```

***
