UAPAY - національний платіжний сервіс

Підтвердження платежів

Owned by Denys Kucheriavyi (Unlicensed)
Last updated: 013 30, 2022 by antonina smetanina (Unlicensed)
3 min read

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

Щоб визначити, що платіж потребує підтвердження, викликаємо метод отримання даних по угоді і у відповіді  беремо до уваги об'єкти платежів data.productPayment і data.handlerPayment. Статус самого платежу status залишається в "NEW", але статус waitingFor має бути в "CONFIRMATION". Це означає, що цей платіж  необхідно підтвердити. В полі details.confirmation буде зберігатися об'єкт, який потрібен для підтвердження платежу.

Приклад:

...
"productPayment": {
    "id": 994,
    "amount": 10000,
    "commissionAmount": 600,
    "status": "NEW",
    "statusCode": "NEEDS_CONFIRMATION",
    "statusText": null,
    "type": "P2P",
    "waitingFor": "CONFIRMATION",
    "details": {
        "confirmation": {
            "type": "LOOKUP",
            "redirectUrl": "https://api.escrowbox.stage.uapay.ua/api/payments/994/confirmations"
        }
    },
    "payReceipt": "https://api.stage.uapay.ua/api/receipts/f8c2f0dd-454e-4264-8051-80a51fd4d167.pdf",
    "reverseReceipt": null,
    "finishReceipt": null
},
...

Є кілька способів підтвердження платежу. Визначити, який спосіб у даного платежу, допоможе details.confirmation.type.

Підтвердження LOOKUP

Поле details.confirmation.type = "LOOKUP".

Приклад об'єкта details.confirmation:

{
    "type": "LOOKUP",
    "redirectUrl": "https://api.escrowbox.demo.uapay.ua/api/payments/994/confirmations"
}

Процедура підтвердження платежу полягає в тому, що платник отримує смс з кодом підтвердження від банку-емітента, який потрібно передати в метод підтвердження платежу системи Escrow Box. Процес передачі цього коду від платника до системи Escrow Box залежить від реалізації клієнта-інтегратора. Як приклад, це звичайна форма з одним полем та кнопкою "Відправити" на клієнтській частині сервісу клієнта-інтегратора, яка викликає метод сервісу клієнта-інтегратора, а той в свою чергу, викликає метод пілтвердження платежу системи Escrow Box з параметром code, в цьому випадку details.confirmation.redirectUrl являється URL-ом, на який потрібно відправити підтвердження. 

Підтвердження 3DS

Поле details.confirmation.type = "3DS".

Приклад об'єкта details.confirmation:

{
  "type": "3DS",
  "url": "https://3ds.ukrsotsbank.com:443/way4acs/pa?id=W6yNkAC_RQUjjjRwIyPCsg",
  "form": {
    "PaReq": "eJxVUttuo0AMfc5foH4Ac0kgQzQZiZaHjVRatqXqY4WIldDdTMgMZJt+/dpAVtmRRtg+Z2yObV3uHUD2CnXvwOgcvK92EDTb9V2RvsDpQ0RzxecRV2qRqDsz00PYzGb6DM43R2tEyEOp2dVFpK2siaKlEnwpZMzjSM6VZhRFMAdX7yvboT3TVX263zyZSMZJLDSbXEIO4DaZ4eOR4wcZY5gItjqAKcF3wTVjUFb+sbG/As0GkFj1sbeduxjFF5pdHQJ699vsu65dMSbkEiXwUKzmeFhebNgL+PZoPRTuWGNLGrsLP32rGb3Cx+xGhC56sv1Y76vZmrx8+37O0u+nMl08Zz8jtP/k411rRgxibqsOjORC8UQuA8FXkVpxbNMQH3pzoN81cUi6J4fiLdVLJ5Cw28CguXcObH0xieIo+uoRBF8oC5CHA/tnk6AbEfrhxzSbusNepxV/3xT95fHs2sX58N7vT01ns+0bl680sYE05W6wuSIhFZNDqSkdFhjWhjo3bBha/23eX56EwQw="
  },
  "redirectUrl": "https://api.escrowbox.demo.uapay.ua/api/payments/564/confirmations"
}

Процедура підтвердження платежу полягає в тому, що платник отримує смс з кодом підтвердження від банку-емітента, який необхідно ввести  на сторінці підтвердження (ACS) банка-емвтента. Процес виклику цієї сторінки залежить від реалізації клієнта-інтегратора. На клієнтській частині сервісу клієнта-інтегратора потрібно реалізувати форму з методом відправки POST  запиту при submit на action details.confirmation.url з двома полями: "TermUrl" (в значенні вказати URL системи-інтегратора, на який прийде postback від банку з даними для підтвердження платежу) та "PaReq"(в значенні вказати дані з details.confirmation.form.PaReq).  Після виклику даної форми платника редіректить на сторінку підтвердження платежу банка-емітента, там він підтверджує платіж і після успішного підтвердження банк надсилає postback на URL, який був вказаний у формі. Про випадок, коли банк не відображає сторінку підтвердження платежу, а відразу надсилає postback, інформація наведена в розділі по quasi-3DS. У відповідь отримаємо об'єкт з параметром "PaRes" та від окремих банків може прийти параметр  "MD", ці параметри необхідно надіслати в метод підтвердження платежу системи Escrow Box на URL details.confirmation.redirectUrl.

Приклад форми:

<html>

<body>
    <form action="https://acs.privatbank.ua/pPaReqMC.jsp" method="POST">
        <input name="TermUrl" value="https://api.escrowbox.stage.uapay.ua/api/payments/1072/confirmations"></input><br>
        <input name="PaReq" value="eJxVUsFuwjAMPfMXFR/QJC2lDQqR2DgMaR1o685TVSzoNkJJ2g34+tkpIBa1qu337NTPVsXWAszfoOosaJWDc+UGgno9Ha5mr3D4EEksucxiEWcjOdQD5cN6MFA/YF29N1qEPIwUu7qINKXRiRhnaZLGPEtTLtNEMYoimIOttqVp0R6osjo8LF50Eo3lWCh2cQnZgV3MNe9P1H+Q0YeJYMod6AJcG1wrBkXpnmvzFSjmQWJV+8609qQzPlLs6hDQ2W+9bdtmwpiIUmyBh2IS42H5asFewTV742Bl9xVKUptN+OkaxSgLk9ldE2rVke36+471WufF+3lZzJLlPD/m5w1H+zef+3eqGDGIuS5b0BEXmeBcBiKb4BPHivm412ZHv6sFH4ecoza9S0hDN85uMKH3Id93Zy2Y6qRlhujNIwiO2BogD4d2s6mpu0bU49NlPlWLesc84VKmEmdKQ/KxS6ka9cTxjHyt2ourGGVjPb8pJJZfKrT+LdsfSpO6aw=="></input><br>
        <button>Submit</button>
    </form>
</body>

</html>

Фінальний етап підтвердження

Підтвердженим платіж буде вважатися у випадку, коли його статус зміниться з "NEW" на "PAID", а не коли буде викликано метод підтвердження платежу. У зв'язку з чим, після  виклику методу підтвердження платежу при буль-якому підтвердженні необхідно трекати стан угоди та звертати увагу на стан платежів.

Є ще один спосіб підтвердження платежів - quasi-3DS, він не виокремлений як окремий, так як містить в собі  обидва підьвердження. Спочатку необхідно підтвердити 3DS (сторінка банка-емітента тут не відображається, відразу відбувається редірект, без підтвердження платником), а потім платіж стає з підтвердженням LOOKUP.

UAPAY - національний платіжний сервіс
pay@uapay.ua