API Reference

Оплата

Створення платежу за квитки з обовʼязковим Idempotency-Key і перевірка статусу замовлення.

POST/checkout · дозвіл checkout:write

Створює платіж і повертає посилання на оплату. Ведіть покупця за цим посиланням, а далі стежте за статусом замовлення. Після успішної оплати ми самі надішлемо квиток на вказану пошту.

Запит

cURL

curl -X POST https://aoa.com.ua/api/v1/checkout \
  -H "Authorization: Bearer aoa_live_…" \
  -H "Idempotency-Key: order-2026-07-30-a1b2c3-0042" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "a1b2c3",
    "tickets": [
      { "ticketTypeId": "clx9ticket001", "quantity": 2 }
    ],
    "buyer": {
      "email": "ivan@example.com",
      "name": "Іван Петренко",
      "phone": "+380671234567"
    },
    "reservationId": "rsv_Xk3mQp7vR2nT8wL5yB1zC4dA"
  }'

Поле	Обовʼязкове	Опис
`eventId`	Так	Ідентифікатор події.
`tickets`	Так	Позиції з ticketTypeId і quantity (1–20 на тип).
`buyer.email`	Так	Сюди прийде квиток. Перевіряйте адресу на своєму боці.
`buyer.name`	Так	Імʼя покупця.
`buyer.phone`	Ні	Телефон покупця.
`couponCode`	Ні	Промокод. Неіснуючий або протермінований код дає помилку, а не повну ціну.
`reservationId`	Ні	Резерв із /reservations. Місця перетікають у платіж.

Idempotency-Key обовʼязковий

Заголовок Idempotency-Key (мінімум 8 символів) захищає від подвійного списання, якщо мережа обірвалась і ви не знаєте, чи дійшов запит. Повторний запит із тим самим ключем поверне ту саму відповідь замість другого платежу:

JSON

{
  "data": {
    "paymentId": "d3f1a2b4-7c8e-4f10-9a2b-5c6d7e8f9012",
    "paymentUrl": "https://pay.mbnk.biz/240730a1b2c3"
  },
  "meta": { "idempotent": true }
}

Ключі памʼятаються 24 години й розділені між партнерами — ваш ключ не може перетнутись із чужим. Беріть значення, унікальне для замовлення: наприклад, ідентифікатор кошика у вашій системі.

Ключ важливіший за тіло запиту

Повтор із тим самим Idempotency-Key, але іншим складом кошика поверне стару відповідь, без попередження. Нове замовлення — завжди новий ключ.

Відповідь

JSON

{
  "data": {
    "paymentId": "d3f1a2b4-7c8e-4f10-9a2b-5c6d7e8f9012",
    "paymentUrl": "https://pay.mbnk.biz/240730a1b2c3"
  }
}

paymentUrl — сторінка оплати, куди слід перенаправити покупця. paymentId збережіть: за ним перевіряють статус.

Цей запит помітно повільніший за інші — ми синхронно створюємо рахунок у банку, щоб віддати готове посилання. Закладайте таймаут не менше 15 секунд.

Статус замовлення

GET/orders/{paymentId} · дозвіл checkout:write

JSON

{
  "data": {
    "paymentId": "d3f1a2b4-7c8e-4f10-9a2b-5c6d7e8f9012",
    "eventId": "a1b2c3",
    "status": "SUCCESS",
    "amountMinor": 90000,
    "amountDecimal": "900.00",
    "currency": "UAH",
    "attendeeId": "clx9attendee01",
    "failureReason": null,
    "createdAt": "2026-07-30T12:00:00.000Z",
    "paidAt": "2026-07-30T12:02:31.000Z"
  }
}

status	Значення
`PENDING`	Створено, покупець ще не оплатив
`PROCESSING`	Банк обробляє платіж
`SUCCESS`	Оплачено, квиток надіслано покупцеві
`FAILED`	Оплата не пройшла
`EXPIRED`	Покупець не оплатив вчасно, місця повернулись
`REFUNDED`	Кошти повернено

Поле attendeeId заповнюється лише після успішної оплати — до того воно null.

Опитуйте статус раз на 5–10 секунд і зупиняйтесь на будь-якому статусі, крім PENDING і PROCESSING. Замість опитування можна підписатися на вебхуки order.paid, order.failed і order.refunded: AOA сама повідомить про результат.

Видно лише власні замовлення

Через API доступні тільки платежі, створені вашим ключем. Чужий чи неіснуючий paymentId дає 404.

Часті помилки

Ситуація	Що робити
`409` «Payments are not configured for this event»	Організатор не підключив приймання оплат. Позначте подію як недоступну для продажу — повторювати немає сенсу.
`409` про залишок квитків	Місця розібрали. Оновіть залишки й запропонуйте меншу кількість.
`400` про безкоштовну подію	У події немає платних квитків — реєстрація на неї відбувається на сайті, не через оплату.
`400` без Idempotency-Key	Додайте заголовок довжиною від 8 символів.

Повний перелік кодів — на сторінці Помилки.