JSON протокол

створив(ла) Igor Uleschenko — Востаннє змінено: Вер 16, 2019 17:23

UKRAINIAN PROCESSING CENTER

Kyiv

JSON протокол
взаємодії торговця з платіжним шлюзом

2019

Використання протоколу дозволяє торговцям, які не володіють сертифікатом безпеки PCI DCC здійснювати оплати не використовуючи захищену сторінку UPC. Для заміни номеру банківської картки було створено механізм токенізації що дозволяє отримати токен картки (текстову величину асоційовану з номером платіжної картки) за допомогою якої можливо надсилати запити на оплату.

Механізм отримання токену:

Торговцю потрібно зв’язатися з відділом електронної комерції (ec@upc.ua) та здійснити запит на активацію послуги токенізації.
Також потрібно звернутися до банку торговця з проханням налаштувати максимально дозволену суму до оплати без участі CVV коду картки платника (дозволяє проводити операції списання використовуючи лише токен картки без підтвердження клієнта). Якщо сума оплати перевищує встановлену банком дозволену суму, в запиті на оплату поряд з токеном картки має бути присутнє поле CVV2 коду.
Торговець здійснює первинну операцію списання з платіжної картки клієнта через захищену сторінку (протокол взаємодії HTTPS )
Після оплати на вказану в кабінеті торговця NOTIFY адресу надсилається стандартне повідомлення NOTIFY повідомлення з додатковою величиною UPCToken
UPCToken - величина асоційована з номером картки, яку потрібно зберегти торговцю для подальших операцій списання з картки клієнта без участі захищеної сторінки UPC.

Для використання методу оплати через JSON торговцю потрібно сформувати запит на оплату згідно формату нижче (всі дані запиту закодовані в base64)

Структура запиту

{
header:"….base64 encoded data….",
payload:" ….base64 encoded data…. ",
signature:" ….base64 encoded $signature …."}

header => {"alg":"RS256"}- стандартний для всіх запитів

header:"eyJhbGciOiJSUzI1NiJ9"

Набір дозволених полів payload

Параметр	Структура	Формат	Наименование (назначение) параметра	Доп. комментарий
MerchantID	L	an15	Ідентифікатор торговця	Призначається обслуговуючим банком
TerminalID	F	an8	Ідентифікатор терміналу	Призначається обслуговуючим банком
TotalAmount	F	N1..12	Сума замовлення	В найменших одиницях (копійки)
Currency	F	n3	Валюта	Визначається обслуговуючим банком
PurchaseTime	F	n12..17	Час запиту в форматі yyMMddHHmmss или yyMMddHHmmssZ	yy - year MM - month in year dd - day in month HH - hour in day (0-23) mm - minute in hour ss - second in minute Z - time zone (RFC 822)
OrderID	L	Ans…20	Номер замовлення довжиною до 20 байт
PurchaseDesc (Опционально)	L	ans...1 25	Короткий опис покупки
UPCToken			Токен. Отриманий від шлюзу після первинної транзакції	Замінює номер картки клієнта і дозволяє торговцю робити списання з картки без участі власника картки
Recurrent			Ознака рекурентності	Допустимі значенн Recurrent:”true” – використовується при первинній транзакції для активації механізму рекурентності і отримання від емітенту ідентифікатору транзакції Recurrent:” 387295757037435” – ідентифікатор первинної транзакції який при наступних списаннях маркує транзакції як subsequent (наступні після оригінальної) і маркує їх в одну спільну послідовність операцій клієнта
CVV			CVV2 код картки клієнта	Використовується коли сума транзакції перевищує дозволену банком суму операції без CVV2 коду.

Приклад набору даних

{MerchantID:"1753945",TerminalID:"E7881945",OrderID:"885566",UPCToken:"1C7C5633F05FA76C4F29B375AC1BBEAE",TotalAmount:100,Currency:980,PurchaseTime:"180919174126",PurchaseDesc:"Test token"}

Формування поля Signature JSON запиту

ЕЦП формується на основі закодованих в base64 даних header об’єднаних конкатенацією з payload (об’єднується без додаткових розділових знаків в одну текстову величину)

datafile =”header”.”payload”

Підпис даних отримуємо стандартними функціями OPENSSL

Отриману величину підпису конвертуємо в base64 ідентично header і payload

Отриманий запит на оплату

