Документація / Інтеграція

Сторінка оплати

Сторінку оплати робимо ми. Ваш сервер лише перенаправляє на неї покупця — за checkout_url із відповіді на створення рахунку.

Що бачить покупець

Суму замовлення й таймер строку дії рахунку.
Вибір валюти — лише активи рахунку, доступні зараз.
Після вибору: QR-код, точну суму з кнопкою «Копіювати», адресу, попередження про мережу й посилання «Відкрити в гаманці» (BIP21, EIP-681, Solana Pay, TRON).
Статус оновлюється сам: «Платіж знайдено» → «Підтвердження 7/20» → «Оплату отримано».
Кнопку «Повернутися до магазину» — ваш return_url.

Поки нічого не сплачено, покупець може змінити валюту. Після першого платежу валюта закріплюється. Для волатильного активу йде таймер курсу (20 хвилин); коли він спливає, сума й адреса приховуються.

Сторінка доступна російською та англійською, зі світлою й темною темою — за налаштуваннями пристрою.

Як відкривати

Де	Як
Сайт	Перехід у тій самій вкладці: `303 See Other` з вашого сервера або `location.href`
iOS	`ASWebAuthenticationSession` або `SFSafariViewController`
Android	Chrome Custom Tabs (`androidx.browser`)
Telegram-бот	Inline-кнопка з посиланням на `checkout_url`
Не використовувати	`iframe`, `WKWebView`, `WebView`: немає адресного рядка (фішинг неможливо відрізнити), посилання в гаманці працюють ненадійно. Вбудовування сторінка забороняє (`frame-ancestors 'none'`)

Мобільні застосункиЗастосунок не звертається до API Coinetic напряму й не зберігає секрет ключа — його витягують зі збірки за лічені хвилини. Рахунок створює ваш сервер на запит застосунку, а застосунку віддає лише checkout_url.

Повернення покупця

Покупець може повернутися до оплати, під час підтверджень або не повернутися зовсім. Сторінка замовлення не повинна на це покладатися.
У return_url можна передати номер замовлення, але статус беріть зі своєї бази — її оновлює вебхук. Якщо замовлення ще не оплачене — перевірте GET /v1/invoices/{id}.
Для застосунків передайте універсальне посилання (Universal Links / App Links): https://shop.example/app/orders/ORDER-1001. Власні схеми (myapp://) не приймаються.

Типові ситуації

Ситуація	Що зробити
Покупець закрив вкладку	Додайте в замовлення посилання «Перейти до оплати» на `checkout_url` — рахунок дійсний до `expires_at`
Строк рахунку минув	Новий рахунок із новим `order_id` (наприклад, `ORDER-1001-2`) і новим `Idempotency-Key`
Недоплата	«Доплатіть залишок на ту саму адресу» — сторінка оплати показує залишок
Оплата після закінчення строку	Гроші отримано, рішення за вами: видати замовлення або оформити повернення
Перевірка AML	Повідомте, що платіж перевіряється; дочекайтеся `invoice.paid`