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

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

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

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

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

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

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

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

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

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

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


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

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

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

де:

Параметр

ОписТипЧи обов'язковий це параметр?Приклад
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-токену:

Тепер потрібно сформувати URL замінивши параметр {token} (це і є ваш сформований JWT-токен), а також передати мову локалізації інтерфейсу, якщо це потрібно, за допомогою query string параметру locale, можна передати -  "ua", "en", "ru".

Приклад уже сформованого URL, який треба вставити в src фрейму:

Інтеграція фрейму в html-сторінку

Для ініціалізації фрейму треба вставити його код в html-сторінку:

Створення кнопки для сабміту фрейму на відправку запиту на створення картки

Створення обробника події натиску кнопки фрейму

Після коду фрейму та кнопки необхідно додати також код обробки події натиску кнопки



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

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

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

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

    1) Для методу "createCard":

    де:
    payload - дані по карті, закодовані в base58 (треба розкодувати)

    Приклад розкодованого payload

    де:

    Параметр

    ОписТипПриклад
    id

    id щойно створеної картки

    STRING"c45b0a87-3af4-4cd1-9466-252acc8d1c29"
    cvv

    CVV2\CVC код картки

    STRING"123"
    panMasked

    замаскований пан картки

    STRING

    "123456*7890"

    2) Для методу "createShortCard":

    де:
    payload - дані по карті, закодовані в base58 (треба розкодувати))

    Приклад розкодованого payload

    де:

    Параметр

    ОписТипПриклад
    id

    id щойно створеної картки

    STRING"c45b0a87-3af4-4cd1-9466-252acc8d1c29"
    panMasked

    замаскований пан картки

    STRING

    "123456*7890"

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


    Отримання відповіді

    Після успішного створення картки отримаємо на обробник подіі "message" у змінну event отримаємо таку відповідь:
    1) Для методу "createCard" (створення повної картки з cvv):

    Де:

    Параметр

    ОписТипПриклад
    name

    Коротке повідомлення про успіх або помилку при виконанні запиту.

    "Success" - запит виконано успішно,

    "Error" - сталась помилка при виконанні запиту

    STRING"Success" або "Error"
    payload

    дані створеної картки, закодовані у base58

    STRING

    "2zNu7MwoGaztBeJNjNA5rmyos2aq6mrcrb2zst6AFPVfNscFNTt8C8ZJF2qAskcLUuQKU9B2BUe5xLPH5KqkDWaECVSQjPdPYuCERRH7tnhzZGmen8"



    Розшифровка відповіді

    Після розкодування payload з base58 ми отримаємо дані створеної картки:

    де:

    Параметр

    ОписТипПриклад
    id

    id щойно створеної картки

    STRING"01afbcfc-a44e-47f7-886b-673bc6f2573d"
    cvv

    CVV2\CVC код картки

    STRING"123"
    panMasked

    замаскований пан картки

    STRING

    "411111*1111"

    2) Для методу "createShortCard" (створення картки без cvv):

    Де:

    Параметр

    ОписТипПриклад
    name

    Коротке повідомлення про успіх або помилку при виконанні запиту.

    "Success" - запит виконано успішно,

    "Error" - сталась помилка при виконанні запиту

    STRING"Success" або "Error"
    payload

    дані створеної картки, закодовані у base58

    STRING

    "QtDZHvcnhSoxHr1LxrNdg64iei966jYsX9465pqh82k5Q6TQhdhuLh4oy2F82WydxBa94L4ga1JSEELQn8AEU11qi98FigGAp"



    Розшифровка відповіді

    Після розкодування payload з base58 ми отримаємо дані створеної картки:

    де:

    Параметр

    ОписТипПриклад
    id

    id щойно створеної картки

    STRING"138ebdb9-3544-4e63-a2d9-bf20e0e9a116"
    panMasked

    замаскований пан картки

    STRING

    "411111*1111"