Storefront API · Оформлення

Оформити замовлення

POSThttps://{store}/api/v1/checkout

Ще раз перевіряє весь кошик (наявність, ціни, доставку, правила магазину) й оформлює замовлення. Передайте суми, які бачив покупець: якщо кошик тим часом змінився, відповідь буде 422 і нічого не списується.

redirect_url — сторінка платіжного провайдера: відправте покупця туди; дані картки ніколи не проходять через ваш застосунок. Сторінка приймає оплату 30 хвилин. Без redirect_url замовлення вже оформлене (наприклад, оплата при отриманні).

Той самий Idempotency-Key повертає те саме замовлення замість другого — навіть після обриву зв’язку. Ключ, використаний для іншого кошика чи суми, дає 422 idempotency_key; для нової спроби потрібен новий ключ.

Токен кошика з POST /carts: X-Cart-Token: {token}.

Ідемпотентний. Потрібен заголовок Idempotency-Key: повтор із тим самим ключем повертає першу відповідь.

Тіло запиту application/json

expected_subtotalintegerобов'язкове

Сума товарів, яку бачив покупець (totals.subtotal), у копійках.

expected_totalintegerобов'язкове

Сума до сплати, яку бачив покупець (totals.total), у копійках.

payment_driverstring

Спосіб оплати; без нього — типовий для магазину.

payment_tokenstring

Лише для способів оплати, яким він потрібен.

contact_emailstring

Email для замовлення; без нього береться з адреси доставки.

notesstring

Коментар покупця, до 1000 символів.

marketing_opt_inboolean

true — запит на підписку на розсилку (з підтвердженням листом).

Приклад

{
    "expected_subtotal": 599900,
    "expected_total": 599900,
    "contact_email": "[email protected]",
    "notes": "Подзвоніть перед відправкою"
}

Відповіді

201Замовлення; redirect_url — якщо покупець платить онлайн.

{
    "data": {
        "id": "101",
        "reference": "2026-001045",
        "status": "awaiting-payment",
        "placed_at": null,
        "payment_driver": "app:com.storeforma.wayforpay",
        "redirect_url": "https://your-store.storeforma.shop/payments/8b1e…/start"
    }
}

422Кошик змінився, товар закінчився, доставка більше недоступна або ключ використано для іншого замовлення.

{
    "message": "Сума кошика змінилася.",
    "errors": {
        "checkout": [
            "Сума кошика змінилася. Перевірте кошик і спробуйте ще раз."
        ]
    }
}

401Немає X-Cart-Token, токен прострочений або кошик уже оформлено.

{
    "message": "A valid X-Cart-Token header is required.",
    "errors": {
        "cart_token": [
            "Кошик не знайдено, строк доступу минув або його вже оформлено."
        ]
    }
}

429Забагато запитів (створення кошика 20/хв з IP, запити кошика 120/хв, оформлення 10/хв).

{
    "message": "Too Many Attempts."
}