Request a direct recharge product

POST/v1/wallets/{walletId}/direct-recharges

Pay from this wallet for Anis staff to deliver the payout. Keep the same operation id if the answer is lost. Billing products (billing) are not available yet.

Permissiondirect_recharges:create

AuthenticationSigned purchase

Anis’s answerSigned

Staff-set limits it counts towardAll requests, Purchases (orders limit)

.NET SDKanis.DirectRecharges.CreateAsync(walletId, operationId, request)

Every processing 202 contains exactly operationId, operationType and status: "processing"; operationType is directRecharge. Full operation reads use 200.
A missing operation read never proves absence. Retry the exact saved body with the same operation id and a fresh signature. A duplicate remains 202 during projection lag. Only a duplicate command on this retry, at or after 60 seconds since original admission, followed by an application-scoped read still not found, closes the operation with idempotency_conflict (409). A read miss or timeout alone never proves a conflict. That code does not prove nothing was charged: the first request may already have been accepted, so read the operation before any new attempt.
This purchase counts toward the existing orders limit and the same daily application spending cap as card orders and other purchases.

Parameters

Name	In	Type	Notes
`walletId`required	`path`	UUID	A UUID, lower-case with hyphens.

Request

Signed with your key, with a one-time nonce, a digest of the body and your operation id as Idempotency-Key.

Headers: Signature-Input, Signature, Content-Digest, Nonce, Idempotency-Key, X-Anis-Date, Accept-Language (optional). The SDKs set all of them for you.

Body: CreateDirectRechargeRequest, as JSON.

Field	Type	Notes
`productId`required	UUID	The selected direct recharge product id.
`payoutAmount`required	string	The desired payout amount string from the quote.
`expectedTotal`required	any	The total you confirmed from the package or quote, as LYD Money. The balance check is exact up to 999,999.999 LYD.
`recipient`required	list of DirectRechargeRecipientInput	The keyed recipient values validated against this direct recharge product.
`note`	string	Your optional note for this direct recharge.
`externalReference`	string	Your reference, included when supplied.

Responses

Status	Meaning	Body
200	Success.	DirectRecharge
202	Accepted — no outcome yet.	DirectRechargeAccepted
400	Refused: the signed request is badly built.	Problem
401	Refused: not authenticated.	Problem
403	Refused: not allowed.	Problem
404	Refused: not found, or not yours.	Problem
409	Refused: conflicts with the current state.	Problem
422	Refused: the request breaks a rule.	Problem
429	Refused: a limit was reached.	Problem
503	No decision: a dependency was unavailable.	Problem

Every answer of this call is signed by Anis — success and every refusal. Require the signature and verify it before you act on the answer; an answer without one is a failure, never an answer (how).

Refusals

Every refusal of this call is a signed problem. Branch on its code; each links to what it means and what to do.

Error	Code	Status
Invalid credentials	`invalid_credentials`	401
Malformed signed request	`malformed_signed_request`	400
Insufficient scope	`insufficient_scope`	403
Source address not allowed	`source_ip_not_allowed`	403
Rate limited	`rate_limited`	429
Validation failed	`validation_failed`	422
Service unavailable	`dependency_unavailable`	503
Request timeout	`request_timeout`	504
Internal error	`internal_error`	500
Account not authorised	`binding_not_authorized`	403
Account inactive	`account_inactive`	403
Wallet not granted	`wallet_not_granted`	404
Not found	`resource_not_found`	404
Currency not supported	`currency_not_supported`	422
Wallet disabled	`wallet_disabled`	409
Wallet expired	`wallet_expired`	409
Business subscription required	`business_subscription_required`	409
Replay detected	`replay_detected`	409
Operation id already used	`idempotency_conflict`	409
Price changed	`price_changed`	409
Insufficient balance	`insufficient_balance`	409
Spending cap reached	`spending_limit_exceeded`	429
Direct recharge product unavailable	`direct_recharge_product_unavailable`	409
Amount outside limits	`amount_out_of_range`	422
Purchase not allowed	`purchase_not_allowed`	403

Types

CreateDirectRechargeRequest

