Створення картки у фреймі

Загальна інформація про створення карток 

Картка створюється за допомогою універсального фрейму для створення карток. Результат дії фрейму - id картки, яку ви зможете використати потім для створення платежу
Є декілька методів створення карток:

  1. "createCard" - Створення повної (з терміном дії) картки - може бути використана для списання коштів.
  2. "createShortCard" - Створення неповної (без терміну дії) картки - може бути використана для зарахування коштів.

Для того, щоб створити фрейм для створення карток потрібно:

  1. Сформувати запит на створення фрейму

  2. Підписати його за допомогою бібліотеки jwt

  3. Вставити код фрейму, який містить щойно підписаний JWT-токен в код html-сторінки

  4. Створити кнопку та обробник на подію натискання кнопки, яка буде сабмітити фрейм для відправки данних

  5. Отримати відповідь одним із способів, описаних у 2 кроці, в залежності від того де застосовується додавання картки (мобільний чи веб додаток)

  6. Зберегти у себе id картки для подальшого використання


Крок 1: Створення фрейму

Створення запиту

Для початку, напишемо наш запит на створення фрейму, наприклад:

{
  "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

Використовуйте новішу версію

Ми радимо вам використовувати версію 2, оскільки вона більш функціональна і має сучасніший дизайн.

Також, з часом ми перестанемо підтримувати версію 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-сторінку

Для ініціалізації фрейму треба вставити його код в 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>



Крок 2: Отримання відповіді

В залежності від того де розроблюється функціонал для створення карток, використовується різні методики отримання відповіді (результату запиту) від фрейму:

1. Мобільний додаток
  • В запит на створення фрейму (створення токену з кроку 1) потрібно передати параметр enableRedirectResponse: true
  • Після того, як користувач введе дані картки та натисне кнопку збереження, у фреймі буде створено токен карти і після цього буде зроблений 302 редірект фрейму, який буде містити в URL відповідь на запит від системи UAPAY. А в мобільному додатку потрібно додати обробник на подію "редірект" для отриманняя даних по карті.

    Приклад отриманого редіректу: 

    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"

2. Веб-додаток
  • В запит на створення фрейму (створення токену з кроку 1) потрібно передати параметр enableRedirectResponse: false
  • Після того, як користувач введе дані картки та натисне кнопку збереження, у фреймі буде створено токен карти і після цього фрейм відправить назовні подію "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"