Отримання статусу T2P-платежу за externalPaymentId
Метод дозволяє інтегратору отримати поточний статус та реквізити T2P-платежу за зовнішнім ідентифікатором (externalPaymentId), який інтегратор передав при створенні платежу в deeplink (параметр id).
Тіло відповіді ідентичне тілу вебхуку, який банк надсилає на callbackSuccess / callbackFail. Це дозволяє інтегратору не піднімати власний сервер для прийому вебхуків, а періодично опитувати статус самостійно.
Пошук обмежений останніми 90 днями. Платежі, створені раніше, через цей ендпоінт недоступні.
Авторизація — за токеном мерчанта (X-Token). Він спільний для всіх терміналів tap2pay.
Рекомендована частота опитування — не частіше ніж 1 раз на 5 секунд для одного externalPaymentId.
Рекомендації щодо використання
- Зберігайте externalPaymentId на своєму боці одразу при створенні платежу — це єдиний ключ для подальшого опитування статусу.
- Платіж переходить у фінальний стан (success / rejected / *_not_completed) зазвичай протягом кількох секунд після завершення операції на терміналі. До цього моменту статус буде pending.
- Опитування статусу — це резервний механізм. Основний рекомендований спосіб отримання результату — вебхук на callbackSuccess / callbackFail, переданий у запиті на створення платежу. Якщо ви плануєте використовувати цей спосіб як основний — передавайте в callbackSuccess / callbackFail адресу, куди потенційно в майбутньому будуть приходити вебхуки.
- Якщо ви опитуєте статус у циклі — використовуйте експоненційну затримку (наприклад, 1 с → 2 с → 5 с → 10 с → 30 с) і обмежте загальний час очікування (наприклад, 2 хвилини). Після цього вважайте платіж невизначеним і звертайтесь у підтримку.
- Поля maskedPan, cardMask, approvalCode, rrn, responseCode, countryCard зʼявляються у відповіді не одразу — лише після того, як по платежу побудована виписка. Якщо вам критично отримати ці поля — виконайте повторний запит через 10–30 секунд після переходу у status=success.
QUERY PARAMETERS:
externalPaymentId
required
string
Зовнішній ідентифікатор платежу, який інтегратор передав у полі id запиту POST /api/t2p/mob/terminal/payment/create
HEADER PARAMETERS:
X-Token
required
string
Токен мерчанта, отриманий з https://web.monobank.ua/
/api/merchant/t2p/terminal/payment/external/status
200 Платіж знайдено, тіло містить актуальні дані
400 Не передано або порожній параметр externalPaymentId
403 Токен невалідний
404 Платіж із таким externalPaymentId не знайдено в межах останніх 90 днів
405 Http-метод невалідний
500 Під час виконання запиту виникла непередбачена помилка