Transactions

{
  "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
}

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.

string

Unique identifier for the transaction.

string

Transaction type. One of PAYMENT, PAYOUT, or REFUND.

string

default:"PENDING"

Current status. One of PENDING, COMPLETED, or FAILED.

number

Transaction amount in NGN.

number

Equivalent amount in USDC.

string

Whether this transaction was created in test or live mode.

string

default:"USDC"

The token used. Currently always USDC.

datetime

Timestamp when the transaction was created.

datetime

Timestamp when the transaction was confirmed. Null if still pending.

string

Business profile that owns this transaction.

string

Customer associated with the transaction, if applicable.

{
  "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
}

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

type: "PAYMENT" → includes a nested payment object. See Payments.
type: "PAYOUT" → includes a nested payout object. See Payouts.
type: "REFUND" → includes a nested refund object. See Refunds.

List all transactions

GET /transactions

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

Query parameters

string

Filter by type: PAYMENT, PAYOUT, or REFUND.

string

Filter by status: PENDING, COMPLETED, or FAILED.

string

Filter by token. Currently only USDC.

string

Filter by mode: test or live.

string

JSON-encoded date filter. Supports preset intervals or custom ranges.Preset: {"type":"preset","interval":"last7days"}Allowed intervals: today, yesterday, last7days, last30days, thisMonth, lastMonth, thisYearRange: {"type":"range","startDate":"2025-01-01","endDate":"2025-01-31"}

string

Filter by a specific paylink.

string

Filter by payment method: PAYMENT_LINK or HOSTED_CHECKOUT.

string

Filter by customer.

number

default:"20"

Maximum number of transactions per page.

string

Cursor for pagination. Pass the nextCursor from a previous response.

curl -X GET "https://api.orafi.app/v1/transactions?status=COMPLETED&limit=10" \
  -H "x-api-key: ora_test_your_api_key"

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

{
  "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
  }
}

Retrieve a transaction

GET /transactions/{transactionId}

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

Path parameters

string

required

Unique identifier of the transaction to retrieve.

curl -X GET https://api.orafi.app/v1/transactions/cmjr6iwo60004v84wdnwm7qub \
  -H "x-api-key: ora_test_your_api_key"

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

{
  "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"
    }
  }
}

Overview

Transactions

Payments

Refunds

Payouts

Paylinks

Customers

Subscriptions

Webhooks

Webhook Deliveries

Crypto Settlements

Fiat Settlements

Profile

Mode

Notifications

Extras

Transactions

The transaction object

List all transactions

Query parameters

Retrieve a transaction

Path parameters

​The transaction object

​List all transactions

​Query parameters

​Retrieve a transaction

​Path parameters

The transaction object

List all transactions

Query parameters

Retrieve a transaction

Path parameters