---
title: "Оплата · API Reference: документація AOA API"
description: "Створення платежу за квитки з обовʼязковим Idempotency-Key і перевірка статусу замовлення."
canonical: "https://aoa.com.ua/docs/api-reference/checkout"
---

# Оплата

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

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

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

## Запит

```bash
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`. Замість опитування можна підписатися на [вебхуки](https://aoa.com.ua/docs/webhooks/events) `order.paid`, `order.failed` і `order.refunded`: AOA сама повідомить про результат.

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

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

`paymentId`

дає

`404`

.

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

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

Повний перелік кодів — на сторінці [Помилки](https://aoa.com.ua/docs/api-reference/errors).