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 order

Staff-set limits it counts towardAll requests, Orders

.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, 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.

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	At least 1 and at most the per-order maximum (100 by default), and within the card’s own minimum and maximum.
`expectedUnitPrice`required	Money	The card’s `unitPrice` exactly as the catalogue showed it for this wallet.
`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
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 is signed by Anis; the SDKs check it before you see it.

Refusals

Every refusal 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
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
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	At least 1 and at most the per-order maximum (100 by default), and within the card’s own minimum and maximum.
`expectedUnitPrice`required	Money	The card’s `unitPrice` exactly as the catalogue showed it for this wallet.
`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 / always present	string	A decimal string with exactly three decimals, such as `"10.500"` — never a JSON number.
`currency`required / always present	string	The currency code, such as `LYD`: always the wallet’s 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 tell Anis. 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`	UUID	The catalogue card bought.
`quantity`	integer	How many cards.
`total`	Money	What the order cost.
`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.