Картка створюється за допомогою універсального фрейму для створення карток. Результат дії фрейму - id картки, яку ви зможете використати потім для створення платежу
Є декілька методів створення карток:
Для того, щоб створити фрейм для створення карток потрібно:
Сформувати запит на створення фрейму
Підписати його за допомогою бібліотеки jwt
Вставити код фрейму, який містить щойно підписаний JWT-токен в код html-сторінки
Створити кнопку та обробник на подію натискання кнопки, яка буде сабмітити фрейм для відправки данних
Отримати відповідь одним із способів, описаних у 2 кроці, в залежності від того де застосовується додавання картки (мобільний чи веб додаток)
Зберегти у себе id картки для подальшого використання
Для початку, напишемо наш запит на створення фрейму, наприклад:
{ "params": { "clientId": 1, "method": "createCard", "enableRedirectResponse": true, "version": 2 }, "iat": 1534158275 } |
де:
Параметр | Опис | Тип | Чи обов'язковий це параметр? | Приклад | |
---|---|---|---|---|---|
params.clientId | id клієнта (можна отримати в кабінеті компанії) | INT | Так | 1 | |
params.method | Метод створення картки: "createCard" або "createShortCard" | STRING | Так | createCard | |
params.enableRedirectResponse | Відповідь у виді редіректу або івенту "message" з фрейму на зовні | BOOLEAN | Так | true | |
params.version | Версія фрейму, якщо параметр не передавати, то за замовчуванням - 1
| INT | Ні | 2 | |
iat | International Atomic Time. В нашій ситуації - це "UNIX-час", тобто, кількість секунд, яка пройшла з 1 січня 1970 р. до моменту виконання запиту | INT | Так | 1534158275 |
Підпишемо наш запит за допомогою jwt та алгоритму HS256 ключем, який отримали в вашому кабінеті, зареєструвавшись у системі. Сам процес підписання може мати відмінності в залежності від того, яку реалізацію бібліотеки ви оберете. Але, після нього ви отримаєте рядок, в якому буде закодовано ваш запит.
Приклад такого рядку - JWT-токену:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOjEsIm1ldGhvZCI6ImNyZWF0ZUNhcmQiLCJlbmFibGVSZWRpcmVjdFJlc3BvbnNlIjp0cnVlLCJ2ZXJzaW9uIjoyfSwiaWF0IjoxNTM0MTU4Mjc1fQ.oOCJLZBnsL1EPwCHaV2KEZ-EEWilJR23Gf3OhQ1irsw |
Тепер потрібно сформувати URL замінивши параметр {token} (це і є ваш сформований JWT-токен), а також передати мову локалізації інтерфейсу, якщо це потрібно, за допомогою query string параметру locale, можна передати - "ua", "en", "ru".
https://api.demo.uapay.ua/api/iframe/{token}?locale=ua |
Приклад уже сформованого URL, який треба вставити в src фрейму:
https://api.demo.uapay.ua/api/iframe/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOjEsIm1ldGhvZCI6ImNyZWF0ZUNhcmQiLCJlbmFibGVSZWRpcmVjdFJlc3BvbnNlIjp0cnVlLCJ2ZXJzaW9uIjoyfSwiaWF0IjoxNTM0MTU4Mjc1fQ.oOCJLZBnsL1EPwCHaV2KEZ-EEWilJR23Gf3OhQ1irsw?locale=ua |
Для ініціалізації фрейму треба вставити його код в html-сторінку:
<iframe id="uapayFrame" style="height: 50%; width: 100%" src="https://api.demo.uapay.ua/api/iframe/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOjEsIm1ldGhvZCI6ImNyZWF0ZUNhcmQiLCJlbmFibGVSZWRpcmVjdFJlc3BvbnNlIjp0cnVlfSwiaWF0IjoxNTM0MTU4Mjc1fQ.2IgQHppcYE69VD8qrZEFX9A2fK_rras2M1AzcXkdM4A"></iframe> |
<button id="btnSubmit">Створити картку</button> |
Після коду фрейму та кнопки необхідно додати також код обробки події натиску кнопки
<script> let iframe = document.getElementById('uapayFrame').contentWindow; let button = document.getElementById('btnSubmit'); button.addEventListener('click', function (e) { iframe.postMessage('Submit', "*"); }); </script> |
В залежності від того де розроблюється функціонал для створення карток, використовується різні методики отримання відповіді (результату запиту) від фрейму:
Приклад отриманого редіректу:
1) Для методу "createCard":
https://addcards.demo.uapay.ua/success?payload=FFHV5W9sKTeUopktwnhMF1FRCcMna7FGBV98RN4g2BQZJJC7YxXhHtqV7oTUhTKGJKGvgA4Gh4Mmf2AFFPAP5mSGht1tK6Nb7A5imEzDiqVYhrqXtSexmGkNv3syNj5vULqzMa |
де:
payload - дані по карті, закодовані в base58 (треба розкодувати)
Приклад розкодованого payload:
{ "id":"c45b0a87-3af4-4cd1-9466-252acc8d1c29", "cvv":"123", "panMasked":"123456*7890" } |
де:
Параметр | Опис | Тип | Приклад |
---|---|---|---|
id | id щойно створеної картки | STRING | "c45b0a87-3af4-4cd1-9466-252acc8d1c29" |
cvv | CVV2\CVC код картки | STRING | "123" |
panMasked | замаскований пан картки | STRING | "123456*7890" |
2) Для методу "createShortCard":
https://addcards.demo.uapay.ua/success?payload=6vUVcDK623kYcyVux2WuRxmsTRwB8FEfUmjNtb3n3XW9oESnsHeZ2yMnJ2iXuq16xiy2ic5pFk7FoWhezWLfmw44khFrnhNowczB55zDh41Fevx |
де:
payload - дані по карті, закодовані в base58 (треба розкодувати))
Приклад розкодованого payload:
{ "id":"c45b0a87-3af4-4cd1-9466-252acc8d1c29" "panMasked":"123456*7890" } |
де:
Параметр | Опис | Тип | Приклад |
---|---|---|---|
id | id щойно створеної картки | STRING | "c45b0a87-3af4-4cd1-9466-252acc8d1c29" |
panMasked | замаскований пан картки | STRING | "123456*7890" |
Після того, як користувач введе дані картки та натисне кнопку збереження, у фреймі буде створено токен карти і після цього фрейм відправить назовні подію "message", в якій буде міститися відповідь на запит від системи UAPAY. А на сторінці потрібно додати обробник на подію "message" для отриманняя даних по карті:
<script> function listener(event) { // Ввімкнути перевірку на production середовищі /*if(event.origin !='https://addcards.uapay.ua'){ return; }*/ if (event.data) { if (event.data.name === 'Success') { //{name: 'Success', payload: '2zNu7MwoGaztBeJNjNA5rmyos2aq6mrcrb2zst6AFPVfNscFNTt8C8ZJF2qAskcLUuQKU9B2BUe5xLPH5KqkDWaECVSQjPdPYuCERRH7tnhzZGmen8'} alert('payload: ' + event.data.payload); console.log('event.data.payload'); } else if (event.data.name === 'Error') { //{name: 'Error', code: 'TIMEOUT_ERROR'} alert('Error: ' + event.data.code); } } } window.addEventListener("message", listener, false); </script> |
Отримання відповіді
Після успішного створення картки отримаємо на обробник подіі "message" у змінну event отримаємо таку відповідь:
1) Для методу "createCard" (створення повної картки з cvv):
{ "name": "Success", "payload": "FFHV5W9sKTeUopktwnhMF1FRCcMna7FGBV98RN4g2BQZJJC7YxXhHtqV7oTUhTKGJKGvgA4Gh4Mmf2AFFPAP5mSGht1tK6Nb7A5imEzDiqVYhrqXtSexmGkNv3syNj5vULqzMa" } |
Де:
Параметр | Опис | Тип | Приклад |
---|---|---|---|
name | Коротке повідомлення про успіх або помилку при виконанні запиту. "Success" - запит виконано успішно, "Error" - сталась помилка при виконанні запиту | STRING | "Success" або "Error" |
payload | дані створеної картки, закодовані у base58 | STRING | "2zNu7MwoGaztBeJNjNA5rmyos2aq6mrcrb2zst6AFPVfNscFNTt8C8ZJF2qAskcLUuQKU9B2BUe5xLPH5KqkDWaECVSQjPdPYuCERRH7tnhzZGmen8" |
Розшифровка відповіді
Після розкодування payload з base58 ми отримаємо дані створеної картки:
{ "id": "01afbcfc-a44e-47f7-886b-673bc6f2573d", "cvv": "123", "panMasked": "411111*1111" } |
де:
Параметр | Опис | Тип | Приклад |
---|---|---|---|
id | id щойно створеної картки | STRING | "01afbcfc-a44e-47f7-886b-673bc6f2573d" |
cvv | CVV2\CVC код картки | STRING | "123" |
panMasked | замаскований пан картки | STRING | "411111*1111" |
2) Для методу "createShortCard" (створення картки без cvv):
{ name: "Success", payload: "QtDZHvcnhSoxHr1LxrNdg64iei966jYsX9465pqh82k5Q6TQhdhuLh4oy2F82WydxBa94L4ga1JSEELQn8AEU11qi98FigGAp" } |
Де:
Параметр | Опис | Тип | Приклад |
---|---|---|---|
name | Коротке повідомлення про успіх або помилку при виконанні запиту. "Success" - запит виконано успішно, "Error" - сталась помилка при виконанні запиту | STRING | "Success" або "Error" |
payload | дані створеної картки, закодовані у base58 | STRING | "QtDZHvcnhSoxHr1LxrNdg64iei966jYsX9465pqh82k5Q6TQhdhuLh4oy2F82WydxBa94L4ga1JSEELQn8AEU11qi98FigGAp" |
Розшифровка відповіді
Після розкодування payload з base58 ми отримаємо дані створеної картки:
{ "id":"138ebdb9-3544-4e63-a2d9-bf20e0e9a116", "panMasked":"411111*1111" } |
де:
Параметр | Опис | Тип | Приклад |
---|---|---|---|
id | id щойно створеної картки | STRING | "138ebdb9-3544-4e63-a2d9-bf20e0e9a116" |
panMasked | замаскований пан картки | STRING | "411111*1111" |