Place an order

POST/v1/wallets/{walletId}/orders

Buys cards from a wallet, under an operation id you choose and keep. The same id sent again never buys twice: it resumes the same order.

Permissionorders:create

AuthenticationSigned purchase

Anis’s answerSigned

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

.NET SDKanis.Orders.CreateAsync(walletId, operationId, order) / ResumeAsync(...)

201: the order completed, and this answer carries the card codes. Store them first.
200: the answer a resume receives when the first answer was lost. If it carries card codes, it is the first time you see them — store them.
An answer marked Idempotency-Replayed: true repeats an order whose outcome was already sent: it carries the order (your reference, the card, the quantity and the total), not the codes. If you never received that first answer — a timeout — the codes were in it: reveal them with the order’s invoice id, which needs cards:reveal.
202: accepted, no outcome yet. Send the same order again after Retry-After.
The order body must be at most 8,192 bytes (8 KB), in UTF-8 — a Content-Type naming any other charset is refused as HTTP 422, validation_failed. A larger body is refused as HTTP 422, validation_failed.
HTTP 429, spending_limit_exceeded: the order was not placed because it would exceed the application’s spending cap for this window. Wait until the window resets, as given by Retry-After, then place a new order with a new operation id; ask Anis staff to change the cap if needed.

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: CreateOrderRequest, as JSON.

Field	Type	Notes
`externalReference`	string	Your own reference, 1 to 100 characters: Latin letters and digits, space and `- _ . : / #`.
`cardId`required	UUID	The catalogue card to buy.
`quantity`required	integer	From 1 to the platform order limit of 100.
`expectedUnitPrice`required	Money	The card’s `unitPrice` exactly as the catalogue showed it for this wallet, using the shared `Money` shape.
`expectedTotal`required	Money	`expectedUnitPrice` times `quantity`, exactly — computed without floating point.
`useAllowedDebt`	boolean	Set to `true` only if you consent to use the account’s allowed debt. Defaults to `false` and is never switched on for you.

Responses

Status	Meaning	Body
200	Success.	Order
201	The order completed.	Order
202	Accepted — no outcome yet.	Order
400	Refused: the signed request is badly built.	Problem
401	Refused: not authenticated.	Problem
402	Refused: needs consent to use allowed debt.	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
Replay detected	`replay_detected`	409
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
Validation failed	`validation_failed`	422
Currency not supported	`currency_not_supported`	422
Operation id already used	`idempotency_conflict`	409
Allowed-debt consent required	`allowed_debt_consent_required`	402
Insufficient balance	`insufficient_balance`	409
Purchase not allowed	`purchase_not_allowed`	403
Order refused	`purchase_not_allowed`	409
Business subscription required	`business_subscription_required`	409
Wallet disabled	`wallet_disabled`	409
Wallet expired	`wallet_expired`	409
Card unavailable	`card_unavailable`	409
Quantity unavailable	`quantity_unavailable`	409
Price changed	`price_changed`	409
Spending allowance used up	`owner_limit_exceeded`	409
Daily limit reached	`daily_limit_exceeded`	429
Spending cap reached	`spending_limit_exceeded`	429
Service unavailable	`dependency_unavailable`	503
Request timeout	`request_timeout`	504
Internal error	`internal_error`	500

Types

CreateOrderRequest

Field	Type	Notes
`externalReference`	string	Your own reference, 1 to 100 characters: Latin letters and digits, space and `- _ . : / #`.
`cardId`required	UUID	The catalogue card to buy.
`quantity`required	integer	From 1 to the platform order limit of 100.
`expectedUnitPrice`required	Money	The card’s `unitPrice` exactly as the catalogue showed it for this wallet, using the shared `Money` shape.
`expectedTotal`required	Money	`expectedUnitPrice` times `quantity`, exactly — computed without floating point.
`useAllowedDebt`	boolean	Set to `true` only if you consent to use the account’s allowed debt. Defaults to `false` and is never switched on for you.

Money

Field	Type	Notes
`amount`required	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`required	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.

Order

Field	Type	Notes
`operationId`always present	UUID	The operation id you chose and sent as `Idempotency-Key`.
`status`always present	string	`processing`: accepted, no outcome yet. `completed`: bought. `failed`: refused by a business rule, nothing bought. `recoveryExhausted`: Anis could not learn the outcome yet — it may have completed; keep resuming slowly and write to support@anis.ly with the operation id. Values: `processing`, `recoveryExhausted`, `completed`, `failed`
`invoiceId`	UUID	The invoice the cards are on. Use it to reveal them again later.
`walletId`	UUID	The wallet the order was paid from.
`cardId`	any	The catalogue card ordered. On every answer for the order — the first one, a repeat of it and a read.
`quantity`	integer	How many cards were ordered. On every answer for the order, a repeat and a read included.
`total`	any	What the order cost. On every answer whose `status` is `completed`, a repeat and a read included; absent while it is `processing` or after it `failed`.
`externalReference`	string	Your own reference, exactly as you sent it. On every answer for the order, a repeat and a read included — it tells you which of your sales this is. Absent when the order had none.
`failureCode`	string	Why the order failed: the refusal code Anis recorded, one of the Error codes. Only on a read of an order whose `status` is `failed`. Absent when that refusal has no public code.
`codesWithheld`	boolean	`true` only on the answer that first reports an order that is paid and complete but whose codes could not be released. Do not buy it again, and write to support@anis.ly with the operation id. Never `false`: on every other answer it is absent, and on a repeat or a read that means “not stated”.
`soldCards`	list of RevealedCredential	The card codes. Present only on the answer that FIRST reports the order completed — store them before anything else.
`completedAt`	string (date-time)	When the order completed.

RevealedCredential

Field	Type	Notes
`soldCardId`always present	UUID	The sold card these codes belong to.
`serialNumber`	string	The card’s serial number. A secret: store it where you keep secrets and never log it.
`voucher`	string	The card’s voucher code. A secret: store it where you keep secrets and never log it.
`revealedAt`	string (date-time)	When it was revealed.
`expiryDate`	string (date)	The last day the card can be used, as `yyyy-MM-dd`. Tell your end customer. Absent when the card has none.
`invoiceId`	any	The invoice the card is on. Also inside an order’s `soldCards`.
`card`	CardSummary	The catalogue card that was sold, so you know which card these codes are for. Also inside an order’s `soldCards`.
`purchasedAt`	string (date-time)	When the card was bought. Also inside an order’s `soldCards`.

CardSummary

Field	Type	Notes
`id`	UUID	The catalogue card’s id.
`name`	LocalizedText	The card name in Arabic and English; empty localized text is omitted.
`faceValue`	string	Optional printed value; absent when empty.
`logo`	string	Optional absolute URL of the subcategory logo; absent when empty.
`subcategory`	object	The card’s subcategory, with id and localized name.
`subcategory.id`	UUID	The subcategory’s id.
`subcategory.name`	LocalizedText	The subcategory’s name in Arabic and English.
`category`	object	The card’s category, with id and localized name.
`category.id`	UUID	The category’s id.
`category.name`	LocalizedText	The category’s name in Arabic and English.

LocalizedText

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