Wallet credits

Credit a customer wallet from your prefunded balance

POST/api/v1/tenant/wallet-credits

Scope wallet-credits:write · Write — send Idempotency-Key and X-Request-Id

Moves the amount from your prefunded balance with Neo Wallet to the customer's wallet; no payment provider is involved and the wallet is credited immediately. The wallet is credited only if the result stays within the wallet's maximum balance for the customer's KYC level and your prefunded balance covers the amount. The response state is terminal immediately and wallet_credit.completed is delivered to your webhook.

Request body

Field	Type	Required	Description
walletUid	string	yes	The wallet to credit, as returned by POST /tenant/customers.
amountMinor	number	yes	Positive integer minor units (e.g. 250000 = ETB 2,500.00). Min 1.
currency	string	yes	ISO-4217; must equal the wallet's currency.
clientReference	string	yes	Your own reference; stored and returned verbatim, never interpreted; unique within your account.
metadata	object	no

Example (generated from the schema)

{
  "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "amountMinor": 1,
  "currency": "ETB",
  "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).

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

Errors

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