{header:"eyJhbGciOiJSUzI1NiJ9",

payload:"e01lcmNoYW50SUQ6IjE3NTM5NDUiLFRlcm1pbmFsSUQ6IkU3ODgxOTQ1IixPcmRlcklEOiI1NTk5IixVUENUb2tlbjoiMUM3QzU2MzNGMDVGQTc2QzRGMjlCMzc1QUMxQkJFQUUiLFRvdGFsQW1vdW50OjEwMCxDdXJyZW5jeTo5ODAsUHVyY2hhc2VUaW1lOiIxODA5MTkxNzQxMjYiLFB1cmNoYXNlRGVzYzoiVGVzdCB0b2tlbiIsUmVjdXJlbnQ6InRydWUifQ==",

signature:"EXDEhK9kMK0lwTEWH4mm1oJvKm5vVFyXnyDnqEDHDc3mYyXEhLv3Ih6_fdmN-apUPxgV5GEpV0YQWTuSyGF3o32dF0n-A4LrZ93z8Dw7gj9ULLd5ffRE42x0tFL6jNNEnVUbj8WB1UeR6mRN4l4aTRaNU123hq6UIqB_jsTxWJU"}

Адреса шлюзу оплати для JSON - https://ecg.test.upc.ua/go/payByToken

Приклад відповіді шлюзу закодований в base64

{

"header": "eyJhbGciOiJSUzUxMiJ9",

"payload": "eyJNZXJjaGFudElEIjoiMTc1Mzk0NSIsIlRlcm1pbmFsSUQiOiJFNzg4MTk0NSIsIkFwcHJvdmFsQ29kZSI6IjkyNTMwMCIsIlJybiI6IjkyMzQxNjg3NTE1OCIsIkhvc3RDb2RlIjoiMDAwIiwiUmVjdXJyZW50IjoiMzg3Mjk1NzU3MDM3NDM1IiwiVHJhbkNvZGUiOiIwMDAiLCJDb21tZW50IjoiQXBwcm92ZWQifQ",

"signature": "jTUTpFY8Jzxrg8Ud8dUdEVN3pH0ubz9nKemQW5mWFi1Jl6Rd9veb4Zz436GnWKHsOYNOSc_h99Z8Yf67E1NmgFmTgujzCgRp07hXazYbyFthLsheB4dDdgrRYPhtGyLuZmuZ1grwWdcIXG36dvKC1Zc3WQMJV4CvvAeNGR0coNM"

}

Base64 decoded

{"MerchantID":"1753945","TerminalID":"E7881945","ApprovalCode":"925300","Rrn":"923416875158","HostCode":"000","TranCode":"000","Comment":"Approved"}

Перелік можливих полів отриманих у відповідь на запит оплати від шлюзу

Параметр	Наименование (назначение) параметра	Доп. комментарий
MerchantID	Ідентифікатор торговця	Призначається обслуговуючим банком
TerminalID	Ідентифікатор терміналу	Призначається обслуговуючим банком
ApprovalCode	Код авторизації в банку	Код авторизації в банку
Rrn	Reference Retrieval Number	Reference Retrieval Number
HostCode	Код транзакціі на хосту авторизації	Додаткове інформаційне поле із значення коду транзакції в авторизації
TranCode	Код транзакції	Код транзакції
Comment
Recurrent	Ознака рекурентності	Recurrent:” 387295757037435” – ідентифікатор первинної транзакції який при наступних списаннях маркує транзакції як subsequent (наступні після оригінальної) і маркує їх в одну спільну послідовність операцій клієнта

Запит статусу платежу через протокол JSON

Адресу шлюзу для запиту - https://ecg.test.upc.ua/go/service/01

Обов’язковий набір полів для запиту статусу

Параметр	Структура	Формат	Наименование (назначение) параметра	Доп. комментарий
MerchantID	L	an15	Ідентифікатор торговця	Призначається обслуговуючим банком
TerminalID	F	an8	Ідентифікатор терміналу	-- // --
TotalAmount	F	N1..12	Сума замовлення	В найменших одиницях (копійки)
Currency	F	n3	Валюта	Визначається обслуговуючим банком
PurchaseTime	F	n12..17	Час запиту в форматі yyMMddHHmmss или yyMMddHHmmssZ	yy - year MM - month in year dd - day in month HH - hour in day (0-23) mm - minute in hour ss - second in minute Z - time zone (RFC 822)
OrderID	L	Ans…20	Номер замовлення довжиною до 20 байт

Приклад набору полів для статусу транзакції

