Створення картки з механізмом авторизації

Крок 1: Створення cесії

Для того, щоб створити запит на створення сесії потрібно:

Написати запит на створення сесії
Підписати його за допомогою бібліотеки jwt
Виконати запит на створення сесії
Отримати відповідь і розшифрувати її, там ми отрмаємо id сесії

Запит на URL /api/sessions/create методом POST

Для початку роботи з системою потрібно створити сесію для свого магазину, від імені якої будуть виконуватись всі подальші дії
Створювати сесію перед кожним платежем не обов'язково, але ми рекомендуємо оновлювати сесію хоча б раз в день

Створення сесії

Написання запиту

Для початку, напишемо наш запит:

{
  "params":{
    "clientId":"636"
  },
  "iat": "1534862833"
}

де:

Параметр

Опис

Тип

Чи обов'язковий це параметр?

Приклад

clientid

id користувача

(можна отримати в кабінеті компанії)

INT

Так

1

iat

International Atomic Time. В нашій ситуації

це "UNIX-час", тобто, кількість секунд, яка пройшла з 1 січня 1970 р. до моменту виконання запиту

INT

Так

1534862833

Підписання запиту

Підпишемо наш запит за допомогою jwt та алгоритму HS256. Сам процес підписання може мати відмінності в залежності від того, яку реалізацію бібліотеки ви оберете. Але, після нього ви отримаєте рядок, в якому буде зашифровано ваш запит:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOiI2MzYifSwiaWF0IjoiMTUzNDg2MjgzMyJ9.msXU79dd1DcVo4gwIUqBF_2PSLg0eFNEVCzRTiOvkfw

Формування запиту для відправлення на сервер

У запиті потрібно передавати і запит у незашифровану вигляді, а також, у підписаному (зашифрованому), у вигляді змінної "token". Тобто, наш запит буде виглядати так:

{
    "params": {
        "clientId": "636"
    },
    "iat": 1534862833,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOiI2MzYifSwiaWF0IjoiMTUzNDg2MjgzMyJ9.msXU79dd1DcVo4gwIUqBF_2PSLg0eFNEVCzRTiOvkfw"
}

де:

Параметр

Опис

Тип

Чи обов'язковий це параметр?

Приклад

clientid

id користувача

(можна отримати в кабінеті компанії)

INT

Так

1

iat

International Atomic Time. В нашій ситуації

це "UNIX-час", тобто, кількість секунд, яка пройшла

з 1 січня 1970 р. до моменту виконання запиту

INT

Так

1534862833

token

Той самий запит, але який вже попередньо

зашифрований за допомогою бібліотеки jwt секретним ключем методом HS256

STRING

Так

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOiIxMzIifSwiaWF0IjoxNTI5OTI3NTUyfQ.I3Ap79vaShIxuBFjbB-8gs1d2j1EoEVchf0DP0DGICg"

Відправлення запиту

Запит треба виконати методом POST, тіло запиту має бути у форматі application/json. Адреса https://api.demo.uapay.ua/api/sessions/create .

У відповідь ми отримаємо:

{
    "status": 1,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImIzOGNlY2QzLTI4ZGItNDFmNC05OTM1LTlmNDExYWM3YTVlYiIsImlhdCI6MTUzNDg2Mjg0Mn0.cXRUNzI75I3HKlE25Uzy3N-CmGDfVE4K5de98sGJmAg"
    }
}

Де:

Параметр

Опис

Тип

Приклад

status

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

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

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

INT

1 або 0

token

Підписана UAPAY відповідь яка містить id сесії.

STRING

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImIzOGNlY2QzLTI4ZGItNDFmNC05OTM1LTlmNDExYWM3YTVlYiIsImlhdCI6MTUzNDg2Mjg0Mn0.cXRUNzI75I3HKlE25Uzy3N-CmGDfVE4K5de98sGJmAg"

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

Тепер ми можемо розшифрувати відповідь. Для цього треба застосувати функцію decode бібліотеки jwt, передати їй ваш секретний ключ, параметр алгоритму (HS256) та рядок який ви отримали у відповіді після запиту у параметрі "token". В результаті ви отримаєте

{
  "id": "b38cecd3-28db-41f4-9935-9f411ac7a5eb",
  "iat": 1534862842
}

Де:

Параметр

Опис

Тип

Приклад

status

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

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

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

INT

1 або 0

id

id сесії

STRING

"b38cecd3-28db-41f4-9935-9f411ac7a5eb"

iat

International Atomic Time. В нашій ситуації

це "UNIX-час", тобто, кількість секунд, яка пройшла з 1 січня 1970 р. до моменту виконання запиту

INT

1534862842

Крок 2: Створення картки

