API reference · Direct recharge

Read a direct recharge

GET/v1/direct-recharges/{operationId}

Follow payment, delivery, recipient corrections and settled refunds for a direct recharge your application requested.

Permissiondirect_recharges:read

AuthenticationSigned read

Anis’s answerSigned

Staff-set limits it counts towardAll requests

.NET SDKanis.DirectRecharges.GetAsync(operationId)

Every processing 202 contains exactly operationId, operationType and status: "processing"; operationType is directRecharge. Full operation reads use 200.
A create that was refused and recorded as refused never produced a direct recharge: the read answers that recorded refusal (409 or 422) with Idempotency-Replayed: true, and nothing was charged. On a read, idempotency_conflict means no direct recharge of this application exists under the id.

Parameters

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

Request

Signed with your key. No body, no nonce.

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

Body: none.

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
Not found	`resource_not_found`	404
Insufficient balance	`insufficient_balance`	409
Price changed	`price_changed`	409
Direct recharge product unavailable	`direct_recharge_product_unavailable`	409
Amount outside limits	`amount_out_of_range`	422
Operation id already used	`idempotency_conflict`	409

Types

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`