Operations

Who calls these endpoints?External API (s2s)

Base path: /api/v1/wallet
Identity: Ed25519 request signature — X-Key-Id, X-Date, X-Nonce, Digest (when there is a body), X-Signature. ±5 min clock window, single-use nonce, optional per-key IP allow-list.
Authorization: The key must carry the wallet product and the wallet permission the call requires; a call without it gets 403 WALLET_INSUFFICIENT_SCOPE. Permissions per endpoint: Key permissions.
Cross-surface: Reading operations exists on all three surfaces. Intervention and reporting are panel-only: operations/:id/intervention-requests, withdrawals/:id/intervention-requests, intervention-requests/*, suspense-funds/*, operations/export, ops-health, operations/:id/receipt.pdf — no s2s equivalents.

Every money-moving call produces an operation — a first-class object with a record, a status, fees, a ledger reference and audit history. It is the single source for reconciliation, support and reporting.

Listing

GET /api/v1/wallet/operations

Parameter	Description
`endUserId`	Operations of a given user
`walletAccountId`	Operations of a given account
`destinationWalletAccountId`	By destination account
`status`	Status filter
`operationType`	Type filter
`limit`	Page size (max 100)
`cursor`	Pagination cursor

Pagination is cursor-based; there is no offset. The page arrives under data.operations with the next-page cursor in data.nextCursor; send it as cursor to fetch the next page.

⚠️

Do not expect offset pagination. Because the list grows over time, offsets would skip or duplicate records — a cursor prevents that structurally.

A single operation

GET /api/v1/wallet/operations/{operationId}

Returned fields:

Field	Description
`id`	Operation id
`operationType`	Type (`W2W_TRANSFER`, `TOPUP_CARD`, …)
`status`	Status
`sourceWalletAccountId`	Source account — on top-ups this is the credited account
`destinationWalletAccountId`	Destination account (empty on top-ups)
`destinationRef`	Destination reference (wallet no / IBAN)
`destinationNameMasked`	Masked destination name
`asset`	Currency / asset
`amount`	Transaction amount (minor-unit)
`feeTotal` · `taxTotal` · `totalCharge`	Fee, tax and total
`scheduleVersionId`	Fee schedule version applied
`ledgerTxnRef`	Ledger transaction reference
`fraudDecision`	Risk decision
`fraudTraceId`	Trace key of the risk evaluation. Use it to look the same evaluation up through the Fraud API. `null` when no evaluation is attached.
`failureCode` · `failureReason`	Failure cause
`paymentPurpose`	Purpose code
`createdAt` · `updatedAt`	Timestamps

Type-specific fields:

Field	On which type
`rail` · `beneficiaryIbanMasked` · `bankRef` · `bankStatus`	Bank integration operations
`fundingSourceType` · `paymentRef` · `agentId`	Top-ups
`commissionTotal` · `commissionScheduleVersionId` · `orderRef`	Wallet payments

⚠️

On a top-up, sourceWalletAccountId is the destination account. A top-up is money in; the "operation's wallet" field carries the credited account and destinationWalletAccountId stays empty. Write your reports accordingly, or top-ups will appear to have no source account.

Receipts

GET /api/v1/wallet/operations/{operationId}/receipt

The receipt is the shareable transaction document. The receiptUrl returned by transfer and payment responses points to the same document.

On the end-user surface:

GET /api/portal/v1/wallet/me/operations
GET /api/portal/v1/wallet/me/operations/{id}
GET /api/portal/v1/wallet/me/operations/{id}/receipt
GET /api/portal/v1/wallet/me/operations/export

Portal endpoints return only the session owner's own operations.

Export

GET /api/panel/v1/wallet/operations/export

Filters mirror the listing endpoint. Narrow the date range for large exports.

Reconciliation states

Status	Meaning	Correct behaviour
`BANK_PROCESSING`	In flight on the bank side	Wait
`AWAITING_RECON`	Outcome uncertain	Do not retry; wait for reconciliation
`HELD`	Held by a risk decision	Tell the user "under review"
`REVERSING`	A reversal or card top-up refund has started and awaits its result	Wait; the result is `REVERSED`. If the ledger rejects it: `AWAITING_RECON` for a reversal, `COMPLETED` for a card top-up refund (no money moved)
`EXPIRED`	Timed out before confirmation	A new operation can be started

⚠️

AWAITING_RECON, HELD and REVERSING are not terminal. An integration that treats them as failures misinforms users and creates double-processing risk.

Audit history

Every status transition writes a history record — from which state to which, when and by what trigger. This is how your support team answers "what happened to this transaction". Panel side: Panel — Operations & Intervention.

Common mistakes

Symptom	Cause	Fix
Records skipped while paginating	Offset-style logic	Use the cursor from the response
Top-ups appear to have no source account	The credited account is in `sourceWalletAccountId`	Branch report logic by type
An `AWAITING_RECON` operation was restarted	Mistaken for terminal	Wait for reconciliation
Fee report does not reconcile	The schedule version changed	Match on `scheduleVersionId`

Webhooks Error Handling