Запит для створення картки.

URL: https://api.demo.uapay.ua/api/cards/create

{  
   "data":{  
      "pan":"1111222233334444",
      "expiresAt":"2020-01"
   },
   "params":{
      "sessionId":"690f8123-3a12-4eef-bcac-2fb82a34bd11"
   }
}

де:

Параметр	Опис	Тип	Чи обов'язковий це параметр?	Приклад
data.pan	Номер картки (16 знаків)	STRING	Так	"1111222233334444"
data.expiresAt	Термін дії картки	STRING	Ні	"2020-01"
params.sessionId	ID сессіії	STRING	Так	"690f8123-3a12-4eef-bcac-2fb82a34bd11"

Підписання запиту

Підпишемо наш запит за допомогою jwt та алгоритму HS256. Сам процес підписання може мати відмінності в залежності від того, яку реалізацію бібліотеки ви оберете. Але, після нього ви отримаєте рядок, в якому буде зашифровано ваш запит:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOiI2MzYifSwiaWF0IjoiMTUzNDg2MjgzMyJ9.msXU79dd1DcVo4gwIUqBF_2PSLg0eFNEVCzRTiOvkfw

Формування запиту для відправлення на сервер

Потрібно передавати запит у незашифровану вигляді, а також, у підписаному (зашифрованому), у вигляді змінної "token". Тобто, наш запит на створення сесії буде виглядати приблизно так:

{
   "data":{  
      "pan":"1111222233334444",
      "expiresAt":"2020-01"
   },
   "params":{
      "sessionId":"690f8123-3a12-4eef-bcac-2fb82a34bd11"
   },
   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOiI2MzYifSwiaWF0IjoiMTUzNDg2MjgzMyJ9.msXU79dd1DcVo4gwIUqBF_2PSLg0eFNEVCzRTiOvkfw"
}

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

Тепер ми можемо розшифрувати відповідь. Для цього треба застосувати функцію decode бібліотеки jwt, передати їй ваш секретний ключ, параметр алгоритму (HS256) та рядок який ви отримали у відповіді після запиту у параметрі "token". В результаті ви отримаєте

{
    "status": 1,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImIzOGNlY2QzLTI4ZGItNDFmNC05OTM1LTlmNDExYWM3YTVlYiIsImlhdCI6MTUzNDg2Mjg0Mn0.cXRUNzI75I3HKlE25Uzy3N-CmGDfVE4K5de98sGJmAg"
    }
}

Де:

Параметр

Опис

Тип

Приклад

status

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

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

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

INT

1 або 0

token

Підписана UAPAY відповідь яка містить id картки.

STRING

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImIzOGNlY2QzLTI4ZGItNDFmNC05OTM1LTlmNDExYWM3YTVlYiIsImlhdCI6MTUzNDg2Mjg0Mn0.cXRUNzI75I3HKlE25Uzy3N-CmGDfVE4K5de98sGJmAg"

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

 {   
      "id":"11389a5a-efb5-4e1d-85c1-068df5bb0357",
      "panMasked":"1111224444",
      "panHashed":"AwHkjhy32jz/9zF9J3koov8fTChboACkdYN+3Ye4="
}

де:

Параметр	Опис	Тип	Чи обов'язковий це параметр?	Приклад
id	id картки в системі UAPAY	STRING	Так	"11389a5a-efb5-4e1d-85c1-068df5bb0357"
panMasked	Маскований PAN картки	STRING	Так	"1111224444"
panHashed	Хеш PAN картки	STRING	Так	"AwHkjhy32jz/9zF9J3koov8fTChboACkdYN+3Ye4="

Крок 3: Запит на підтвердження карти

Перед створенням платежу є обов'язковим наявніть сесії, якщо її немає, треба створити як описано на кроці 1.

На цьому кроці ми створюємо платіж. Для цього потрібно виконати такі дії:

Написати запит на створення платежу, додати в нього id сесії
Підписати його за допомогою бібліотеки jwt
Виконати запит на створення платежу
Отримати відповідь та розшифрувати її. У відповіді будуть номер замовлення, номер платежу, id платежу та ключ платежу. Останні два потрібні для наступного кроку (підтвердження платежу).

Написання запиту

Запит треба виконати методом POST, тіло запиту має бути у форматі application/json. Адреса https://api.demo.uapay.ua/api/cards/confirm

Напишемо запит на створення платежу (замовлення):

