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

# Transactions

> List and inspect payments, settlements, and refunds.

Transactions represent completed and in-flight payments across crypto and fiat rails.

Base path: `/api/v1/merchant`

## Endpoints

| Method | Path                               | Description                  |
| ------ | ---------------------------------- | ---------------------------- |
| `GET`  | `/transactions`                    | List transactions            |
| `GET`  | `/transactions/:id`                | Transaction detail           |
| `POST` | `/transactions/:id/refunds`        | Request refund               |
| `GET`  | `/settlements`                     | List payouts to your balance |
| `GET`  | `/settlements/:id`                 | Settlement detail            |
| `GET`  | `/settlements/:id/transfer-status` | MoMo or bank transfer status |
| `POST` | `/settlements/withdraw`            | Withdraw clearing balance    |
| `GET`  | `/summary`                         | Dashboard KPIs               |
| `GET`  | `/limits`                          | Platform limits for tenant   |

## List transactions

`GET /api/v1/merchant/transactions`

| Query           | Description      |
| --------------- | ---------------- |
| `page`, `limit` | Pagination       |
| `status`        | Filter by status |
| `type`          | Transaction type |
| `from`, `to`    | ISO date range   |

<RequestExample>
  ```bash cURL theme={null}
  curl -s "https://api.morapay.io/api/v1/merchant/transactions?page=1&limit=20" \
    -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
    -H "Morapay-Timestamp: $TIMESTAMP" \
    -H "Morapay-Signature: v1=$SIGNATURE"
  ```
</RequestExample>

<ResponseExample>
  <CodeGroup>
    ```json 200 OK theme={null}
    {
      "success": true,
      "data": [
        {
          "id": "txn_uuid",
          "type": "PAYMENT",
          "status": "COMPLETED",
          "amount": "100.00",
          "currency": "USD",
          "createdAt": "2026-03-01T12:00:00.000Z"
        }
      ],
      "meta": { "page": 1, "limit": 20, "total": 1 }
    }
    ```

    ```json 401 Unauthorized theme={null}
    {
      "success": false,
      "error": "Invalid request signature.",
      "code": "auth.signature.mismatch",
      "requestId": "req_txn401"
    }
    ```
  </CodeGroup>
</ResponseExample>

## Get transaction

`GET /api/v1/merchant/transactions/:id`

Returns line items, fees, payer metadata, and linked payment link or subscription when present.

<RequestExample>
  ```bash cURL theme={null}
  curl -s "https://api.morapay.io/api/v1/merchant/transactions/txn_uuid" \
    -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
    -H "Morapay-Timestamp: $TIMESTAMP" \
    -H "Morapay-Signature: v1=$SIGNATURE"
  ```
</RequestExample>

<ResponseExample>
  <CodeGroup>
    ```json 200 OK theme={null}
    {
      "success": true,
      "data": {
        "id": "txn_uuid",
        "type": "PAYMENT",
        "status": "COMPLETED",
        "amount": "100.00",
        "currency": "USD"
      }
    }
    ```

    ```json 404 Not Found theme={null}
    {
      "success": false,
      "error": "Transaction not found.",
      "code": "resource.not_found",
      "requestId": "req_txn404"
    }
    ```
  </CodeGroup>
</ResponseExample>

## Refund

`POST /api/v1/merchant/transactions/:id/refunds`

Portal users need finance role. Merchant API keys have full tenant access.

| Field    | Type            | Required | Description                   |
| -------- | --------------- | -------- | ----------------------------- |
| `amount` | string / number | No       | Partial refund; omit for full |
| `reason` | string          | No       | Internal note                 |

<RequestExample>
  ```bash cURL theme={null}
  curl -s -X POST "https://api.morapay.io/api/v1/merchant/transactions/txn_uuid/refunds" \
    -H "Content-Type: application/json" \
    -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
    -H "Morapay-Timestamp: $TIMESTAMP" \
    -H "Morapay-Signature: v1=$SIGNATURE" \
    -d '{ "amount": "100.00", "reason": "Customer request" }'
  ```
</RequestExample>

<ResponseExample>
  <CodeGroup>
    ```json 202 Accepted theme={null}
    {
      "success": true,
      "data": {
        "id": "refund_uuid",
        "transactionId": "txn_uuid",
        "status": "PENDING",
        "amount": "100.00"
      }
    }
    ```

    ```json 403 Forbidden theme={null}
    {
      "success": false,
      "error": "Your role or key does not allow this action.",
      "code": "FORBIDDEN_MERCHANT_ROLE",
      "requestId": "req_refund403"
    }
    ```

    ```json 422 Unprocessable Entity theme={null}
    {
      "success": false,
      "error": "Transaction is not refundable.",
      "code": "request.validation_failed",
      "requestId": "req_refund422"
    }
    ```
  </CodeGroup>
</ResponseExample>

## Settlements and withdrawals

`GET /api/v1/merchant/settlements` lists merchant payouts.

`POST /api/v1/merchant/settlements/withdraw` withdraws to a linked MoMo or bank account.

Withdraw body: `{ "amount", "currency", "payoutMethodId" }`.

<RequestExample>
  ```bash cURL theme={null}
  curl -s -X POST "https://api.morapay.io/api/v1/merchant/settlements/withdraw" \
    -H "Content-Type: application/json" \
    -H "Morapay-Key: $MORAPAY_PUBLIC_KEY" \
    -H "Morapay-Timestamp: $TIMESTAMP" \
    -H "Morapay-Signature: v1=$SIGNATURE" \
    -d '{
      "amount": "500.00",
      "currency": "GHS",
      "payoutMethodId": "pm_uuid"
    }'
  ```
</RequestExample>

<ResponseExample>
  <CodeGroup>
    ```json 202 Accepted theme={null}
    {
      "success": true,
      "data": {
        "id": "settlement_uuid",
        "status": "PROCESSING",
        "amount": "500.00",
        "currency": "GHS"
      }
    }
    ```

    ```json 400 Bad Request theme={null}
    {
      "success": false,
      "error": "Insufficient clearing balance.",
      "code": "payouts.momo.insufficient_balance",
      "requestId": "req_withdraw400"
    }
    ```
  </CodeGroup>
</ResponseExample>

## Summary KPIs

`GET /api/v1/merchant/summary?days=30&seriesDays=7`

Returns volume, fees, status breakdowns, and time series for the resolved TEST or LIVE environment.

## Related

* [Payment links API](/api-reference/payment-links)
* [Payout methods](/api-reference/payout-methods)
* [Payout rails API](/api-reference/payout-rails)
* [Conventions](/api-reference/conventions)