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.
amount	string	yes	A positive amount with at most two decimal places.
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 (placeholder values)

{
  "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "amount": "2500.00",
  "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.
amount	string	A decimal amount with two decimal places.
fee	string	A decimal amount with two decimal places.
tax	string	A decimal amount with two decimal places.
currency	string	ISO-4217.
clientReference	string | null	Your reference, exactly as you supplied it.
sourceWalletUid	string | null	Wallet transfers only: the wallet the money left.
destinationWalletUid	string | null	Wallet transfers only: the wallet the money reached.
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 (placeholder values)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "type": "string",
  "state": "string",
  "amount": "2500.00",
  "fee": "12.50",
  "tax": "1.88",
  "currency": "ETB",
  "clientReference": "string",
  "sourceWalletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "destinationWalletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "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.