{  
   "params":{  
      "id":"11389a5a-efb5-4e1d-85c1-068df5bb0357",   		
      "sessionId":"690f8123-3a12-4eef-bcac-2fb82a34bd11",
      "device": {
         "acceptHeader": "*/*",
         "ip": "91.137.205.117",
         "colorDepth": 24,
         "javaEnabled": false,
         "language": "en-US",
         "screenHeight": 864,
         "screenWidth": 1536,
         "windowHeight": 734,
         "windowWidth": 1479,
         "time": "2021-10-07T14:55:52.832Z",
         "timezoneOffset": -180,
         "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.159 Safari/537.36"
      }
   },
   "data":{  
      "externalId":"000004", 
      "secureCode":"123"
   }
}

Де:

Параметр	Опис	Тип	Обов'язковий параметр чи ні?	Приклад
Параметри
sessionId	id сесії яку ми отримали після розшифровки підписаної відповіді попереднього запиту. Цей параметр взагалі треба передавати у всіх запитах	STRING	Так	"4bda7e34-a1c7-4587-b43b-06c506388ce7"
id	ИД картки	STRING	Так	"11389a5a-efb5-4e1d-85c1-068df5bb0357"
device	Об'єкт з інформацією про браузер / пристрій платника	OBJECT	Так	{"acceptHeader":"/","ip":"91.137.205.117","colorDepth":24,"javaEnabled":false,"language":"en-US","screenHeight":864,"screenWidth":1536,"windowHeight":734,"windowWidth":1479,"time":"2021-10-07T14:55:52.832Z","timezoneOffset":-180,"userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.159 Safari/537.36"}
Данні
externalId	Унікальний номер платежу у системі клієнта. За допомогою цього параметру ви будете знати до якого замовлення\кошика\клієнта віднесено ту чи іншу оплату	STRING	Так	"000004", "1", "123"
secureCode	CVV	STRING	Так	"123"

Підписання запиту

Підписуємо запит таким саме чином, як і запит на створення сесії. Тобто, за допомогою бібліотеки jwt та ключа який ми отримали у кабінеті алгоритмом HS256. І отримуємо token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiaWQiOiIxMTM4OWE1YS1lZmI1LTRlMWQtODVjMS0wNjhkZjViYjAzNTciLCJzZXNzaW9uSWQiOiI2OTBmODEyMy0zYTEyLTRlZWYtYmNhYy0yZmI4MmEzNGJkMTEiLCJkZXZpY2UiOnsiYWNjZXB0SGVhZGVyIjoiKi8qIiwiaXAiOiI5MS4xMzcuMjA1LjExNyIsImNvbG9yRGVwdGgiOjI0LCJqYXZhRW5hYmxlZCI6ZmFsc2UsImxhbmd1YWdlIjoiZW4tVVMiLCJzY3JlZW5IZWlnaHQiOjg2NCwic2NyZWVuV2lkdGgiOjE1MzYsIndpbmRvd0hlaWdodCI6NzM0LCJ3aW5kb3dXaWR0aCI6MTQ3OSwidGltZSI6IjIwMjEtMTAtMDdUMTQ6NTU6NTIuODMyWiIsInRpbWV6b25lT2Zmc2V0IjotMTgwLCJ1c2VyQWdlbnQiOiJNb3ppbGxhLzUuMCAoWDExOyBMaW51eCB4ODZfNjQpIEFwcGxlV2ViS2l0LzUzNy4zNiAoS0hUTUwsIGxpa2UgR2Vja28pIENocm9tZS85Mi4wLjQ1MTUuMTU5IFNhZmFyaS81MzcuMzYifX0sImRhdGEiOnsiZXh0ZXJuYWxJZCI6IjAwMDAwNCIsInNlY3VyZUNvZGUiOiIxMjMifSwiaWF0IjoxNTM0ODY0MDI2fQ.May9uR8JQofJjmcUoD3pwhfUEtXhSzLuYtetPxzwsuc

