Transaction History and Status Tracking

Every conversion you create through PeerPesa is tracked as a transaction. You can list transactions to reconcile activity, filter by status or date, and retrieve a single transaction for full details including fees, rates, and blockchain confirmation data.

All endpoints require a valid Bearer token. See Authentication for how to obtain one.

List transactions

Retrieve a paginated list of transactions with optional filters.

Endpoint

GET /transactions

Query parameters

string

Filter by transaction type: onramp, offramp, deposit, withdraw, send, buy, or swap.

string

Only return transactions created by this recurring payment, for example rp_5t8w2k.

string

Filter by status: awaiting_payment, awaiting_deposit, processing, completed, failed, expired, or refunded.

string

Filter by blockchain network, for example stellar or celo.

string

Matches transaction ID, order_id, reference, wallet addresses, tx_hash, and account numbers. Minimum 2 characters.

string

Only include transactions created on or after this date (YYYY-MM-DD or ISO 8601, UTC).

string

Only include transactions created on or before this date (YYYY-MM-DD or ISO 8601, UTC).

string

Filter by asset or fiat currency, for example USDC or KES.

number

Only include transactions with an amount greater than or equal to this value.

number

Only include transactions with an amount less than or equal to this value.

string

default:"created_at"

created_at, updated_at, or amount.

string

default:"desc"

desc or asc.

integer

default:"1"

Page number to return, starting at 1. See Pagination and filters.

integer

default:"20"

Number of results per page. Maximum is 100.

integer

default:"20"

Alias for size. If you send both, size is used.

Request

curl -X GET "https://api.peerpesa.co/v1/transactions?page=1&size=20&status=completed&start_date=2026-07-01&end_date=2026-07-31" \
  -H "Authorization: Bearer <access_token>"

fetch('https://api.peerpesa.co/v1/transactions?page=1&size=20&status=completed&start_date=2026-07-01&end_date=2026-07-31', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <access_token>',
  },
})
  .then((res) => res.json())
  .then((data) => console.log(data));

Example response

{
  "data": [
    {
      "id": "txn_3j9x2kL8pQvW",
      "type": "offramp",
      "status": "completed",
      "quote_id": "qt_8f2k9mN4pQrS",
      "network": "stellar",
      "asset": "USDC",
      "fiat_currency": "KES",
      "source_amount": "100.00",
      "destination_amount": "12945.00",
      "fee": {
        "total": "1.50",
        "currency": "USDC",
        "processing_fee": "1.00",
        "network_fee": "0.50"
      },
      "rate": "129.45",
      "tx_hash": "a1b2c3d4e5f6...",
      "beneficiary_id": "ben_2k9mN4pQrS7T",
      "reference": "order-98765",
      "created_at": "2024-06-10T14:23:00Z",
      "updated_at": "2024-06-10T14:35:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 134,
    "total_pages": 7
  }
}

Response fields

array

List of transaction objects.

string

Unique transaction identifier starting with txn_.

string

Transaction type: onramp, offramp, deposit, withdraw, send, buy, or swap. See the wallet operations pages for wallet transaction types.

string

Current status in the transaction lifecycle.

string

Amount being converted, as a decimal string.

string

Amount the recipient receives after fees, as a decimal string.

object

Fee breakdown including total, currency, processing_fee, and network_fee.

string

Exchange rate applied to the transaction.

string | null

Blockchain transaction hash when available (null until confirmed).

object

Page details: page, size, total (matching transactions across all pages), and total_pages. See Pagination.

Retrieve a transaction

Fetch complete details for a single transaction by its ID.

Endpoint

GET /transactions/{id}

Path parameters

string

required

The unique transaction ID, for example txn_3j9x2kL8pQvW.

Request

curl -X GET "https://api.peerpesa.co/v1/transactions/txn_3j9x2kL8pQvW" \
  -H "Authorization: Bearer <access_token>"

fetch('https://api.peerpesa.co/v1/transactions/txn_3j9x2kL8pQvW', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <access_token>',
  },
})
  .then((res) => res.json())
  .then((data) => console.log(data));

Example response

{
  "id": "txn_3j9x2kL8pQvW",
  "type": "onramp",
  "status": "awaiting_payment",
  "quote_id": "qt_8f2k9mN4pQrS",
  "network": "celo",
  "asset": "USDC",
  "fiat_currency": "NGN",
  "source_amount": "50000.00",
  "destination_amount": "48.50",
  "fee": {
    "total": "1.50",
    "currency": "USDC",
    "processing_fee": "1.00",
    "network_fee": "0.50"
  },
  "rate": "1030.93",
  "tx_hash": null,
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "reference": "user-deposit-42",
  "created_at": "2024-06-11T09:15:00Z",
  "updated_at": "2024-06-11T09:15:00Z"
}

Transaction status lifecycle

Statuses move forward in one direction except for terminal failure states and manual refunds.

Status	Description
`awaiting_payment`	Onramp only. Fiat payment from the user has not yet been received.
`awaiting_deposit`	Offramp only. Crypto deposit from the user has not yet been confirmed on chain.
`processing`	Funds have been received and the conversion or payout is in progress.
`completed`	The conversion finished successfully and the destination funds have been delivered.
`failed`	The transaction could not complete. No funds were lost; any received funds are refunded automatically when possible.
`expired`	The quote or deposit window expired before funds were received.
`refunded`	A refund was issued after a failure or manual request.

A transaction can reach expired if the quote expires before fiat payment (onramp) or crypto deposit (offramp) is received. Always create a fresh quote if the previous one has expired.

​List transactions

​Endpoint

​Query parameters

​Request

​Example response

​Response fields

​Retrieve a transaction

​Endpoint

​Path parameters

​Request

​Example response

​Transaction status lifecycle

List transactions

Endpoint

Query parameters

Request

Example response

Response fields

Retrieve a transaction

Endpoint

Path parameters

Request

Example response

Transaction status lifecycle