Быстрый старт: первый счёт за 5 минут

Проверьте доступ

Демо-токен уже подставлен — метод авторизации вернёт идентификатор пользователя.

curl -X GET 'https://api.invoicebox.ru/v3/security/api/auth/auth' \
  -H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e' \
  -H 'User-Agent: MyApp 1.0'

Выставьте счёт

Один запрос создаёт заказ и возвращает paymentUrl — ссылку, которую вы отправляете покупателю.

curl -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' \
  -d '{
  "merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "merchantOrderId": "demo-order-1785862862042",
  "amount": 12000,
  "vatAmount": 0,
  "currencyId": "RUB",
  "languageId": "ru",
  "description": "Оплата бронирования № 4412",
  "expirationDate": "2026-08-05T17:01:02+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": "room-deluxe",
      "name": "Проживание в номере «Делюкс», 2 ночи",
      "measure": "шт",
      "measureCode": "796",
      "quantity": 1,
      "amount": 12000,
      "amountWoVat": 12000,
      "totalAmount": 12000,
      "totalVatAmount": 0,
      "vatCode": "RUS_VAT0",
      "type": "service",
      "paymentType": "full_prepayment"
    }
  ],
  "customer": {
    "type": "legal",
    "name": "ООО «Ромашка»",
    "vatNumber": "7701234560",
    "taxRegistrationReasonCode": "770101001",
    "phone": "79001112233",
    "email": "buh@example.invbox.ru"
  }
}'

Хотите выполнить без копирования — нажмите «Выполнить» на странице Создание заказа.

Примите уведомление об оплате

Когда покупатель оплатит, Инвойсбокс отправит POST-уведомление на ваш URL. Проверьте подпись и ответьте HTTP 200 с телом {"status":"success"} — иначе уведомление придёт повторно.

// Псевдокод обработчика
const signatureOk = verifyHmac(request.rawBody, request.headers['x-signature'], SIGN_KEY);
// Внимание: код ответа всегда 200 — отказ передаётся телом, а не HTTP-кодом
if (!signatureOk) return response(200, { status: 'error', code: 'signature_error' });
if (request.body.status !== 'completed') return response(200, { status: 'success' });
if (!amountMatches(request.body)) return response(200, { status: 'error', code: 'order_wrong_amount' });
markOrderPaid(request.body.merchantOrderId); // идемпотентно: то же уведомление может прийти снова
return response(200, { status: 'success' });

Подробности и примеры проверки подписи — Уведомление по умолчанию.

Проверить шаг можно, ничего не поднимая. Демо-заказ, созданный кнопкой «Выполнить» — на странице создания заказа или в демо-сценарии, — уходит с адресом уведомления портала. Оплатите его на платёжной странице (на демо-контуре деньги не списываются), и ниже появится то, что прислал Инвойсбокс, вместе с проверкой подписи.

Ключ подписи демо-магазина — 5a3797956281681be7cbb33ffc390ea1, метод hash_hmac, алгоритм sha1: с ними тот же расчёт можно повторить у себя. Свой ключ и адрес уведомлений задаются в личном кабинете; на localhost уведомление не придёт — нужен публичный адрес по HTTPS. Пока обработчика нет, статус заказа читают запросом — Получение заказа.