{
   "params":{  
      "id":"11389a5a-efb5-4e1d-85c1-068df5bb0357",   		
      "sessionId":"690f8123-3a12-4eef-bcac-2fb82a34bd11",
      "device": {
         "acceptHeader": "*/*",
         "ip": "91.137.205.117",
         "colorDepth": 24,
         "javaEnabled": false,
         "language": "en-US",
         "screenHeight": 864,
         "screenWidth": 1536,
         "windowHeight": 734,
         "windowWidth": 1479,
         "time": "2021-10-07T14:55:52.832Z",
         "timezoneOffset": -180,
         "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.159 Safari/537.36"
      }
   },
   "data":{  
      "externalId":"000004", 
      "secureCode":"123"
   },
   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiaWQiOiIxMTM4OWE1YS1lZmI1LTRlMWQtODVjMS0wNjhkZjViYjAzNTciLCJzZXNzaW9uSWQiOiI2OTBmODEyMy0zYTEyLTRlZWYtYmNhYy0yZmI4MmEzNGJkMTEiLCJkZXZpY2UiOnsiYWNjZXB0SGVhZGVyIjoiKi8qIiwiaXAiOiI5MS4xMzcuMjA1LjExNyIsImNvbG9yRGVwdGgiOjI0LCJqYXZhRW5hYmxlZCI6ZmFsc2UsImxhbmd1YWdlIjoiZW4tVVMiLCJzY3JlZW5IZWlnaHQiOjg2NCwic2NyZWVuV2lkdGgiOjE1MzYsIndpbmRvd0hlaWdodCI6NzM0LCJ3aW5kb3dXaWR0aCI6MTQ3OSwidGltZSI6IjIwMjEtMTAtMDdUMTQ6NTU6NTIuODMyWiIsInRpbWV6b25lT2Zmc2V0IjotMTgwLCJ1c2VyQWdlbnQiOiJNb3ppbGxhLzUuMCAoWDExOyBMaW51eCB4ODZfNjQpIEFwcGxlV2ViS2l0LzUzNy4zNiAoS0hUTUwsIGxpa2UgR2Vja28pIENocm9tZS85Mi4wLjQ1MTUuMTU5IFNhZmFyaS81MzcuMzYifX0sImRhdGEiOnsiZXh0ZXJuYWxJZCI6IjAwMDAwNCIsInNlY3VyZUNvZGUiOiIxMjMifSwiaWF0IjoxNTM0ODY0MDI2fQ.May9uR8JQofJjmcUoD3pwhfUEtXhSzLuYtetPxzwsuc"
}

Відправлення запиту на сервер

У відповідь ми отримаємо:

{
    "status": 1,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdGF0dXMiOjEsImRhdGEiOnsiaWQiOiJkMTMyMjBiNS1kZDY0LTQxNzUtYjFiNi04NjQ0ZjM1NzgwNjciLCJrZXkiOiJFR3l6Ylhrd00yVkw5bko4Q2d3MzhnR1dzU3hxcFI1ejFvYmRKUVhRdFZMNy5qYzBiY3RpZjc0Mzc3NTYwMzY2NCJ9LCJpYXQiOjE1MzQ4NjQwMjZ9.i-HLZnu350_IvPs0q6_Y6v2KMQnR5aFi8ZB4iRp0z90"
    }
}

Де:

Параметр

Опис

Тип

Приклад

status

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

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

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

INT

1 або 0

token

Токен для розшифровки

STRING

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdGF0dXMiOjEsImRhdGEiOnsiaWQiOiJkMTMyMjBiNS1kZDY0LTQxNzUtYjFiNi04NjQ0ZjM1NzgwNjciLCJrZXkiOiJFR3l6Ylhrd00yVkw5bko4Q2d3MzhnR1dzU3hxcFI1ejFvYmRKUVhRdFZMNy5qYzBiY3RpZjc0Mzc3NTYwMzY2NCJ9LCJpYXQiOjE1MzQ4NjQwMjZ9.i-HLZnu350_IvPs0q6_Y6v2KMQnR5aFi8ZB4iRp0z90"

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

Тепер ми можемо розшифрувати відповідь. Для цього треба застосувати функцію decode бібліотеки jwt, передати їй ваш секретний ключ, параметр алгоритму (HS256) та рядок який ви отримали у відповіді після запиту у параметрі "token". В результаті ви отримаєте:

{  
   "status":1,
   "data":{  
      "id":"d13220b5-dd64-4175-b1b6-8644f3578067",
      "key":"EGyzbXkwM2VL9nJ8Cgw38gGWsSxqpR5z1obdJQXQtVL7.jc0bctif743775603664"
   }
}

Де:

Параметр

Опис

Тип

Приклад

status

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

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

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

INT

1 або 0

id

ІД платежу

STRING

"d13220b5-dd64-4175-b1b6-8644f3578067"

key

Ключ для підписання запиту

STRING

"EGyzbXkwM2VL9nJ8Cgw38gGWsSxqpR5z1obdJQXQtVL7.jc0bctif743775603664"

Крок 4: Перевірка статусу платежу

Після створення платежу

Тепер наш платіж знаходиться в одному з п'яти статусів. І нам потрібно з'ясувати в якому, бо від цього залежать наші подальші дії. Для початку виконаємо запит на /api/payments/ecom/show.

Про метод "show"

До цього методу нам потрібно буде звертатись кожного разу після виконання запиту для будь якої активної дії: спроби зняти гроші, спроби зарахувати гроші та спроби повторити транзакцію.

Написання запиту

{
  "params": {
    "sessionId":"b38cecd3-28db-41f4-9935-9f411ac7a5eb",
    "id": "a9cc5e84-64aa-44b0-b266-9c7298d68009"
  }
}

