> For the complete documentation index, see [llms.txt](https://docs.xpayconnect.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xpayconnect.io/documentation/eng/orders/create.md). # Create Order (PAYIN-FIAT) > Method: **POST** > > Path: **/merchant/createOrder** ## Request Parameters ```json { "order_id": "01a00c1a-9f0e-7e42-b8a5-2a1c3d4e5f6a", "amount": 2300, "amountUp": 120, "amountDown": 10, "type": "sim", "success_callback_url": "http://test.com/api/order/success", "merchant_id": "exMerchant", "client_id": "99999999", "currency": "RUB", "convertToUsdt": false, "comment": "Заказ #12345" } ``` | Field | Type | Required | Description | | -------------------------- | ----------------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **amount** | integer | ✓ | Payment amount in the merchant's currency. See [Currencies](/documentation/eng/reference/currencies.md) | | **type** | string (enum) | ✓ | [Payment Methods](/documentation/eng/reference/payment-methods.md) | | **merchant\_id** | string | ✓ | Unique merchant name | | **order\_id** | string | — | Unique identifier on the merchant side (external\_id). String format is arbitrary — we recommend a UUID (v4 or v7) to guarantee uniqueness across your systems. If `null` is sent, the identifier is generated on our side | | **direction** | string (enum) | — | Defaults to accepting a payment (PAYIN). Pass `PAYOUT` for a payout — parameters and response are different, see [Creating a Payout](/documentation/eng/orders/payout.md) | | **success\_callback\_url** | string | — | Merchant URL for receiving the webhook when the payment completes | | **client\_id** | string | — | Client ID in the merchant's system. Used to identify the payer | | **client\_registered\_at** | string (ISO-8601) | — | Client registration date in the merchant's system — anti-fraud signal (account age at the time of the order). An invalid or missing value is ignored — the order is created without it | | **client\_orders\_count** | integer (≥0) | — | Total number of orders the client has had on the merchant side over all time, value as of order creation. An invalid value is ignored | | **client\_paid\_count** | integer (≥0) | — | Total number of payments the client has made on the merchant side over all time, value as of order creation. Together with `client_orders_count` displayed as `client_paid_count/client_orders_count`, e.g. **10/20** (10 payments out of 20 orders). An invalid value is ignored | | **currency** | string (enum) | — | Order currency. See [Currencies](/documentation/eng/reference/currencies.md). Default: `RUB` | | **convertToUsdt** | boolean | — | Convert the credit to USDT. Requires access granted by the administration. Default: `false` | | **amountUp** | integer (RUB) | — | Allowed upward amount deviation, in rubles, for [disambiguation](#unikalizaciya-summy). RUB PAYIN only | | **amountDown** | integer (RUB) | — | Allowed downward amount deviation, in rubles, for [disambiguation](#unikalizaciya-summy). RUB PAYIN only | | **comment** | string | — | Arbitrary comment from the merchant. Maximum 500 characters. Saved in the order and accessible in the admin panel | ### Request Examples {% tabs %} {% tab title="JavaScript" %} ```javascript const crypto = require('crypto'); const axios = require('axios'); const apiKey = 'YOUR_API_KEY'; const body = { order_id: '01a00c1a-9f0e-7e42-b8a5-2a1c3d4e5f6a', amount: 2300, type: 'sim', success_callback_url: 'http://test.com/api/order/success', merchant_id: 'exMerchant', client_id: '99999999', }; const bodyStr = JSON.stringify(body); const xApiKey = crypto.createHash('sha256').update(`${apiKey}|${bodyStr}`).digest('hex'); const { data } = await axios.post('https://api.xpayconnect.io/merchant/createOrder', body, { headers: { 'Content-Type': 'application/json', 'client-api-key': apiKey, 'x-api-key': xApiKey, }, }); ``` {% endtab %} {% tab title="Python" %} ```python import hashlib import json import requests api_key = 'YOUR_API_KEY' body = { 'order_id': '01a00c1a-9f0e-7e42-b8a5-2a1c3d4e5f6a', 'amount': 2300, 'type': 'sim', 'success_callback_url': 'http://test.com/api/order/success', 'merchant_id': 'exMerchant', 'client_id': '99999999', } body_str = json.dumps(body, separators=(',', ':')) x_api_key = hashlib.sha256(f'{api_key}|{body_str}'.encode()).hexdigest() resp = requests.post('https://api.xpayconnect.io/merchant/createOrder', json=body, headers={ 'Content-Type': 'application/json', 'client-api-key': api_key, 'x-api-key': x_api_key, }) data = resp.json() ``` {% endtab %} {% tab title="PHP" %} ```php $apiKey = 'YOUR_API_KEY'; $body = [ 'order_id' => '01a00c1a-9f0e-7e42-b8a5-2a1c3d4e5f6a', 'amount' => 2300, 'type' => 'sim', 'success_callback_url' => 'http://test.com/api/order/success', 'merchant_id' => 'exMerchant', 'client_id' => '99999999', ]; $bodyStr = json_encode($body, JSON_UNESCAPED_UNICODE); $xApiKey = hash('sha256', $apiKey . '|' . $bodyStr); $ch = curl_init('https://api.xpayconnect.io/merchant/createOrder'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => $bodyStr, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'client-api-key: ' . $apiKey, 'x-api-key: ' . $xApiKey, ], ]); $response = json_decode(curl_exec($ch), true); curl_close($ch); ``` {% endtab %} {% endtabs %} *** ## Response ```json { "ok": true, "id": "lux01993328-a828-7581-b3a9-e712a6a0e88c", "payment_id": "01a00c1a-9f0e-7e42-b8a5-2a1c3d4e5f6a", "status": "pending", "usdtAmount": 29.37, "usdtAmountAfterFee": 25.5, "amountAfterFee": 2001, "exchangeRate": 78.3, "currency": "RUB", "payment_details": { "address": "+79221110500", "bank": "Сбербанк", "holder_name": "Имя Фамилия", "type": "sim", "amount": "2300" } } ``` | Field | Type | Description | | ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ok** | boolean | `true` when payment details are successfully provided | | **id** | string (uuid) | Unique identifier of the internal system (internal\_id) | | **payment\_id** | string | The **order\_id** passed by the merchant at creation, or generated by the system if `null` was passed | | **status** | string (enum) | Payment status: `pending`, `success`, `error` | | **usdtAmount** | number, null | Estimated amount in USDT at the `exchangeRate` rate, calculated **WITHOUT** the merchant's fee (`amount / exchangeRate`). Populated only when `convertToUsdt: true` | | **usdtAmountAfterFee** | number, null | Estimated USDT amount to be credited to the merchant's USDT balance **after** fee deduction: `(amount − fee) / exchangeRate`. At creation — an estimate; the exact amount is fixed upon `success`. Populated only when `convertToUsdt: true` | | **amountAfterFee** | number | Amount in fiat currency after the merchant's fee deduction. Always returned, including without `convertToUsdt`. Useful for merchants on a fiat balance to see in advance exactly how much will be credited after the order succeeds | | **exchangeRate** | number, null | Fixed USDT/`currency` exchange rate | | **currency** | string | Order currency | | **payment\_details** | object | Information about the provided payment details | | ↳ **address** | string | Payment details for making the payment | | ↳ **bank** | string | Bank name | | ↳ **holder\_name** | string | Name of the payment details holder | | ↳ **type** | string (enum) | [Payment Method](/documentation/eng/reference/payment-methods.md) | | ↳ **amount** | string | Final amount to be paid by the client in `currency`. May differ from the amount passed by the merchant — see [Amount Disambiguation](#unikalizaciya-summy) | | ↳ **cryptoAmount** | string, optional | Exact amount to pay in cryptocurrency — present **only for crypto methods** (`usdt_trc20`, etc.). If the amount has not yet been calculated at the time of the response, the field is absent — in this case it can be retrieved via [`GET /merchant/order/:id`](/documentation/eng/orders/info.md) | | ↳ **form\_url** | string, optional | Link to the payment form for payment and receipt upload. Present for methods that require a receipt (`card_pdf`, `sbp_pdf`, `qr_smart`). See the "Methods with PDF Receipt" section below | | ↳ **emv** | string, optional | EMVCo QR-payload (scan-to-pay string, e.g. VietQR) — not present for all methods. The client renders the QR on their side from this string | *** ## Amount Disambiguation To eliminate collisions when matching bank notifications to orders, the system can automatically shift the amount within a specified range so that each active order has a unique value. ### How It Works If there is already an active pending order with the same amount in the system, the new order's amount will be shifted within the range `[amount - amountDown, amount + amountUp]` to the first free value. If all values in the range are taken — the original amount is returned. {% hint style="info" %} The `amount` field in the response's `payment_details` is the **final amount** the client must pay. It may differ from the requested amount. {% endhint %} ### Configuration Disambiguation works only for the `RUB` currency and only for PAYIN orders. It is enabled automatically if: * `amountUp > 0` or `amountDown > 0` is passed in the request, or * Default values are configured for the merchant Priority: values from the request take priority over the default settings. {% hint style="warning" %} If both deviations are `0` or not specified — disambiguation is disabled and the amount is returned as is. {% endhint %} ### Example The merchant sends: ```json { "amount": 5000, "amountUp": 100, "amountDown": 10 } ``` If there is already an active order for 5000 RUB in the system, the response will return: ```json { "payment_details": { "amount": "5001", ... } } ``` The client must pay exactly `5001 RUB` — this allows the system to unambiguously match the incoming payment with this order. *** ## Methods with PDF Receipt (card\_pdf / sbp\_pdf / qr\_smart) For the [`card_pdf`, `sbp_pdf` and `qr_smart`](/documentation/eng/reference/payment-methods.md) methods, an additional field is added to the `payment_details` object: * **form\_url** — a link to the payment form where the client pays the order and uploads the receipt. For `qr_smart`, the form also renders a QR code from the data in `address`. In this case, `address` **remains the actual payment detail** (card number / phone), unlike standard methods. The merchant can either show the client the detail from `address` directly, or redirect them to `form_url`. Example response for `card_pdf`: ```json { "ok": true, "id": "lux01993328-a828-7581-b3a9-e712a6a0e88c", "payment_id": "01a00c1a-9f0e-7e42-b8a5-2a1c3d4e5f6a", "status": "pending", "amountAfterFee": 2001, "currency": "RUB", "payment_details": { "address": "2200 1234 5678 9010", "bank": "Сбербанк", "holder_name": "Имя Фамилия", "type": "card_pdf", "amount": "2300", "form_url": "https://api.xpayconnect.io/form/lux01993328-a828-7581-b3a9-e712a6a0e88c" } } ``` {% hint style="info" %} After the client has paid, the receipt must be attached to the order — see [Receipt Upload](/documentation/eng/orders/receipt-upload.md). {% endhint %} *** ## Payment Methods The full list of available methods is on a separate page: [Payment Methods](/documentation/eng/reference/payment-methods.md).