Для того щоб робити запити до тестового середовища (sanbox) треба їх всі відправляти на URL https://api.demo.uapay.ua/api/<method>, де <method> це назва методу до якого ми хочемо звернутись
Оплата на тестовому середовщі доступна лише наступними картами
Доступ для продуктового середовища знаходиться за посиланням https://api.uapay.ua/api/<method>, де <method> це назва методу до якого ми хочемо звернутись
Для додаткового захисту від типів атаки man in middle ми перевіряємо час створення запиту на стороні мерчанта. Якщо час створення запиту та його отримання UAPAY відрізняються більше ніж на 20 секунд, то в цьому разі буде повернуто помилку {"error":{"code":"TIMELIMIT_ERROR"}} |
UAPAY потрібно ідентифікувати додатки які ініціюють оплату. Для цього використовується механізм приватних ключів. Реалізовано його з використанням JSON Web Tokens library (jwt). Також, для ідентифікації магазину використовується унікальний id.
У вашому обліковому записі може буди безліч "магазинів". Один магазин - це один рахунок у банку на який будуть перераховуватись гроші. Всі люблять гроші, тому ви можете мати кілька рахунків у одному обліковому записі. І для того щоб ми розуміли на який рахунок перераховувати ваші надходження, а з'єднання із сервером було безпечне, ми використовуємо механізм унікальних ключів.
Усі запити до API UAPAY треба підписувати ключем який можна отримати у вашому кабінеті. Для того щоб при розробці не витрачати реальні гроші з карток, можна виконувати усі операції у тестовому середовищі.
Для початку, вам потрібно перейти за цим посиланням та зареєструвати обліковий запис. Далі, перейти на сторінку "Мої магазини" та натиснути на велику червону кнопку "Створити магазин" (менеджери люблять великі червоні кнопки )
Після заповнення трьох обов'язкових полів ваш магазин буде створено. І при натисненні на напис "Натисніть тут щоб побачити secret key" ви побачите секретний ключ для підпису тестових записів. Ключ є статичним. Після того як ви завершите розробку, тестовий ключ можна буде змінити на реальний.
Далі, ми переходимо до редагування магазину:
Зберігання ключів у відкритому вигляді в репозиторії не є дуже безпечним способом. Краще їх хоча б зашифрувати із допомогою git-remote-gcrypt або BlackBox. |
Формування підпису запитів
Підпис або верифікація запитів проводиться за допомогою алгоритму HS256. З боку UAPAY буде згенеровано і надано секретний ключ, необхідний для підпису запитів та верифікації відповідей.
Payload (корисне навантаження, далі по тексту - payload) в запиті передається в параметрі "token". Payload представляє собою JWT-токен, сформований з JSON-об'єкту з потрібними параметрами і підписаного вашим секретним ключем (далі по тексту - secretKey) за алгоритмом HS256. Підписанню підлягають всі запити. Опис стандарту роботи з бібліотекою і приклади можете знайти за посиланням https://jwt.io/
{ "params":{/*поля в залежності від запиту (може бути не заповненим)*/ }, "data":{ }, "iat": 1529927552 } |
Підпишемо наш запит за допомогою 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" |
Для розшифровки запиту необхідно виконати функцію decode бібліотеки jwt, в параметрах передати ваш секретний ключ, параметр алгоритму (HS256) та рядок який ви отримали у відповіді після запиту у параметрі "token". В результаті ви отримаєте
{ "status":1, "data":{ "id":"4bda7e34-a1c7-4587-b43b-06c506388ce7" } } |