Creating an order
An order is the central object: it holds the amount, the basket, the buyer and the payment link. To create one, call:
- method:
POST - resource:
/v3/billing/api/order/order - request body — a CreateOrderRequest object
- response body — an OrderResponse object
- possible errors
Request and response example
HTTP
POST /v3/billing/api/order/order
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json
Request body:
{
"merchantId": "01771534-196a-1105-839a-82422289d6d9",
"merchantOrderId": "m-1608560079",
"amount": 366.00,
"successUrl": "https://shop.example.com/order/4412?result=success",
"failUrl": "https://shop.example.com/order/4412?result=fail",
"returnUrl": "https://shop.example.com/order/4412?result=return",
"vatAmount": 66.00,
"basketItems": [
{
"sku": "5fe0adcfa7fb4",
"name": "Room booking",
"measure": "pcs",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 3,
"amount": 122.00,
"amountWoVat": 100.00,
"totalAmount": 366.00,
"totalVatAmount": 66.00,
"vatCode": "RUS_VAT22",
"type": "service",
"paymentType": "full_prepayment"
}
],
"metaData": {
"@type": "LodgingReservation",
"reservationId": "abc456",
"reservationStatus": "https://schema.org/ReservationConfirmed",
"underName": {
"@type": "Person",
"name": "John Smith"
},
"reservationFor": {
"@type": "LodgingBusiness",
"name": "Hilton San Francisco Union Square",
"address": {
"@type": "PostalAddress",
"streetAddress": "333 O'Farrell St",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94102",
"addressCountry": "US"
},
"telephone": "415-771-1400"
},
"checkinTime": "2026-09-14T16:00:00-08:00",
"checkoutTime": "2026-09-16T11:00:00-08:00"
},
"expirationDate": "2026-09-16T00:00:00+00:00",
"languageId": "en",
"currencyId": "RUB",
"description": "Hotel room payment",
"customer": {
"type": "legal",
"name": "Romashka LLC",
"phone": "79001112233",
"email": "buh@example.invbox.ru",
"vatNumber": "7710044140",
"registrationAddress": "190000, Saint Petersburg, Nevsky prospect 147, office 321"
}
}
CURL
curl -L -X POST 'https://api.invoicebox.ru/v3/billing/api/order/order' \
-H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp 1.0' \
-H 'Accept: application/json' \
-d '{
"merchantId": "01771534-196a-1105-839a-82422289d6d9",
"merchantOrderId": "m-1608560079",
"amount": 366.00,
"vatAmount": 66.00,
"currencyId": "RUB",
"languageId": "en",
"description": "Hotel room payment",
"expirationDate": "2026-09-16T00:00:00+00:00",
"successUrl": "https://shop.example.com/order/4412?result=success",
"failUrl": "https://shop.example.com/order/4412?result=fail",
"returnUrl": "https://shop.example.com/order/4412?result=return",
"basketItems": [
{
"sku": "5fe0adcfa7fb4",
"name": "Room booking",
"measure": "pcs",
"measureCode": "796",
"grossWeight": 0,
"netWeight": 0,
"quantity": 3,
"amount": 122.00,
"amountWoVat": 100.00,
"totalAmount": 366.00,
"totalVatAmount": 66.00,
"vatCode": "RUS_VAT22",
"type": "service",
"paymentType": "full_prepayment"
}
],
"customer": {
"type": "legal",
"name": "Romashka LLC",
"phone": "79001112233",
"email": "buh@example.invbox.ru",
"vatNumber": "7710044140"
}
}'
CreateOrderRequest
| Property | Required | Type | Description | Example |
|---|---|---|---|---|
| description | yes | string(1000) | Order description | Hotel room payment |
| merchantId | yes | string(36) | Merchant identifier | 01771534-1a57-f184-dee3-ebeb91dded76 |
| merchantOrderId | yes | string(256) | Order identifier in the merchant's own system; must be unique | O-12345 |
| merchantOrderIdVisible | no | string(256) | Order number shown on the payment page. Falls back to merchantOrderId | 111TN22-33 |
| amount | yes | float | Order total; no limits | 19658.45 |
| vatAmount | yes | float | VAT amount | 156.56 |
| currencyId | yes | string(3) enum | Currency code per ISO 4217 | RUB, USD, EUR, GBP |
| languageId | no | string(2) enum | Payment page language | ru, en |
| expirationDate | yes | datetime | How long the order stays payable | 2026-09-14T00:00:00+00:00 |
| basketItems | yes | array of BasketItem | Order basket | |
| metaData | no | object | Additional order data | |
| customer | yes | Customer | Buyer details | |
| notificationUrl | no | string(1000) | URL for status notifications; defaults to the URL in the merchant settings | |
| successUrl | no | string(1000) | Where to return the buyer after a successful payment | |
| failUrl | no | string(1000) | Where to return the buyer after a failed payment | |
| returnUrl | no | string(1000) | Where to return the buyer who left the payment page | |
| invoiceSetting | no | InvoiceSetting | Extra payment settings | |
| orderSetting | no | OrderSetting | Extra order settings | |
| parentId | no | string(36) | Identifier of the base order — used for correction orders | 01771534-196a-1105-839a-82422289d6d9 |
| orderContainerId | no | string(36) | Identifier of the main order — used to add an order to an existing invoice | 01771534-196a-1105-839a-82422289d6d9 |
| shopId | no | string(36) | Identifier of the linked shop or marketplace | 06581534-196a-1105-839a-82422289d6d8 |
| userAccountId | no | string(36) | Loyalty programme identifier | 06581534-196a-1105-839a-82422289d6d7 |
| processable | no | bool | Whether the order is processable | true, false |
| subtype | no | string(36) | Order subtype: order — a regular order (default), hold — an order with a hold | order, hold |
OrderResponse
Repeats every property of CreateOrderRequest and adds:
| Property | Required | Type | Description | Example |
|---|---|---|---|---|
| id | yes | string(36) | Order identifier in Invoicebox | 01771534-1a57-f184-dee3-ebeb91dded75 |
| paymentUrl | yes | string(1000) | Link to the payment gateway | |
| createdAt | yes | datetime | When the order was created | 2026-09-14T00:00:00+00:00 |
| status | yes | string(50) enum | Order status: created — awaiting payment, completed — paid, hold — funds reserved | completed, hold |
| paidAt | no | datetime | When the order was paid, if it was | 2026-09-14T00:00:00+00:00 |
| paymentInfo | no | PaymentInfo | Payment and payer details | {"maskedPan": "220024**0954", "expiration": "202601", "paymentSystem": "MIR", "cardholderName": "CARDHOLDER NAME"} |
| holdTill | no | datetime | When reserved funds are captured, for orders with subtype hold | 2026-09-14T00:00:00+00:00 |
Important
Depending on your scenario, paymentUrl is either a link you redirect the browser to, or a value you
encode in a QR code for the buyer to scan with a camera or the Invoicebox app.
Customer
| Property | Required | Type | Description | Example |
|---|---|---|---|---|
| type | no | string(10) enum | Buyer type | legal — a company or sole trader, private — an individual |
| name | no | string(500) | Name | Romashka LLC |
| phone | no | string(100) | Phone number | 79001112233 |
| no | string(100) | buh@example.invbox.ru | ||
| vatNumber | no | string(20) | Taxpayer number (INN) | 7710044140 |
| taxRegistrationReasonCode | no | string(9) | Tax registration reason code (KPP) | 770201001 |
| registrationAddress | no | string(1000) | Registered address including the postal code | 190000, Saint Petersburg, Nevsky prospect 147, office 321 |
BasketItem
The order basket. Read the rules for naming the items carefully: what you send here is what the buyer sees in the fiscal receipt.
| Property | Required | Type | Description |
|---|---|---|---|
| sku | yes | string(36) | Stock keeping unit, for example 5fe0adcfa7fb4 |
| name | yes | string(300) | Item name, for example Room booking |
| type | yes | string(10) | Item type per the reference, or service, or commodity |
| groupName | no | string(500) | Item group name, used when building the closing documents |
| measure | yes | string(10) | Unit of measure (in Russia — per OKEI), for example pcs |
| measureCode | yes | string(4) | Unit of measure code (in Russia — per OKEI), for example 796 |
| originCountry | no | string(20) | Country of origin, for example Russia |
| originCountryCode | no | string(4) | Country of origin code, for example 643 for Russia |
| grossWeight | no | float | Gross weight, for example 125.45 |
| netWeight | no | float | Net weight, for example 125.45 |
| quantity | yes | float | Quantity, for example 3 |
| amount | yes | float | Unit price, for example 100.55; no limits |
| amountWoVat | yes | float | Unit price excluding VAT |
| totalAmount | yes | float | Total for all units including VAT, for example 123.55 |
| totalVatAmount | yes | float | Total VAT, for example 23 |
| excise | no | float | Excise duty, for example 10.00 |
| gtdNumber | no | string(23) | Customs declaration number |
| vatCode | yes | string(20) enum | Invoicebox VAT rate code, see the VAT rates reference |
| serviceDate | no | date | Date the service was rendered, if the item is a service, for example 2026-09-14 |
| paymentType | yes | string(20) enum | Payment type: full_prepayment, prepayment, advance, full_payment |
| categoryType | required with category | string(20) enum | Category reference: merchantHonestSignMap (the merchant's own categories) or honestSign (Honest Sign) |
| category | no | string(20) enum | Product group in the merchant's or Honest Sign reference: milk, water and so on |
| metaData | no | object | Additional basket item data |
InvoiceSetting
| Property | Required | Type | Description | Example |
|---|---|---|---|---|
| customerLocked | no | bool | Forbid editing every payer detail | true to forbid; false by default |
| customerLockedFields | no | array<string> | Which Customer fields to lock on the payment page | ['type', 'name', 'phone', 'email', 'vatNumber', 'registrationAddress'] |
| paymentMethodIdLocked | no | bool | Forbid changing the payment method | true to forbid; false by default |
| paymentMethodId | no | int | Identifier of the preselected payment method | 123 |
| paymentMethodCode | no | string | Code of the preselected payment method. Publicly available: invoice — by invoice, invoice-rtp — invoice via Request to Pay, acquiring — card, sbp — SBP. Other methods are provided on request for a specific integration | invoice, invoice-rtp, acquiring, sbp |
| paymentMethodAutosubmit | no | bool | Send the buyer straight to the payment system from paymentMethodCode, skipping the Invoicebox payment page. Requires a fully filled Customer | true |
| deliveryAddress | no | string | Full delivery address | Moscow region, Khimki, Vashutinskoe shosse 6 |
| savePaymentData | no | bool | Store the card details for recurring payments | true, false |
| clientId | no | string | Client identifier in the merchant's system | 123, c-102322 |
OrderSetting
| Property | Required | Type | Description |
|---|---|---|---|
| roundPolicy | no | string(20) enum | How the order total is rounded. strict — no rounding, exact match; none — no rounding, allowed when quantity * amount <= totalAmount; floor — down to the nearest integer; ceil — up to the nearest integer; halfUp — 0.50 rounds up; halfDown — 0.50 rounds down |
PaymentInfo
| Property | Required | Type | Description |
|---|---|---|---|
| paymentToken | no | string | Payment token |
| cardholderName | no | string | Cardholder name |
| expiration | no | string | Card expiry |
| maskedPan | no | string | Masked card number |
| paymentSystem | no | string | Card payment system |