Де:

Параметр	Опис	Тип	Приклад
sessionId	id сесії яку ми отримали після розшифровки підписаної відповіді запиту на створення сесії. Цей параметр взагалі треба передавати у всіх запитах	STRING	"b38cecd3-28db-41f4-9935-9f411ac7a5eb"
id	id платежу	STRING	"a9cc5e84-64aa-44b0-b266-9c7298d68009"

Підписання запиту

Підписуємо запит таким саме чином, як і запит на створення сесії. Тобто, за допомогою бібліотеки jwt та ключа який ми отримали у кабінеті алгоритмом HS256. І отримуємо token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsic2Vzc2lvbklkIjoiYjM4Y2VjZDMtMjhkYi00MWY0LTk5MzUtOWY0MTFhYzdhNWViIiwiaWQiOiI3ODZkNDE0Ni03M2NiLTQ1NGItOTMyMi01ZjNjYzMyYzMwOTAifSwiaWF0IjoxNTM0ODY1NjEyfQ.bg_9TYgktD9bMuDqoSWsPY5c__MnfnK69W83cycVP20

{
    "status": 1,
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImE5Y2M1ZTg0LTY0YWEtNDRiMC1iMjY2LTljNzI5OGQ2ODAwOSIsInN0YXR1cyI6Ik5FRURTX0NPTkZJUk1BVElPTiIsImFtb3VudCI6MzAwMCwicGx1Z2luSWQiOjIsImNvbmZpcm1hdGlvbiI6eyJ0eXBlIjoiTE9PS1VQIiwiY29uZmlybWF0aW9uc0xlZnQiOjN9LCJpYXQiOjE1MzQ4NjYzMzJ9.uJkPdPtLpxAnXBBpJV7uqw26lRz_gu6hNjr_Os8deDU"
    }
}

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

Тепер ми можемо розшифрувати відповідь. Для цього треба застосувати функцію decode бібліотеки jwt, передати їй ваш секретний ключ, параметр алгоритму (HS256) та рядок який ви отримали у відповіді після запиту у параметрі "token". В результаті ви отримаєте:

У відповідь ми отримаємо статус платежу (для LOOKUP):

{
  "id": "a9cc5e84-64aa-44b0-b266-9c7298d68009",
  "status": "NEEDS_CONFIRMATION",
  "amount": 3000,
  "pluginId": 2,
  "confirmation": {
    "type": "LOOKUP",
    "confirmationsLeft": 3
  },
  "iat": 1534866332
}

Або отримаємо статус платежу (для 3Ds):

{
   "status": 1,
   "data": {
       "id": "a9cc5e84-64aa-44b0-b266-9c7298d68009",
       "status": "NEEDS_CONFIRMATION",
       "amount": 100,
       "pluginId": 1,
       "key": "C3ZwPKsoCkDbo6ryHDsicCtJBpwBa72ruQ7JKeTDgKRw.jp8j8up5583950198087",
       "confirmation": {
           "type": "3DS",
           "url": "https://3ds.ukrsotsbank.com:443/way4acs/pa?id=XAVajg551ggIMco69PYLaQ",
           "form": {
               "PaReq": "eJxVUm1v4jAM/sy/qPYDyEtpKSiLxK3aDena6zam0+7LqSoedIxQkvbG+PWzU5hYpKq2nyd2/NhqsbYA6SNUnQWtMnCuXEFQL6+vitkD7P+JaBQm0WgcjkIRX+mB8mE9GKj/YF29M1oM+VAqdnYRaUqjo2icCD4WMuZxJMNEMYoimIGt1qVp0R6ostr/mOc6kvEkFoqdXEK2YOep5v2R/Q8ZfZgIptyCXoBrg3PGYFG6X7XZBIp5kFjVrjOt/dAJHyl2dgjo7Jtet20zZUzIMbbAh2Ia4mFZMWcP4JqdcVDYXYWS1GY1fHWNYnQLL7OLJlTRke36eod6qbPFE8+OK5Gn1TFPs0P+OnvPUv9dK0YMYi7LFrTkIhGSh4FIpqGcCnykj3tttvRckpejMr1D8YbqzU4gYZcB33NnLZjqQ08SRL88guCAbQHycGBfNjV00YS6uTvNpmpR69nz4Ub8Ld5/vzxNnv+83f7Mbc3v95v7zd2RJuZJp9w1iismPPHJa6+0YpQOC/i1IeX8hqH1bfM+AdjVwPU="
           }
       },
       "redirect": {
           "url": "https://api.demo.uapay.ua/api/payments/ecom/confirm",
           "params": {
               "id": "2128d32f-0358-4a69-8566-9415a9ba02e1"
           },
           "directAcs": null
       }
   },
  "iat": 1534866332
}

