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

# Transactions

> Query your complete transaction history — payments, payouts, and refunds.

## The transaction object

A transaction is the single source of truth for every financial event in Orafi. Each payment, payout, and refund creates a transaction record.

<ResponseField name="id" type="string">
  Unique identifier for the transaction.
</ResponseField>

<ResponseField name="type" type="string">
  Transaction type. One of `PAYMENT`, `PAYOUT`, or `REFUND`.
</ResponseField>

<ResponseField name="status" type="string" default="PENDING">
  Current status. One of `PENDING`, `COMPLETED`, or `FAILED`.
</ResponseField>

<ResponseField name="amount" type="number">
  Transaction amount in NGN.
</ResponseField>

<ResponseField name="amountInUSDC" type="number">
  Equivalent amount in USDC.
</ResponseField>

<ResponseField name="mode" type="string">
  Whether this transaction was created in `test` or `live` mode.
</ResponseField>

<ResponseField name="token" type="string" default="USDC">
  The token used. Currently always `USDC`.
</ResponseField>

<ResponseField name="createdAt" type="datetime">
  Timestamp when the transaction was created.
</ResponseField>

<ResponseField name="confirmedAt" type="datetime">
  Timestamp when the transaction was confirmed. Null if still pending.
</ResponseField>

<ResponseField name="profileId" type="string">
  Business profile that owns this transaction.
</ResponseField>

<ResponseField name="customerId" type="string">
  Customer associated with the transaction, if applicable.
</ResponseField>

<ResponseExample>
  ```json The transaction object theme={null}
  {
    "id": "cmjfu1cjv0003v8vsmmxgjk05",
    "type": "PAYMENT",
    "status": "COMPLETED",
    "amount": 4000,
    "amountInUSDC": 2.53,
    "mode": "test",
    "token": "USDC",
    "createdAt": "2025-12-20T10:30:00.000Z",
    "confirmedAt": "2025-12-20T10:32:15.000Z",
    "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b",
    "customerId": "cmjr4c7qq0000v8hozkzz4em5",
    "payment": { ... },
    "payout": null,
    "refund": null
  }
  ```
</ResponseExample>

<Note>
  Depending on the transaction `type`, one of the following sub-objects will be populated:

  * `type: "PAYMENT"` → includes a nested `payment` object. See [Payments](/api-reference/endpoint/payments#transaction-sub-object).
  * `type: "PAYOUT"` → includes a nested `payout` object. See [Payouts](/api-reference/endpoint/payouts#transaction-sub-object).
  * `type: "REFUND"` → includes a nested `refund` object. See [Refunds](/api-reference/endpoint/refunds#transaction-sub-object).
</Note>

***

## List all transactions

<div className="api-method-box">
  <span className="api-method get">GET</span> `/transactions`
</div>

Returns a paginated list of all transactions for the authenticated business. Supports filtering by type, status, token, mode, date, and more.

### Query parameters

<ParamField query="type" type="string">
  Filter by type: `PAYMENT`, `PAYOUT`, or `REFUND`.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `PENDING`, `COMPLETED`, or `FAILED`.
</ParamField>

<ParamField query="token" type="string">
  Filter by token. Currently only `USDC`.
</ParamField>

<ParamField query="mode" type="string">
  Filter by mode: `test` or `live`.
</ParamField>

<ParamField query="date" type="string">
  JSON-encoded date filter. Supports preset intervals or custom ranges.

  **Preset:** `{"type":"preset","interval":"last7days"}`

  Allowed intervals: `today`, `yesterday`, `last7days`, `last30days`, `thisMonth`, `lastMonth`, `thisYear`

  **Range:** `{"type":"range","startDate":"2025-01-01","endDate":"2025-01-31"}`
</ParamField>

<ParamField query="paymentLinkId" type="string">
  Filter by a specific paylink.
</ParamField>

<ParamField query="paymentMethod" type="string">
  Filter by payment method: `PAYMENT_LINK` or `HOSTED_CHECKOUT`.
</ParamField>

<ParamField query="customerId" type="string">
  Filter by customer.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of transactions per page.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for pagination. Pass the `nextCursor` from a previous response.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.orafi.app/v1/transactions?status=COMPLETED&limit=10" \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.orafi.app/v1/transactions?status=COMPLETED&limit=10",
    { headers: { "x-api-key": "ora_test_your_api_key" } }
  );
  ```

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Transactions retrieved successfully",
    "data": {
      "transactions": [
        {
          "id": "cmjr6iwo60004v84wdnwm7qub",
          "type": "REFUND",
          "status": "FAILED",
          "amount": 200,
          "mode": "test",
          "createdAt": "2025-12-29T13:13:41.094Z",
          "confirmedAt": null,
          "token": "USDC",
          "date": "2025-12-29T13:13:41.094Z",
          "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b",
          "customerId": "cmj6esbky0000v83kibbrjxwp",
          "customer": {
            "id": "cmj6esbky0000v83kibbrjxwp",
            "firstname": "Melvin",
            "lastname": "Charles",
            "email": "customer@example.com",
            "mode": ["test"],
            "totalSpent": 0
          },
          "payment": null,
          "payout": null,
          "refund": {
            "id": "cmjr6ixla0005v84wlfust2mn",
            "amount": "200",
            "status": "FAILED",
            "reason": "Customer not satisfied!",
            "walletAddress": "0xc9f89b...1ad9",
            "originalTxId": "cmjlzeq0j0001v83g2cuplnbg"
          }
        }
      ],
      "count": 1,
      "nextCursor": null,
      "hasNextPage": false
    }
  }
  ```
</ResponseExample>

***

## Retrieve a transaction

<div className="api-method-box">
  <span className="api-method get">GET</span> `/transactions/{transactionId}`
</div>

Fetches full details for a single transaction, including related payment, payout, or refund data.

### Path parameters

<ParamField path="transactionId" type="string" required>
  Unique identifier of the transaction to retrieve.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X GET https://api.orafi.app/v1/transactions/cmjr6iwo60004v84wdnwm7qub \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.orafi.app/v1/transactions/cmjr6iwo60004v84wdnwm7qub",
    { headers: { "x-api-key": "ora_test_your_api_key" } }
  );
  ```

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Transactions retrieved successfully",
    "data": {
      "id": "cmjr6iwo60004v84wdnwm7qub",
      "type": "REFUND",
      "status": "FAILED",
      "amount": 200,
      "mode": "test",
      "createdAt": "2025-12-29T13:13:41.094Z",
      "confirmedAt": null,
      "token": "USDC",
      "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b",
      "customerId": "cmj6esbky0000v83kibbrjxwp",
      "customer": {
        "id": "cmj6esbky0000v83kibbrjxwp",
        "firstname": "Melvin",
        "lastname": "Charles",
        "email": "customer@example.com"
      },
      "refund": {
        "id": "cmjr6ixla0005v84wlfust2mn",
        "amount": "200",
        "status": "FAILED",
        "reason": "Customer not satisfied!",
        "walletAddress": "0xc9f89b...1ad9",
        "originalTxId": "cmjlzeq0j0001v83g2cuplnbg"
      }
    }
  }
  ```
</ResponseExample>