Buy a product over x402 in one call

The x402 rail: order creation, payment and delivery in a single request, repeated twice. Send the createOrder body with no payment header and the response is 402 carrying the x402 PaymentRequired document — in the PAYMENT-REQUIRED response header, which is the canonical v2 location, and mirrored in the body — with accepts[0].amount holding the exact atomic USDC amount for that item, plus an order block. Sign it and repeat the identical request with the PAYMENT-SIGNATURE header: the payment is verified and settled, then the order is fulfilled. Send an Idempotency-Key to make retries safe — without one it is derived from the request body, so an identical repeat resolves to the same order rather than buying twice. The settlement receipt comes back in PAYMENT-RESPONSE. This endpoint speaks x402 v2 by default and x402 v1 for clients that need it: send the v1 payload in X-PAYMENT, or ask for a v1 quote with X-PAYMENT-VERSION: 1 (or ?x402_version=1); v1 names the chain "base", puts the amount in accepts[].maxAmountRequired and returns its receipt in X-PAYMENT-RESPONSE. Calling it with no purchase named at all (empty body, or a bare GET) is answered with a 402 quoting the rail's floor and no order block — that is the probe form, not a buyable quote; name a product to get a real price.

post/api/v1/buy

Request

  • Base URL: https://kodshop.cloud
  • URL: https://kodshop.cloud/api/v1/buy
  • Auth: none declared

Headers

Idempotency-Keystring
PAYMENT-SIGNATUREstring

Base64 JSON x402 v2 PaymentPayload. Absent on the quoting call.

X-PAYMENTstring

Base64 JSON x402 v1 PaymentPayload, for clients that do not speak v2.

X-PAYMENT-VERSION'1' | '2'

Ask for a quote in a specific protocol version. Defaults to 2.

Request body

emailstring email required

Where the code / eSIM QR is delivered

product_type'giftcard' | 'topup' | 'esim' | 'phone_rental' | 'phone_rental_renew' required
product_idinteger

product_type=giftcard|topup: id from listProducts

item_idinteger

product_type=giftcard|topup: chosen denomination (items[i].id)

quantityinteger

Units of item_id. Optional — omitting it buys 1, including on the many voucher products whose fields[] declares quantity required. Send it only to buy several copies of one denomination; fields[] carries the allowed min/max.

account_numberstring

Top-ups: recipient account, when the product's fields require it

amountnumber

Variable-amount top-ups only

extraobject

Product-specific inputs that have no dedicated field. Any entry in the product's fields[] whose code is not quantity / account_number / amount goes here, keyed by that code — e.g. game top-ups that need {"zone_id": "1234"} or {"server_id": "eu"}.

bundle_namestring

product_type=esim

country_codestring

product_type=esim / phone_rental

Response

Paid and fulfilled — delivery carries the code, esim or phone

idstring
statusstring
access_tokenstring
status_urlstring uri

Poll this while status is not completed

pricenumber

Order total in the brand currency (RUB)

currencystring
productobject
deliveryobject

Gift card code(s) once completed

esimobject

ICCID + QR payload for eSIM orders

phoneobject

Rented number for phone_rental orders

fulfilled_atstring date-time
retry_after_secondsinteger

Present on 202 — how long to wait before polling status_url

errorstring

Present on 502

Changes

No recorded changes to this operation across all 1 revision of this API.