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

Швидкий старт

Про тестове середовище

Яким чином можна виконати запит?

  1. Усі запити до API UAPAY треба підписувати ключем який можна отримати у вашому кабінеті. Підпис відбувається за допомогою jwt алгоритм шифрування HS256
  2. Усі запити потрібно виконувати http методом POST. Тип контенту запиту - application/json
  3. Для того щоб робити запити до тестового середовища (sanbox) треба їх всі відправляти на URL https://api.demo.uapay.ua/api/<method>де <method> це назва методу до якого ми хочемо звернутись

(warning) Оплата на тестовому середовщі доступна лише наступними картами

(warning) Доступ для продуктового середовища  знаходиться за посиланням https://api.uapay.ua/api/<method>, де <method> це назва методу до якого ми хочемо звернутись


Про iat

Для додаткового захисту від типів атаки man in middle ми перевіряємо час створення запиту на стороні мерчанта. Якщо час створення запиту та його отримання UAPAY відрізняються більше ніж на 20 секунд, то в цьому разі буде повернуто помилку

{"error":{"code":"TIMELIMIT_ERROR"}}

Реєстрація у системі, та отримання ключа

UAPAY потрібно ідентифікувати додатки які ініціюють оплату. Для цього використовується механізм приватних ключів. Реалізовано його з використанням  JSON Web Tokens library (jwt). Також, для ідентифікації магазину використовується унікальний id.

Як отримати ключі для підпису запитів та id магазину?

У вашому обліковому записі може буди безліч "магазинів". Один магазин - це один рахунок у банку на який будуть перераховуватись гроші. Всі люблять гроші, тому ви можете мати кілька рахунків у одному обліковому записі. І для того щоб ми розуміли на який рахунок перераховувати ваші надходження, а з'єднання із сервером було безпечне, ми використовуємо механізм унікальних ключів.

Усі запити до API UAPAY треба підписувати ключем який можна отримати у вашому кабінеті. Для того щоб при розробці не витрачати реальні гроші з карток, можна виконувати усі операції у тестовому середовищі. 

Для початку, вам потрібно перейти за цим посиланням та зареєструвати обліковий запис. Далі, перейти на сторінку "Мої магазини" та натиснути на велику червону кнопку "Створити магазин" (менеджери люблять великі червоні кнопки (smile))

Після заповнення трьох обов'язкових полів ваш магазин буде створено. І при натисненні на напис "Натисніть тут щоб побачити secret key" ви побачите секретний ключ для підпису тестових записів. Ключ є статичним. Після того як ви завершите розробку, тестовий ключ можна буде змінити на реальний.

Далі, ми переходимо до редагування магазину:

Пам'ятайте

Зберігання ключів у відкритому вигляді в репозиторії не є дуже безпечним способом. Краще їх хоча б зашифрувати із допомогою git-remote-gcrypt або BlackBox.


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

Підпис або верифікація запитів проводиться за допомогою алгоритму HS256. З боку UAPAY буде згенеровано і надано секретний ключ, необхідний для підпису запитів та верифікації відповідей.

Payload (корисне навантаження, далі по тексту - payload) в запиті передається в параметрі "token"Payload представляє собою JWT-токен, сформований з JSON-об'єкту з потрібними параметрами і підписаного вашим секретним ключем (далі по тексту - secretKey) за алгоритмом HS256. Підписанню підлягають всі запити. Опис стандарту роботи з бібліотекою і приклади можете знайти за посиланням https://jwt.io/

Структура payload объкета
{  	
   "params":{/*поля в залежності від запиту (може бути не заповненим)*/
   },
   "data":{
   },
   "iat": 1529927552
}

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

Підпишемо наш запит за допомогою jwt та алгоритму HS256 функцією sign

Приклад запиту без підпису
{
"params": {
"clientId": "1"
},
"iat": 1529927552
}

Структура объекта запроса

token = jwt.sign(payloadObject, secretKey, algorithm: HS256)

Приклад сформованного токену
>>>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOiIxMzIifSwiaWF0IjoxNTI5OTI3NTUyfQ.I3Ap79vaShIxuBFjbB-8gs1d2j1EoEVchf0DP0DGICg

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

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

Приклад підписанного запиту
{
"params": {
"clientId": "1"
},
"iat": 1529927552,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOiIxMzIifSwiaWF0IjoxNTI5OTI3NTUyfQ.I3Ap79vaShIxuBFjbB-8gs1d2j1EoEVchf0DP0DGICg"
}

де:

Параметр

ОписТипЧи обов'язковий це параметр?Приклад
clientid

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

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

STRINGТак1
iat

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

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

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

INTТак1529927552
token

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

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

STRINGТак

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJhbXMiOnsiY2xpZW50SWQiOiIxMzIifSwiaWF0IjoxNTI5OTI3NTUyfQ.I3Ap79vaShIxuBFjbB-8gs1d2j1EoEVchf0DP0DGICg"

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

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

Приклад відповіді
{
 "status":1,
 "data":{
 "id":"4bda7e34-a1c7-4587-b43b-06c506388ce7"
 }
}

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