---
title: "Buy a product over x402 in one call"
method: POST
path: "/api/v1/buy"
---

# Buy a product over x402 in one call

`POST /api/v1/buy`

## Request

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

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.

## Headers

- `Idempotency-Key` string
- `PAYMENT-SIGNATURE` string
- `X-PAYMENT` string
- `X-PAYMENT-VERSION` '1' | '2'

## Request body

- CreateOrderRequest
  - `email` string, email, required: Where the code / eSIM QR is delivered
  - `product_type` 'giftcard' | 'topup' | 'esim' | 'phone_rental' | 'phone_rental_renew', required
  - `product_id` integer: product_type=giftcard|topup: id from listProducts
  - `item_id` integer: product_type=giftcard|topup: chosen denomination (items[i].id)
  - `quantity` integer: 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_number` string: Top-ups: recipient account, when the product's fields require it
  - `amount` number: Variable-amount top-ups only
  - `extra` object: 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_name` string: product_type=esim
  - `country_code` string: product_type=esim / phone_rental

## Response `200`

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

- X402OrderResult
  - `id` string
  - `status` string
  - `access_token` string
  - `status_url` string, uri: Poll this while status is not completed
  - `price` number: Order total in the brand currency (RUB)
  - `currency` string
  - `product` object
  - `delivery` object: Gift card code(s) once completed
  - `esim` object: ICCID + QR payload for eSIM orders
  - `phone` object: Rented number for phone_rental orders
  - `fulfilled_at` string, date-time
  - `retry_after_seconds` integer: Present on 202 — how long to wait before polling status_url
  - `error` string: Present on 502

## Other responses

- `202`: Paid, fulfilment still running — poll order.status_url
- `400`: Invalid request or malformed payment header
- `402`: Payment required — accepts[] is priced for this exact order
- `409`: Product not orderable — nothing was charged
- `502`: Paid but fulfilment failed — refunds are handled by a human at support@support.kodshop.cloud
- `503`: Payment could not be verified or settled — nothing was charged

---

[API](https://skmtc.dev/kodshop/apis/kodshop-public-api.md) · [All operations](https://skmtc.dev/kodshop/apis/kodshop-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kodshop/apis/kodshop-public-api/revisions/63f1271e61ea?raw)