payload =>
{MerchantID:"1753945",TerminalID:"E7881945",OrderID:"9989",TotalAmount:100,Currency:980,PurchaseTime:"180919174126"}

purchaseTime – час транзакції має бути ідентичним часу оригінальної транзакції для якої здійснюється запит статусу

Всі дані запиту кодуються в формати base64. Формування підпису відбувається аналогічно запиту оплати.

{header:"eyJhbGciOiJSUzI1NiJ9",

payload:"e01lcmNoYW50SUQ6IjE3NTM5NDUiLFRlcm1pbmFsSUQ6IkU3ODgxOTQ1IixPcmRlcklEOiI5OTg5IixUb3RhbEFtb3VudDoxMDAsQ3VycmVuY3k6OTgwLFB1cmNoYXNlVGltZToiMTgwOTE5MTc0MTI2In0=",

signature:"EXDEhK9kMK0lwTEWH4mm1oJvKm5vVFyXnyDnqEDHDc3mYyXEhLv3Ih6_fdmN-apUPxgV5GEpV0YQWTuSyGF3o32dF0n-A4LrZ93z8Dw7gj9ULLd5ffRE42x0tFL6jNNEnVUbj8WB1UeR6mRN4l4aTRaNU123hq6UIqB_jsTxWJU"}

Приклад відповіді
{
"header": "eyJhbGciOiJSUzUxMiJ9",
"payload": "eyJyZXN1bHRzIjpbeyJ0cmFuQ29kZSI6IjAwMCIsImFwcHJvdmFsQ29kZSI6IjUxNDI5NyIsInJybiI6IjkyMzQxNTg3NTIwNCIsImNvbW1lbnQiOiJBcHByb3ZlZCIsImNhcmROdW1NYXNrZWQiOiI0OTk5OTkqKioqKiowMDExIiwidHJhblRpbWUiOiIyMDE5LTA4LTIyIDE1OjE1OjIwLjcwMiIsImFtb3VudCI6MTAwLCJjdXJyZW5jeSI6Ijk4MCIsIm9wZXJUeXBlIjoiUkVDVVJSRU5UIFNVQlNFUVVFTlQiLCJhY3Rpb25Db2RlIjoiMDAwIn0seyJ0cmFuQ29kZSI6IjQxMCIsImNvbW1lbnQiOiJUaGUgb3JkZXIgd2FzIHBhaWQgKHBvc3NpYmxlIHJlcGxheSkiLCJjYXJkTnVtTWFza2VkIjoiNDk5OTk5KioqKioqMDAxMSIsInRyYW5UaW1lIjoiMjAxOS0wOC0yMiAxNjo1MDo1MS4wODYiLCJhbW91bnQiOjEwMCwiY3VycmVuY3kiOiI5ODAiLCJvcGVyVHlwZSI6IlJFQ1VSUkVOVCBTVUJTRVFVRU5UIiwiYWN0aW9uQ29kZSI6Ijk5OSJ9LHsidHJhbkNvZGUiOiI0MTAiLCJjb21tZW50IjoiVGhlIG9yZGVyIHdhcyBwYWlkIChwb3NzaWJsZSByZXBsYXkpIiwiY2FyZE51bU1hc2tlZCI6IjQ5OTk5OSoqKioqKjAwMTEiLCJ0cmFuVGltZSI6IjIwMTktMDgtMjIgMTU6NTM6NTYuNDE2IiwiYW1vdW50IjoxMDAsImN1cnJlbmN5IjoiOTgwIiwib3BlclR5cGUiOiJSRUNVUlJFTlQgU1VCU0VRVUVOVCIsImFjdGlvbkNvZGUiOiI5OTkifV19",
"signature": "q74IKELVfLpYmbd3CSovGsMLdzHdYudjpBljl240rp8K59PA2ymLR8SUae1zAY7qExFinAUMv_bhxnajwR0eOuZUqnt7CvhmehxFGsRVcmF5-wHGsgh-oT8Oe6ILPzfE9mwAHnGgzyP_krLgPrWUOWS-RLM9DDGHfkHYecwswak"
}

Base64 decoded

{

"results": [{

"tranCode": "000",

"approvalCode": "514297",

"rrn": "923415875204",

"comment": "Approved",

"cardNumMasked": "499999******0011",

"tranTime": "2019-08-22 15:15:20.702",

"amount": 100,

"currency": "980",

"operType": "RECURRENT SUBSEQUENT",

"actionCode": "000"

}]

}