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

# Transactions

> Query and manage payment transactions

# Transactions API

## List Transactions

<ParamField query="page" type="number" default="1">Page number</ParamField>
<ParamField query="perPage" type="number" default="20">Results per page (max 100)</ParamField>
<ParamField query="search" type="string">Search by ID, name, email, or description</ParamField>
<ParamField query="status" type="string">Filter by status: APPROVED, SETTLED, DECLINED, REFUNDED, ERROR</ParamField>
<ParamField query="dateFrom" type="string">Start date (ISO 8601)</ParamField>
<ParamField query="dateTo" type="string">End date (ISO 8601)</ParamField>
<ParamField query="merchantId" type="string">Filter by merchant</ParamField>
<ParamField query="sort" type="string" default="processedAt">Sort field</ParamField>
<ParamField query="order" type="string" default="desc">Sort order: asc or desc</ParamField>

```bash theme={null}
GET /api/transactions?page=1&perPage=20&status=SETTLED&dateFrom=2026-01-01
```

### Response

```json theme={null}
{
  "transactions": [
    {
      "id": "clx...",
      "nmiTransactionId": "11848339551",
      "type": "SALE",
      "status": "SETTLED",
      "amount": "187.50",
      "currency": "USD",
      "customerName": "John Doe",
      "customerEmail": "john@example.com",
      "cardType": "visa",
      "cardLast4": "5449",
      "description": "Consulting Services",
      "processedAt": "2026-03-20T21:38:00Z",
      "settledAt": "2026-03-21T01:21:00Z"
    }
  ],
  "total": 7956,
  "page": 1,
  "perPage": 20,
  "totalPages": 398
}
```

## Get Transaction

```bash theme={null}
GET /api/transactions/:id
```

Returns full transaction detail including metadata, BIN data, decline information, and linked customer/subscription.

## Refund Transaction

```bash theme={null}
POST /api/payments/refund
```

```json theme={null}
{
  "transactionId": "clx...",
  "amount": 50.00,
  "reason": "Customer request"
}
```

Processes a refund through the NMI gateway. Partial refunds are supported.

## Sync Transactions

```bash theme={null}
POST /api/nmi/sync
```

```json theme={null}
{
  "nmiAccountId": "clx...",
  "type": "incremental"
}
```

Triggers a sync job for the specified NMI account. Returns the job ID for tracking.