Де:

Параметр	Опис	Тип	Приклад
status	Статус виконання операції перегляду статусу платежу. 1 - запит виконано успішно, 0 - сталась помилка при виконанні запиту	INT	1 або 0
Тіло відповіді
Id	id платежу в системі UAPAY	STRING	"a9cc5e84-64aa-44b0-b266-9c7298d68009"
status	Статус платежу. Може набувати одного з таких значень: "NEW" - нове замовлення, по ньому не було здійснено оплату "FINISHED" - завершене замовлення. Наш улюблений статус. Гроші було знято та зараховано на рахунки UAPAY, скоро ви отримаєте гроші на розрахунковий рахунок, який було вказано в налаштуваннях магазину "REJECTED" - платіж по замовленню не був здійснений по технічним причинам. Наприклад, платіж був відмінений банком через те, що картку платника було вкрадено. Або, можливо, злі тхори перегризли всі дроти в дата-центрах Amazon і ми впродовж довгого часу не змогли провести платіж, через що банк відмінив транзакцію. "NEEDS_CONFIRMATION" - платіж потребує підтвердження	STRING	"NEEDS_CONFIRMATION"
amount	Сума переказу в копійках	INT	3000
Інформація про підтвердження переказу (зараз ми зрозуміємо як цей переказ підтвердити для банку)
confirmation.url	Адреса для переадресації користувача на сторінку підтвердження його банку. Саме сюди ми будемо відправляти користувача для підтвердження переказу.	STRING	"https://acs.privatbank.ua/pPaReqMC.jsp"
type	Тип підтвердження що вимагає банк для цієї картки. Може мати одне з двох значень: 3DS - найпоширеніший та найбільш надійний спосіб підтвердження. Для нього потрібно буде відправити користувача на сторінку банку. LOOKUP - не такий поширений спосіб підтвердження. Для нього потрібно створити сторінку с полем для вводу LOOKUP коду який банк самостійно вже відправив нашому платнику на його номер телефону, що прив'язано до картки.	STRING	"3DS" або "LOOKUP"
Параметри для формування запитів для 3DS підтвердження
PaReq	id переказу в системі банку	STRING	"eJxVUttOwzAMfd5fVHzAknRJ2k4h0mAPTKLTgPKMqs5iBZaVpOX29djphkakqvY5thMf21Q7D7B8gGbwYE0JIdTPkLTby4vN4h7e..."
Інформація для формування URL для повернення платника після підтвердження оплати
redirect.url	Базова частина посилання	STRING	"https://api.demo.uapay.ua/api/payments/ecom/confirm"
id	id платежу в системі UAPAY	STRING	"856af8d2-7d14-45b8-b6f1-89c1fa33c538"

Крок 5: Підтвердження платежу

Орієнтуючись на поле type ми знаємо який спосіб підтвердження потрібно використовувати для цього конкретного платежу. (3DS або LOOKUP)

3DS
Для цього нам потрібно відправити за допомогою POST-запиту, на URL котрий ми отримали після використання методу show в блоці confirmation в параметрі url, HTML документ:

<!DOCTYPE html>
<html>

<head>
	<title>ASC Test page</title>
</head>
<body>
	<script type="text/javascript">
		"use  strict";
		var form = document.createElement('form');
		form.setAttribute('method', 'post');
		form.setAttribute('action', 'confirmation:url');
		var termUrl = document.createElement('input');
		termUrl.setAttribute('type', 'hiden');
		termUrl.setAttribute('name', 'TermUrl');
		termUrl.setAttribute('value', 'redirect: url ? id = redirect : params: ID &key = key &redirect = agent_page_return / ID'); 
var  paReq  =  document.createElement('input '); 
paReq.setAttribute('type','hiden'); 
paReq.setAttribute('name','PaReq'); 
paReq.setAttribute('value', 'confirmation:form:PaReq'); 
form.appendChild(termUrl); 
form.appendChild(paReq); 
form.submit();
</script>
</body>
</html>

Приклад HTTP

