Topup intents

Issue a top-up reference the customer quotes when paying

POST/api/v1/tenant/topup-intents

Scope topup-intents:write · Write — send Idempotency-Key and X-Request-Id

Creates a topup_c2b operation in state pending_provider with a 12-digit intentReference and an expiresAt; no money moves yet. The payment provider (railCode) must be active and able to receive payments, and the customer and wallet able to receive a credit. The wallet is credited when the payment provider reports a payment carrying the reference and the exact amount before the intent expires (topup.confirmed); a payment that does not match is not credited and is held by Neo Wallet for reconciliation. Without a matching payment the intent fails at expiresAt (topup.expired).

Request body

Field	Type	Required	Description
walletUid	string	yes	The wallet the top-up credits, as returned by POST /tenant/customers.
amountMinor	number	yes	Positive integer minor units (e.g. 250000 = ETB 2,500.00); the exact amount the payer must pay in. Min 1.
currency	string	yes	ISO-4217; must equal the wallet's currency.
railCode	string	yes	The payment provider's code the payer will pay through; the provider must be active and accept incoming payments. At most 64 characters.
expiresInSeconds	object	no	Lifetime of the intent in seconds; defaults to the payment provider's configured lifetime, else one hour. Min 60. Max 86400.
clientReference	string	yes	Your own reference; stored and returned verbatim, never interpreted; unique within your account.

Example (generated from the schema)

{
  "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "amountMinor": 1,
  "currency": "ETB",
  "railCode": "string",
  "clientReference": "string"
}

Response · 201

Field	Type	Description
uid	string
type	string	Operation type, e.g. wallet_credit, wallet_debit, payout_b2c or topup_c2b.
state	string	Operation state: created, awaiting_authorization, authorized, held, processing, pending_provider, confirmed, failed, reversed or completed.
amountMinor	number	Integer minor units (e.g. 250000 = ETB 2,500.00).
feeMinor	number	Minor units.
taxMinor	number	Minor units.
currency	string	ISO-4217.
clientReference	string | null	Your reference, exactly as you supplied it.
createdAt	string
completedAt	string | null	When the operation first reached a final state.
links	object
links.self	string	API-relative path of this operation (GET /tenant/operations/{uid}).
links.receipt	string	API-relative path of its receipt (GET /tenant/operations/{uid}/receipt).
intentReference	string	The reference the payer quotes to the provider; 12 digits.
expiresAt	string	After this instant a payment against the reference is not matched.
railCode	string	The payment provider's code the intent was issued on.
payerInstructions	string | null	What to tell the payer, verbatim from the payment provider's configuration; null when there is none.

Example (generated from the schema)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "type": "string",
  "state": "string",
  "amountMinor": 0,
  "feeMinor": 0,
  "taxMinor": 0,
  "currency": "ETB",
  "clientReference": "string",
  "createdAt": "2026-09-03T10:15:30.000Z",
  "completedAt": "2026-09-03T10:15:30.000Z",
  "links": {
    "self": "string",
    "receipt": "string"
  },
  "intentReference": "048213775902",
  "expiresAt": "2026-09-03T10:15:30.000Z",
  "railCode": "string",
  "payerInstructions": "string"
}

Errors

400 401 403 404 409 422 429 500 503 — one body shape for all of them, see Errors.

Get one top-up intent's status and state timeline

GET/api/v1/tenant/topup-intents/{uid}

Scope operations:read

The operation detail of GET /tenant/operations/{uid} for a topup_c2b operation, plus its intentReference and expiresAt.

Path parameters

Name	Type	Required	Description
uid	string	yes

Response · 200

Field	Type	Description
uid	string
type	string	Operation type, e.g. wallet_credit, wallet_debit, payout_b2c or topup_c2b.
state	string	Operation state: created, awaiting_authorization, authorized, held, processing, pending_provider, confirmed, failed, reversed or completed.
amountMinor	number	Integer minor units (e.g. 250000 = ETB 2,500.00).
feeMinor	number	Minor units.
taxMinor	number	Minor units.
currency	string	ISO-4217.
clientReference	string | null	Your reference, exactly as you supplied it.
createdAt	string
completedAt	string | null	When the operation first reached a final state.
links	object
links.self	string	API-relative path of this operation (GET /tenant/operations/{uid}).
links.receipt	string	API-relative path of its receipt (GET /tenant/operations/{uid}/receipt).
timeline	object[]	State transitions of the operation, in sequenceNo order.
timeline[].sequenceNo	number	0 for the creation event, then monotonically increasing.
timeline[].fromState	string | null	State the operation moved from; null on the creation event.
timeline[].toState	string | null	State the operation moved to.
timeline[].occurredAt	string
timeline[].actorType	enum | null	Kind of actor that drove the transition; the actor's identity is never included. One of api_client, admin, system, provider, customer.
provider	object | null	Payment provider status of a top-up or payout; null for operations that involve no payment provider.
provider.state	string	Status at the payment provider: created, initiated, pending, confirmed, failed, reversed, uncertain or reconciled.
provider.reference	string | null	The provider's own reference, when known.
provider.lastUpdatedAt	string	Last provider-side change Neo Wallet recorded.
intentReference	string	The reference the payer quotes to the provider; 12 digits.
expiresAt	string	After this instant a payment against the reference is not matched.

Example (generated from the schema)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "type": "string",
  "state": "string",
  "amountMinor": 0,
  "feeMinor": 0,
  "taxMinor": 0,
  "currency": "ETB",
  "clientReference": "string",
  "createdAt": "2026-09-03T10:15:30.000Z",
  "completedAt": "2026-09-03T10:15:30.000Z",
  "links": {
    "self": "string",
    "receipt": "string"
  },
  "timeline": [
    {
      "sequenceNo": 0,
      "fromState": "string",
      "toState": "string",
      "occurredAt": "2026-09-03T10:15:30.000Z",
      "actorType": "api_client"
    }
  ],
  "provider": {
    "state": "string",
    "reference": "string",
    "lastUpdatedAt": "2026-09-03T10:15:30.000Z"
  },
  "intentReference": "string",
  "expiresAt": "2026-09-03T10:15:30.000Z"
}

Errors

400 401 403 404 429 500 503 — one body shape for all of them, see Errors.