Create an order
Creates an order and returns the `url` to send the buyer to. Returns 201 for a new order, and 200 if this `reference` already has one open. Send `amount`, `amount_minor`, or both. If both, they must agree at the currency's decimal places, or the order is refused with `amount_mismatch`. `success_url` and `cancel_url` are optional, and must be on an origin registered under Settings, Payment links. Needs the `receive` capability.
Authorization
KeyID Timestamp Nonce Signature Your key id, gyv_k_live_... or gyv_k_sandbox_....
In: header
Unix seconds. Must be within 5 minutes of our clock.
In: header
A unique value per request. Replays are rejected.
In: header
Ed25519 signature over the canonical string. See the Signing guide.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Your id for this order, and the idempotency key. Free to reuse once the order is closed.
What the buyer sees on the page.
The total as a decimal string, e.g. "150.00". More decimal places than the
currency has is refused.
The total in minor units. If sent with amount, the two must agree.
int64Three-letter code of the currency you price in.
How many. amount is still the total.
Price of one, in minor units.
int64Limit how the buyer can pay. Omit for btc_lightning, usdt and usdc.
btc_onchain is only offered when you list it.
Seconds the order stays payable. Omit it and the buyer gets a short window to pick an asset, then 1 hour for a stablecoin, 15 minutes for Lightning or 3 hours for on-chain Bitcoin. Money arriving after expiry is still credited.
Where to send the buyer after paying. Its origin must be registered in the dashboard. Optional.
uriSame rule as success_url.
uriYour data, returned on the order and in its webhooks. Up to 4KB.
Optional. The customer this order is for.
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/checkout/orders" \ -H "Content-Type: application/json" \ -d '{ "reference": "order_1001", "description": "Order #1001 at Kente & Co", "amount": "125.50", "amount_minor": 12550, "currency": "GHS", "success_url": "https://shop.example.com/checkout/thanks", "cancel_url": "https://shop.example.com/cart", "metadata": { "order_id": "1001" } }'{ "data": { "id": "7b1f9a2c-4e5d-4a8b-9c3f-2d6e1a4b7c90", "status": "open", "kind": "checkout", "reference": "order_1001", "description": "Order #1001 at Kente & Co", "amount": "125.50", "amount_minor": "12550", "currency": "GHS", "currency_decimals": 2, "quantity": 0, "unit_amount": "string", "unit_amount_minor": "string", "settled": { "asset": "USDT", "chain": "tron", "network": "onchain", "quoted": "8.120000", "quoted_minor": "8120000", "received": "8.120000", "received_minor": "8120000", "short_by": "string", "short_by_minor": "string", "over_by": "string", "over_by_minor": "string" }, "late": true, "url": "https://pay.gyvar.com/chk_live_7b1f9a2c-4e5d-4a8b-9c3f-2d6e1a4b7c90", "success_url": "http://example.com", "cancel_url": "http://example.com", "metadata": {}, "expires_at": "2019-08-24T14:15:22Z", "paid_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e" }}