Field	Type	Notes
`productId`required	UUID	The selected direct recharge product id.
`payoutAmount`required	string	The desired payout amount string from the quote.
`expectedTotal`required	any	The total you confirmed from the package or quote, as LYD Money. The balance check is exact up to 999,999.999 LYD.
`recipient`required	list of DirectRechargeRecipientInput	The keyed recipient values validated against this direct recharge product.
`note`	string	Your optional note for this direct recharge.
`externalReference`	string	Your reference, included when supplied.

DirectRechargeRecipientInput

Field	Type	Notes
`key`required	string	The exact field key supplied by the direct recharge product definition.
`value`required	string	The submitted field value; a location choice uses its id.

DirectRecharge

Field	Type	Notes
`operationId`always present	UUID	The same UUID sent as Idempotency-Key for this purchase.
`status`always present	DirectRechargeStatus	The merged customer-facing status; partial refunds add amounts rather than a new status.
`number`always present	integer	The recorded direct recharge number.
`walletId`always present	string	The wallet used for this purchase.
`product`always present	DirectRechargeProductReference	The purchased direct recharge product's id and title.
`payout`always present	DirectRechargePayout	The payout string and named currency; not the LYD Money shape.
`exchangeRate`always present	string	The quoted exchange rate as a decimal string.
`price`always present	Money	The LYD price including applicable location and holder adjustments.
`commission`always present	Money	The LYD commission included in total.
`total`always present	Money	The total wallet cost, as LYD Money. The balance check is exact up to 999,999.999 LYD.
`recipient`always present	list of DirectRechargeRecipientValue	The saved recipient values and display labels.
`note`	string	Your optional note for this direct recharge.
`externalReference`	string	Your reference, included when supplied.
`requestedAt`always present	string (date-time)	When the direct recharge was requested, in UTC.
`completedAt`	string (date-time)	The completion time when supplied, in UTC.
`proofUrl`	string	The recorded delivery proof URL when supplied; no access or expiry guarantee is stated.
`reason`	string	The reason for suspension or either rejected state.
`partialRefund`	DirectRechargePartialRefund	Settled partial-refund and remaining amounts; occurs only if partial refunds are enabled for the product.

DirectRechargeStatus

DirectRechargeProductReference

Field	Type	Notes
`id`always present	UUID	The selected direct recharge product id.
`title`always present	string	The direct recharge product's display text.

DirectRechargePayout

Field	Type	Notes
`amount`always present	string	The payout amount as a decimal string.
`currency`always present	DirectRechargeCurrency	The payout currency display name object.

DirectRechargeCurrency

Field	Type	Notes
`name`always present	string	The display name supplied for this item.

Money

Field	Type	Notes
`amount`always present	string	A decimal string, never a JSON number. Wallet balances may be negative while allowed debt is used. Prices and totals follow each route's amount rules.
`currency`always present	string	An uppercase three-letter currency code, such as `LYD`. Read a wallet’s currency from `balance.currency`.
`asOf`	string (date-time)	When this price or balance was read.

DirectRechargeRecipientValue

Field	Type	Notes
`key`always present	string	The exact field key supplied by the direct recharge product definition.
`name`	LocalizedText	The Arabic and English display labels, omitting empty languages.
`value`always present	string	The submitted field value; a location choice uses its id.
`valueName`	string	The display name of a selected value, when supplied.

LocalizedText

Field	Type	Notes
`ar`	string	The Arabic text; omitted when empty.
`en`	string	The English text; omitted when empty.

DirectRechargePartialRefund

Field	Type	Notes
`refundedPayout`always present	string	The refunded or remaining payout as a string in the product currency.
`refundedTotal`always present	Money	The refunded or remaining LYD wallet amount.
`remainingPayout`always present	string	The refunded or remaining payout as a string in the product currency.
`remainingTotal`always present	Money	The refunded or remaining LYD wallet amount.

DirectRechargeAccepted

Field	Type	Notes
`operationId`always present	UUID	The same UUID sent as Idempotency-Key for this purchase.
`operationType`always present	string	Always directRecharge. Values: `directRecharge`
`status`always present	string	Always processing; the outcome is not final. Values: `processing`