<html>
<body>
   <form action="https://3ds.ukrsotsbank.com:443/way4acs/pa?id=XAVUoBtXGhzJgb9Ea7dAGw" method="POST">
       <input name="TermUrl" value="https://api.demo.uapay.ua/api/payments/ecom/confirm?id=a9cc5e84-64aa-44b0-b266-9c7298d68009&redirect=https://api.demo.uapay.ua&key=8awXLEQW2HEEvfGMVvZRSRtqE8JprPSASjtYWXG5godK.jp8icbcj38284959294" type="hidden"></input>
       <input name="PaReq" value="eJxVUk1v2zAMPedfGL0WiD4cO0qgCvCaAQs2F0HnHnYqPIdInC6KI8lL2l8/Uk6KTIBgku+JNB+pq60DWPyEpndgdAne1xtI2vXD3ap4huOryCapylIpcq7EnRnpGDajkf4LzrcHa8SYj6VmVxeRrrYmy6ZK8KmQOc8zmSrNKIpgCa7Z1jagPdJ1c/yyfDKZzGe50OziErIHt1wYPhw5fJAxhIlg6z2YCnxIrhmTqvY/WvuWaBZBYjWH3gb3bhSfaHZ1COjdH7MNoZszJuQUW+BjMU/xsHK1ZM/gu4P1sHKHBiVp7Wa8851m9Aofs5sm9Kon2w/1zu3alNULLz82ovxYnp92xaSsilO5iPdBM2IQc10HMJILJSRPE6HmPJ9nuWYxHrXZ0++SvByVGRyKd1SvuICE3QZiz71zYJt3M1OIfnoEwRnbAuThwD5tauimCf347TKbJqDWxa9wbwt3+r4/ulMVut1O5u35ZfH17fE3TSySLrlbFFfMuIrJ26i0ZpQOC8S1IeXihqH13+b9A9lCwVw=" type="hidden"></input>
   </form>
   <script>
   document.getElementsByTagName('form')[0].submit();
   </script>
</body>
</html>

В цьому HTML-документі, у рядку redirect: url?id=redirect:params:ID&key=key &redirect=agent_page_return/ID');

треба вказати такі параметри:

Параметр	Опис	Приклад
url	Це URL до якого треба звернутись для того, щоб підтвердити платіж. Він завжди є одним і тим самим, а саме https://api.uapay.ua/api/payments/ecom/confirm - для продакшену та https://api.demo.uapay.ua/api/payments/ecom/confirm - для тесту. Після нього потрібно вказати в якості get-параметрів данні які описано нижче	https://api.uapay.ua/api/payments/ecom/confirm
id redirect	id платежу в системі UAPAY, який отримали на 3 кроці	"856af8d2-7d14-45b8-b6f1-89c1fa33c538"
key	Ключ для підписання запиту, який отримали на 3 кроці	"GDzGwLo3wfKnC6aLdHjjFU7LfKZxG1ZbQzFiGiQxH4Ss.jhc1olcx1562559385"
redirect	Адреса сторінки на сайті продавця, на яку потрібно буде направити користувача після того, як він проведе підтвердження транзакції. Зазвичай це URL thank you page	http://test-shop.com/success/

Після цього потрібно знову викликати кілька разів метод show для отримання інформації про статус платежу (тому що користувач може не одразу виконати підтвердження).

LOOKUP

Для підтвердження платежу картою без 3DS захисту використовується lookup code.
Банк надсилає цей код в смс на номер, який закріплений за картою. Вам потрібно буде намалювати форму, в яку ваш користувач впише надісланий йому код.

Далі відправляємо ці дані методом POST на /api/payments/ecom/confirm

Після створення замовлення та платежу (крок 3) потрібно підтвердити платіж для його проведення

Написання запиту

Напишемо запит на підтвердження платежу:

