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

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

Owned by Ihor Balimasov
Last updated: 357 06, 2021 by antonina smetanina (Unlicensed)
11 min read

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

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

  1. Написати запит на створення сесії
  2. Підписати його за допомогою бібліотеки jwt
  3. Виконати запит на створення сесії
  4. Отримати відповідь і розшифрувати її, там ми отрмаємо 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 - сталась помилка при виконанні запиту

INT1 або 0
token

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

STRING

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImIzOGNlY2QzLTI4ZGItNDFmNC05OTM1LTlmNDExYWM3YTVlYiIsImlhdCI6MTUzNDg2Mjg0Mn0.cXRUNzI75I3HKlE25Uzy3N-CmGDfVE4K5de98sGJmAg"


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

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

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

Де:

Параметр

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

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

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

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

INT1 або 0
id

id сесії

STRING

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

iat

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

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

INT1534862842


Крок 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.sessionIdID сессіії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 - сталась помилка при виконанні запиту

INT1 або 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.

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

  1. Написати запит на створення платежу, додати в нього id сесії
  2. Підписати його за допомогою бібліотеки jwt
  3. Виконати запит на створення платежу
  4. Отримати відповідь та розшифрувати її. У відповіді будуть номер замовлення, номер платежу, 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"
secureCodeCVVSTRINGТак"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 - сталась помилка при виконанні запиту

INT1 або 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 - сталась помилка при виконанні запиту

INT1 або 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 - сталась помилка при виконанні запиту

INT1 або 0
Тіло відповіді
Id

id платежу в системі UAPAY

STRING"a9cc5e84-64aa-44b0-b266-9c7298d68009"
status

Статус платежу. Може набувати одного з таких значень:

"NEW" - нове замовлення, по ньому не було здійснено оплату

"FINISHED" - завершене замовлення. Наш улюблений статус. Гроші було знято та зараховано на рахунки UAPAY, скоро ви отримаєте гроші на розрахунковий рахунок, який було вказано в налаштуваннях магазину

"REJECTED" - платіж по замовленню не був здійснений по технічним причинам. Наприклад, платіж був відмінений банком через те, що картку платника було вкрадено. Або, можливо, злі тхори перегризли всі дроти в дата-центрах Amazon і ми впродовж довгого часу не змогли провести платіж, через що банк відмінив транзакцію.

"NEEDS_CONFIRMATION" - платіж потребує підтвердження

STRING"NEEDS_CONFIRMATION"
amountСума переказу в копійкахINT3000
Інформація про підтвердження переказу (зараз ми зрозуміємо як цей переказ підтвердити для банку)
confirmation.urlАдреса для переадресації користувача на сторінку підтвердження його банку. Саме сюди ми будемо відправляти користувача для підтвердження переказу.STRING"https://acs.privatbank.ua/pPaReqMC.jsp"
type

Тип підтвердження що вимагає банк для цієї картки. Може мати одне з двох значень:

3DS - найпоширеніший та найбільш надійний спосіб підтвердження. Для нього потрібно буде відправити користувача на сторінку банку.

LOOKUP - не такий поширений спосіб підтвердження. Для нього потрібно створити сторінку с полем для вводу LOOKUP коду який банк самостійно вже відправив нашому платнику на його номер телефону, що прив'язано до картки.

STRING"3DS" або "LOOKUP"
Параметри для формування запитів для 3DS підтвердження
PaReqid переказу в системі банкуSTRING"eJxVUttOwzAMfd5fVHzAknRJ2k4h0mAPTKLTgPKMqs5iBZaVpOX29djphkakqvY5thMf21Q7D7B8gGbwYE0JIdTPkLTby4vN4h7e..."
Інформація для формування URL для повернення платника після підтвердження оплати
redirect.urlБазова частина посиланняSTRING"https://api.demo.uapay.ua/api/payments/ecom/confirm"
idid платежу в системі UAPAYSTRING"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 redirectid платежу в системі UAPAY, який отримали на 3 кроці"856af8d2-7d14-45b8-b6f1-89c1fa33c538"
keyКлюч для підписання запиту, який отримали на 3 кроці"GDzGwLo3wfKnC6aLdHjjFU7LfKZxG1ZbQzFiGiQxH4Ss.jhc1olcx1562559385"
redirectАдреса сторінки на сайті продавця, на яку потрібно буде направити користувача після того, як він проведе підтвердження транзакції. Зазвичай це URL thank you pagehttp://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"
    idId платежу (який було створено на 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 - сталась помилка при виконанні запиту

    		INT1 або 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 сесії який ми отримали у першому запиті, коли відкривали сесію

STRING1 або 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 - сталась помилка при виконанні запиту

INT1 або 0
Тіло відповіді
Id

id платежу в системі UAPAY

STRING"a9cc5e84-64aa-44b0-b266-9c7298d68009"
status

Статус переказу. Може набувати таких значень:

"HOLDED" - платіж підтверджений

"REJECTED" - платіж не був здійснений по технічним причинам. Наприклад, платіж був відмінений банком через те, що картку платника було вкрадено.

"CANCELED" - платіж скасовано.

STRING"HOLDED"
amountСума переказу в копійкахINT100


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

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

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

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

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


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

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

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