Object

The transfer object

Fields

idstringrequired

Starts with trf_.

objectstringrequired

kindstringrequired

One of user_to_user, conversion, onramp, offramp.

statestringrequired

Transfers of every kind share these states. Which states a kind uses, and how it moves between them:

user_to_user: pending → completed; or pending → in_review → completed or failed; pending → canceled only before posting.
conversion: pending → completed, or pending → failed (quote expired, stock or treasury too low). Settles in one ledger transaction, so it is final in the response.
onramp: awaiting_funds → funds_received → completed. Exceptions: in_review (after funds arrive), returned (funds sent back to the sender, final), canceled (from awaiting_funds, final), failed.
offramp: pending → payout_submitted → completed. Exceptions: in_review (before submission), undeliverable and returned (rail rejected the payout; both move on to refunded), refunded (source wallet credited back, final), failed (refused before the wallet was debited, final).

Final states: completed, failed, canceled, returned (on-ramp), refunded. Each change emits transfer.state_changed.

One of pending, awaiting_funds, funds_received, in_review, payout_submitted, completed, failed, canceled, returned, undeliverable, refunded.

state_reasonobject | null

Why the transfer is in an exception state (in_review, failed, returned, undeliverable, refunded, canceled).

state_reason.codestringrequired

state_reason.messagestringrequired

sourceobjectrequired

A resolved source or destination, as returned on a transfer.

source.typestringrequired

One of wallet, fiat, payout_account.

source.wallet_idstring

Starts with wal_.

source.payout_account_idstring

Starts with pa_.

source.user_idstring

Owner of the wallet or payout account. Absent for a fiat source.

Starts with usr_.

source.assetstring

A wallet asset code. The set is data on GET /routes. In 1.0 it holds two assets:

ndeipi-points: Ndeipi Points, bought with fiat on Absa or PayPal at a fixed price per currency and cashed out the same way. Every user's default asset.
ndeipi-coin: NdeipiCoin, opt-in. Its price moves. It is bought and sold only by converting points at a locked quote (POST /quotes), never directly with fiat. A wallet needs acknowledge_price_risk: true to create.

source.currencystring

Lower-case ISO 4217 fiat currency code.

source.railstring

A payment rail code, published by GET /routes. Not an enum by design.

destinationobjectrequired

A resolved source or destination, as returned on a transfer.

destination.typestringrequired

One of wallet, fiat, payout_account.

destination.wallet_idstring

Starts with wal_.

destination.payout_account_idstring

Starts with pa_.

destination.user_idstring

Owner of the wallet or payout account. Absent for a fiat source.

Starts with usr_.

destination.assetstring

A wallet asset code. The set is data on GET /routes. In 1.0 it holds two assets:

ndeipi-points: Ndeipi Points, bought with fiat on Absa or PayPal at a fixed price per currency and cashed out the same way. Every user's default asset.
ndeipi-coin: NdeipiCoin, opt-in. Its price moves. It is bought and sold only by converting points at a locked quote (POST /quotes), never directly with fiat. A wallet needs acknowledge_price_risk: true to create.

destination.currencystring

Lower-case ISO 4217 fiat currency code.

destination.railstring

A payment rail code, published by GET /routes. Not an enum by design.

amountstringrequired

As requested, in the source's unit.

deposit_account_idstring

Set when the on-ramp was created by a deposit to a standing deposit account.

Starts with da_.

deposit_instructionsDepositInstructions | null

One-off on-ramps only.

receiptReceipt | null

Present once funds have moved.

receipt.amount_expectedstring

On-ramp only. The amount from the create request.

receipt.amount_receivedstring

On-ramp only. Fiat that arrived.

receipt.amount_debitedstring

Debited from the source wallet.

receipt.amount_creditedstring

Credited to the destination wallet.

receipt.earned_amountstring

Points transfers only: the part of the amount that moved as earned points and arrived as earned points. The rest moved as cashable points.

receipt.amount_paid_outstring

Off-ramp only. Sent to the payout account, in its currency.

receipt.ratestring

Conversion rate applied, as destination units per source unit.

receipt.feesarray of object

receipt.rail_referencestring

The rail's own reference for the deposit or payout.

receipt.initiated_attimestamprequired

receipt.completed_attimestamp

integrator_referencestring | null

metadataobject

Integrator key-value data, returned unchanged. Up to 50 keys; keys up to 40 characters, values up to 500.

versionintegerrequired

created_attimestamprequired

updated_attimestamprequired

Example

{
  "id": "trf_01JA8ZC4QK7N2Y5W3V0T9S8R6P",
  "object": "transfer",
  "kind": "user_to_user",
  "state": "completed",
  "state_reason": null,
  "source": {
    "type": "wallet",
    "wallet_id": "wal_01JA8Z4K2V9QW3H6Y7XKD2M0RS",
    "user_id": "usr_01JA8Z2F5G6H7J8K9M0N1P2Q3R",
    "asset": "ndeipi-points"
  },
  "destination": {
    "type": "wallet",
    "wallet_id": "wal_01JA8Z5B7C1DE2F3G4H5J6K7LM",
    "user_id": "usr_01JA8Z3H6J7K8M9N0P1Q2R3S4T",
    "asset": "ndeipi-points"
  },
  "amount": "25.00",
  "deposit_instructions": null,
  "receipt": {
    "amount_debited": "25.00",
    "amount_credited": "25.00",
    "earned_amount": "0.00",
    "fees": [],
    "initiated_at": "2026-10-16T09:30:00Z",
    "completed_at": "2026-10-16T09:30:00Z"
  },
  "integrator_reference": "invoice-7781",
  "metadata": {
    "note": "Lunch"
  },
  "version": 2,
  "created_at": "2026-10-16T09:30:00Z",
  "updated_at": "2026-10-16T09:30:00Z"
}