{
    "params": {
        "sessionId": "28e3f909-8e3b-4ea6-82f8-9b7f57525e66",
        "id": "b56aa0fb-7811-4df3-839e-c409b1d0ad2f",
        "code": "111111",
        "key": "Fb9eM8mA5ukS5pGkoyXp1dNsQzmJM9KViDxNxyUdzBT5.jkuehx6121848551587"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsic2Vzc2lvbklkIjoiMjhlM2Y5MDktOGUzYi00ZWE2LTgyZjgtOWI3ZjU3NTI1ZTY2IiwiaWQiOiJiNTZhYTBmYi03ODExLTRkZjMtODM5ZS1jNDA5YjFkMGFkMmYiLCJjb2RlIjoiMTExMTExIiwia2V5IjoiRmI5ZU04bUE1dWtTNXBHa295WHAxZE5zUXptSk05S1ZpRHhOeHlVZHpCVDUuamt1ZWh4NjEyMTg0ODU1MTU4NyJ9LCJpYXQiOjE1MzQyOTMwODh9.IF2bE1PYB-BctwjYueeoiBdXr5AjamWyDEA8yhsEv_0"
}

Де:

Параметр	Опис	Тип	Обов'язковий параметр чи ні?	Приклад
Параметри
sessionId	id сесії яку ми отримали після розшифровки підписаної відповіді попереднього запиту. Цей параметр взагалі треба передавати у всіх запитах	STRING	Так	"4bda7e34-a1c7-4587-b43b-06c506388ce7"
id	Id платежу (який було створено на 3 кроці)	STRING	Так	"b56aa0fb-7811-4df3-839e-c409b1d0ad2f"
code	Код підтвердження платежу	STRING	Так	"111111"
key	Ключ платежу, який було отримано на кроці створення платежу (3 крок)	STRING	Так	"Fb9eM8mA5ukS5pGkoyXp1dNsQzmJM9KViDxNxyUdzBT5.jkuehx6121848551587"

Підписання запиту

Підписуємо запит таким саме чином, як і запит на створення сесії. Тобто, за допомогою бібліотеки jwt та ключа який ми отримали у кабінеті алгоритмом HS256. І отримуємо token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsic2Vzc2lvbklkIjoiMjhlM2Y5MDktOGUzYi00ZWE2LTgyZjgtOWI3ZjU3NTI1ZTY2IiwiaWQiOiJiNTZhYTBmYi03ODExLTRkZjMtODM5ZS1jNDA5YjFkMGFkMmYiLCJjb2RlIjoiMTExMTExIiwia2V5IjoiRmI5ZU04bUE1dWtTNXBHa295WHAxZE5zUXptSk05S1ZpRHhOeHlVZHpCVDUuamt1ZWh4NjEyMTg0ODU1MTU4NyJ9LCJpYXQiOjE1MzQyOTMwODh9.IF2bE1PYB-BctwjYueeoiBdXr5AjamWyDEA8yhsEv_0

Відправлення запиту на сервер

Запит треба виконати методом POST, тіло запиту має бути у форматі application/json. Адреса https://api.demo.uapay.ua/api/payments/ecom/confirm

У відповідь ми отримаємо:

{
    "status": 1,
    "data": {}
}

Де:

Параметр

Опис

Тип

Приклад

status

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

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

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

INT

1 або 0

Крок 6: Перевірка статусу платежу

От ми з вами і дали користувачеві посилання на оплату платежу. Для цього виконаємо POST запит на URL https://api.demo.uapay.ua /api/payments/ecom/show:

{
 "params":{
 "sessionId":"4bda7e34-a1c7-4587-b43b-06c506388ce7",
 "id":"c375eefd-3c46-48d9-a671-17f3be600a98"
 }
}

Де:

Параметр	Опис	Тип	Приклад
sessionId	id сесії який ми отримали у першому запиті, коли відкривали сесію	STRING	1 або 0
id	id платежу у системі UAPAY	STRING	"73a40e15-7b4b-45e5-a7a2-a24e2483c933"

Звичайно, запит нам треба підписати ключем який ми отримали в кабінеті за допомогою бібліотеки jwt методом шифрування HS256.

У відповідь, після розшифровки підписаного запиту, ми отримаємо щось на зразок:

{
   "status": 1,
   "data": {
       "id": "a9cc5e84-64aa-44b0-b266-9c7298d68009",
       "status": "HOLDED",
       "amount": 100
   }
}

Де:

Параметр	Опис	Тип	Приклад
status	Статус виконання операції перегляду статусу платежу. 1 - запит виконано успішно, 0 - сталась помилка при виконанні запиту	INT	1 або 0
Тіло відповіді
Id	id платежу в системі UAPAY	STRING	"a9cc5e84-64aa-44b0-b266-9c7298d68009"
status	Статус переказу. Може набувати таких значень: "HOLDED" - платіж підтверджений "REJECTED" - платіж не був здійснений по технічним причинам. Наприклад, платіж був відмінений банком через те, що картку платника було вкрадено. "CANCELED" - платіж скасовано.	STRING	"HOLDED"
amount	Сума переказу в копійках	INT	100

Які картки мені використовувати для тестування?

Для тестування ви можете використовувати будь яку картку MasterCard із 3DS захистом, окрім карток Монобанк. При зверненнях до тестового середовища гроші не будуть зніматись з картки, але транзакція завершиться корректно. Також, ви можете штучно створити помилку, наприклад, якщо на картці є 100 гривень, а ви спробуєте здійснити транзакцію на 102 гривні, сервер UAPAY поверне помилку "недостатньо грошей на рахунку".

Про продукційне середовище (production)

Запити до production середовища виконуються так само як і до тестового.

URL до якого треба звертатись: https://api.uapay.ua/api/<method>, де <method> це назва методу до якого ми хочемо звернутись.

Нічого не зрозуміло?

Ну то не страшно. Але треба буде трохи розібратись із тим, як працює інтернет та програмування взагалі для того, щоб створювати web-додатки. Для початку ознайомтеся із тим як працює http. А за допомогою Postman можна буде виконувати запити до нашого API без використання мов програмування. Це дозволить вам зрозуміти як взагалі працювати із API.