Робота з токенізованими картами

Merchant API

Головна сторінка

(Токенізація з передачею даних картки у запиті

Токенізація за допомогою введення даних картки користувачем на сторінці
Отримання списку токенізованих карт
Видалення токенізованих карт
Видача кредиту (переказ на картку користувача)
Нотифікації (колбеки) щодо операцій поповнення карток
Інтеграція з ApplePay та GooglePay
- Інтеграція з ApplePay
- Інтеграція з GooglePay
Створення підпису
Можливі варіанти інструментів оплати
SDK

Токенізація карти

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

Токенізація з передачею даних картки у запиті (заборонено без PCI:DSS сертифікації мерчанта)

Перед викликом цього методу. Потрібно викликати один із методів:

- CreateApp

- CreatePage

POST /api/merchant/tokenCard

Request

headers

"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "phone": "380501002030ws",
  "pan": "4874120123567889",
  "expire": "1222",
  "cvv": "012",
  "vсode": "123654"
}

Response

headers
відсутній

body
{
  "activateCodeType": "code|amount",
  "cardGuid: "55F5118B-B695-43BA-8555-AF8B698C4D2C",
  "pan”: "48741201****1234",
  "expire”: "1222" 
  "error": "null"
}

Токенізація картки - процес двоетапний.

На першому етапі у запиті йдуть параметри картки та номер телефону користувача. У відповіді, залежно від activateCodeType, може бути активація за кодом підтвердження з виписки або SMS або за сумою списання.

З другого краю етапі до всіх параметрів додається ще vcode – код верифікації. При успішному відповіді прийдуть параметри токенізованої карти чи помилка.

Токенізація за допомогою введення даних картки користувачем на сторінці (сертифікація PCI:DSS не потрібна)

Перед викликом цього методу, потрібно викликати один із методів:

- CreateApp;

- CreatePage;

POST api/merchant/tokenCard/create

Request

headers 
"Content-Type: application/json"
"PartnerKey: partnerName"
"locale: ua"
"AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "phone": "8888",
  "expire": "2020-12-06T12:54:32.043Z",
  "urls": {
    "success": "https://test.ua",
    "failed": "https://test1.ua",
    "notify": "https://test2.ua",
    "back": "https://test3.ua"
  },
  "description": "testtts",
  "checkExistingToken": false
  "operationType":"SingleToken | createToken | ExistingToken"
}

Response

headers

body
{
"forwardUrl": "https://easypay.ua/ua/tokencard/cae16afc-be56-4a39-8ce1-5de4f4142e76",
"error": null
}

Параметр	Характеристика	Коментарій
`description`	опис, який відобразиться на сторінці токенізації
`expire`	час життя сторінки токенізації (по дефолту - 15 хвилин)
`phone`	ідентифікатор клієнта, під яким збережеться картка (будь-які літери, цифри, GUID.	Не повинен містити символ ‘+’
`urls`	містить інформацію про: сторінці успіху партнера (success) для переадресації клієнта після успішної токенізації, потрібно обов'язково передавати сторінці помилки (failed) для переадресації клієнта у разі помилки адреса для відправки callback-запиту з деталями при успішній токенізації (notify) адресу для повернення назад зі сторінки токенізації (back)
`forwardUrl`	сторінка для додавання картки (токенізації)
`checkExistingToken`	перевірка наявності токена по карті, що вводиться у даного партнера.	Параметр може набувати значення: true - проводити валідацію на наявність раніше створеного токена по цій карті; false - валідація відсутня; null - валідація відсутня; Якщо параметру checkExistingToken присвоєно значення true, слід очікувати наступних сценаріїв поведінки: “checkExistingToken” : true, і в системі немає раніше створених токенів під зазначену карту під даним партнером (partnerKey) - формується запит на верифікацію введених даних картки (надсилання коду верифікації). За результатом успішної верифікації – створюється токен. При неуспішній верифікації – токен не створюється. У callback пишуться дані щодо створеного токену; “checkExistingToken” : true, і в системі є раніше створені токени під зазначену карту під даним партнером (partnerKey) - користувачу відкривається сторінка успіху, додаткова верифікація (надсилання коду верифікації не відбувається), токен не створюється, а в callback вказується масив раніше створених токенів; “checkExistingToken” : false / null, і в системі немає раніше створених токенів під зазначену карту під даним партнером (partnerKey) - формується запит на верифікацію введених даних картки (надсилання коду верифікації). За результатом успішної верифікації – створюється токен. При неуспішній верифікації – токен не створюється. У callback пишуться дані щодо створеного токену; “checkExistingToken” : false / null, і в системі є раніше створені токени під зазначену карту під даним партнером (partnerKey) – формується запит на верифікацію введених даних картки (надсилання коду верифікації). За результатом успішної верифікації – створюється токен. При неуспішній верифікації – токен не створюється. У callback пишуться дані щодо створеного токену.
`operationType`	(Новий параметр) задає тип операції токенізації	SingleToken - для однієї карти завжди повертається той самий токен. Логіка така: перевіряємо чи є токен для цієї картки під partnerKey із запиту якщо є 1 або більше токенів - беремо останній з них, створюємо новий запис з цим токеном для переданого ідентифікатора клієнта (phone), відправляємо цей токен в callback у кореневому параметрі cardGuid якщо токенів немає - створюємо новий для цього phone і відправляємо його в callback в кореневому параметрі cardGuid (один і той же cardGuid може бути прив'язаний до різних phone) createToken - значення за замовчуванням, звичайне створення токена (можна не передавати) ExistingToken - поведінка аналогічна checkExistingToken:true

На сторінці токенізації можемо керувати інтерфейсом (на стороні EasyPay):

відображати/сховати логотип EasyPay
відображати/приховати логотип та назву партнера
відображати/приховати опис з деталями токенізації
відображати опис у згорнутому/розгорнутому вигляді

Приклад callback - запит з IP адреси 93.183.196.26 після успішної токенізації:

Request

headers

Sign : AStbusXxzYdr48vssdr4/VXZCITrad8vr1A/tWhCBP8=

body
{ 
   "partnerKey":"partnerName",
   "phone":"test989",
   "cardGuid":"2ad57b2e-eb5b-4a99-ad05-788cf589b8af",
   "pan":"44411122****3558",
   "expire":"0524",
   "datePost":"2021-02-24T17:32:07.447",
   "codeType":"Mpi3Ds"
}

Параметр	Характеристика
`phone`	ідентифікатор клієнта, під яким збережено картку
`cardGuid`	токен збереженої карти
`pan`	маскований номер картки
`expire`	термін дії карти
`datePost`	час додавання картки
`codeType`	ознака типу верифікації картки. Mpi3Ds – з використанням 3ds.

Приклад callback - запит з IP адреси 93.183.196.26 з параметром ExistingToken:

Request

headers
Sign : AStbusXxzYdr48vssdr4/VXZCITrad8vr1A/tWhCBP8=

body
{
   "partnerKey":"easypay-test",
   "phone":"380509899549",
   "cardGuid":null,
   "pan":"44411122****3558",
   "expire":"0524",
   "datePost":"2021-05-18T18:41:53.152",
   "codeType":"Code",
   "existingTokens":[
      {
         "partnerKey":"easypay-test",
         "phone":"380509899549",
         "cardGuid":"bac4f855-xxxx-xxxx-bece-14cdf23c6c52",
         "pan":"44411122****3558",
         "expire":"0524",
         "datePost":"2021-05-18T18:28:23.840",
         "codeType":"Mpi3Ds"
      },
      {
         "partnerKey":"easypay-test",
         "phone":"380509899549",
         "cardGuid":"6338e8b4-xxxx-xxxx-a3e5-f46ad0cb0efa",
         "pan":"44411123****3558",
         "expire":"0524",
         "datePost":"2021-05-18T18:34:25.733",
         "codeType":"Mpi3Ds"
  },
      {
         "partnerKey":"easypay-test",
         "phone":"380509899549",
         "cardGuid":"18e3c35e-xxxx-xxxx-ba59-9506154394c0",
         "pan":"44411123****3558",
         "expire":"0524",
         "datePost":"2021-05-18T18:39:42.010",
         "codeType":"Mpi3Ds"
      }
   ]
}

Параметр	Характеристика
`existingTokens`	масив з даними раніше створених токенів по цій карті під даного партнера (partnerKey)

Отримання списку токенізованих карт

Метод призначений для отримання списку токенізованих карток за номером телефону (ознакою) користувача.

GET /api/merchant/tokenCards/get

Request

headers 

'PartnerKey: partnerName' 
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'TimeStamp: 1554360173'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='

queryparams
phone = string 
cardGuid= Guid

Response

headers 
відсутній

body
{
  "tokenCards": [
  {
     "cardGuid": "55F5118B-B695-43BA-8555-AF8B698C4D2C",
     "pan": "48741234****1234",
     "expire”: "1222"
   }],
  "error": "null"
}

Якщо передати тільки ідентифікатор клієнта (параметр phone) - у відповіді будуть всі карти поточного клієнта. Якщо передати phone та cardGuid - у відповіді буде одна карта поточного клієнта.

Видалення токенізованих карт

Метод призначений для видалення токенізованих карток за номером телефону. Якщо у клієнта під одним номером кілька карток, всі картки будуть видалені.

DELETE /api/merchant/tokenCards/delete/phone

DELETE /api/merchant/tokenCards/delete/phone?CardGuid=Guid

Request

headers

'PartnerKey: partnerName' 
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'TimeStamp: 1554360173'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='

queryparams

cardGuid= Guid

Response

headers 
відсутній 

body 
відсутній

Видача кредиту (переказ на картку користувача)

Метод призначений для переказу на картку користувача суми кредиту.

POST /api/merchant/createOrder

Перед викликом цього методу потрібно викликати один із методів:

Request:

headers

"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
   "order":{
  	"serviceKey":"CARD-FILL",
  	"description":"test top up card",
  	"amount":1.12, (decimal)
  	"orderId":"test",
  	"fields":[
     	{
        	"fieldName":"Pan",
        	"fieldValue":"4102321200001111",
        	"fieldKey":"b95d541a-c11f-49bc-9042-295dbf74ccn6"
     	},
     	{
        	"fieldName":"Phone",
        	"fieldValue":"38093520000"
     	}
  	],
     	"additionalItems": {
	      "Merchant.ClientFullName": "Иванов Петр Сергеевич",
                     "Merchant.Address": "04080, Київ, вул.Межигірська 82а корп.Б, кв.32",
                    "Merchant.Inn": "3334445823"
        }
   },
   "userPaymentInstrument":{
  	"instrumentType":"Vcash"
   }
}

Response

headers
відсутній 

body 
{
	"redirectUrl": null,
	"action": null,
	"paymentState": "Confirmed",
	"status": "Done",
	"actionType": "UrlRedirect",
	"transactionId": "766934634",
	"retrievalReferenceNo": "null",
	"responseItems": "null",
	"error": "null"
}

Опис параметрів

Параметр Характеристика Коментарій

paymentState

Confirmed оплата пройшла успішно
WaitConfirm очікується підтвердження платежу
Rejected і Refunded платіж відхинело

transactionId

ідентифікатор платежу в системі Easypay

У об'єкти поля передається інформація для поповнення карти. Номер картки можна вказувати:

для випадку з PCI DSS сертифікацією: у відкритому вигляді

"fieldName":"Pan",

"fieldValue":"4102321200001111",

для випадку без PCI DSS сертифікації: у вигляді токена (як отримати токен картки - див. Токенізація карти):

"fieldName":"Pan",

"fieldKey":"b95d541a-c11f-49bc-9042-295dbf74ccn6"

Також потрібно вказати:

- номер телефону клієнта:

"fieldName":"Phone",

"fieldValue":"38093520000"

- ПІБ та адреса клієнта АБО ПІБ та ІПН клієнта:

"additionalItems": {

"Merchant.ClientFullName": "Іванов Петро Сергійович"

"Merchant.Address": "04080, Київ, вул.Межигірська 82а корп.Б, кв.32"

"Merchant.Inn": "3334445862"

}

Статус видачі кредиту:

Якщо у відповіді отримано кінцевий статус (paymentState = Confirmed / Rejected / Refunded) - необхідно присвоїти його платежу.
Якщо кінцевий статус у відповіді не отримано (paymentState = WaitConfirm), у тому числі при серверних, мережевих та будь-яких інших відповідях та помилках - необхідно запросити статус платежу методом orderState (Перевірка статусу платежу) до отримання кінцевого статусу.

Важливо врахувати, що нотифікація про оплату не надсилається (якщо партнер/мерчант не повідомив про необхідність такого налаштування).

Скасування транзакції не передбачено.

Response (Приклади відповідей при помилках: status code = 400)

{
    "error": {
        "errorCode": "MERCHANT_CREATEORDER_VALIDATION_EXCEPTION",
        "title": null,
        "description": null,
        "errorMessage": "MERCHANT_CREATEORDER_VALIDATION_EXCEPTION",
        "fieldErrors": [
            {
                "fieldName": "Order.Fields[0]",
                "errorCode": "SERVICE_FIELDS_VALIDATION_EXCEPTION",
                "errorMessage": "Вказана умова не була виконана для значення поля."
            }
        ]
    }
}


{
    "error": {
        "errorCode": "PAYMENT_ALFABANK_CASH2CARD_C2Pv2",
        "title": "Платіжна помилка",
        "description": "Платіжна помилка",
        "errorMessage": "Обслуговуються тільки карти емітовані українськими банками",
        "fieldErrors": []
    }
}


{
    "error": {
        "errorCode": "PAYMENT_ALFABANK_CASH2CARD_C2Pa8",
        "title": "Платіжна помилка",
        "description": "Платіжна помилка",
        "errorMessage": "Необхідно уточнити реквізити картки одержувача у банку емітента",
        "fieldErrors": []
    }
}

Нотифікації (колбеки) щодо операцій поповнення карток

Дані колбеки є опціональним (додатковим) способом отримання інформації від EasyPay про результат виконання запиту на поповнення картки.

Для активації отримання колбеків мерчант (партнер) повинен повідомити EasyPay про таку необхідність, після чого EasyPay включає цю опцію.

Спосіб відправки колбека - HTTP - з IP 93.183.196.26 буде надіслано POST запит з інформацією про платіж на вказаний urlNotify.

urlNotify прописується на стороні EasyPay і використовується за замовчуванням, якщо партнер не передав його у своєму запиті.

URL для повідомлень (UrlNotify) повідомляє партнер (мерчант).

Партнер може передавати UrlNotify у запиті createOrder у параметрі:

"order":{

"additionalItems":{

"Merchant.UrlNotify":"https://notify.url"

}

"Merchant.UrlNotify" параметр не може бути порожнім і повинен відповідати формату URL.

Якщо у відповідь не отримано HTTP StatusCode 200 - запит нотифі буде надіслано повторно, доки не отримано статусу “200 ОК”.

Коли нотифікацію (колбек) успішно доставлено (отримано статус 200 ОК), повторне відправлення колбеків припиняється.

Відправлення колбеків можливе за двома сценаріями:

1) лише за успішними операціями (транзакціями);

2) за операціями (транзакціями) у фінальному статусі (успішні та відхилені).

Надання фінального статусу операції (транзакції) асинхронно з процесом відправки колбека (фінансова транзакція набуває фінального статусу незалежно від статусу прийняття колбека партнером).

Request

headers 

"Sign: "Bq2d0oaqVGMRWpX5wsGpOlpqLg42pBdDO7TfTPYVmnU="
"User-Agent": "EasyPay.MerchantNotifyService"

body

{
  "action": "payment",
  "merchant_id": 5347,
  "order_id": "5",
  "date": "2019-06-19T15:38:10.7802613+03:00",
  "details": {
    "amount": 1.00,
    "desc": "Wooden tables x 10",
    "payment_id": 724502946,
    "recurrent_id": null
  },
  "additionalitems": {
    "BankName": "CB PRIVATBANK",
    "Card.Pan": "414962******1234",
  }
}

Опис параметрів

Параметр	Характеристика	Коментарій
`action`	тип оповіщення	payment - про успішний платіж (повторюється, якщо у відповідь не отримано статусу 200)
`merchant_id`	номер сервісу партнера на стороні EasyPay;
`order_id`	номер замовлення партнера із запиту createOrder;
`date`	час надання платежу статусу на стороні EasyPay;	необов'язковий параметр (потрібно вказати, якщо потрібно замінити картку Одержувача)
`details`	детальна інформація про платіжну операцію (транзакцію)	payment_id - ID детальна інформація про платіжну операцію (транзакцію): amount - сума фінансової операції; desc - опис замовлення, отриманий під час запиту CreateOrder; recurrent_id - ознака реккурентного платежу (завжди за замовчуванням на операціях поповнення картки – null);
`additionalitems`	блок додаткових параметрів, до якого можуть включатися додаткові айтеми, отримані в запиті CreateOrder:	BankName - назва банку власника картки; Card.Pan - номер картки у маскованому вигляді.

Необхідно перевіряти підпис у нашому HTTP notify, налаштувати прийом лише для наших IP 93.183.196.26.

⚠️ Важливо! У випадку, якщо підпис notify не перевірено, всі фінансові ризики перекладаються на партнера.

← Назад
Основні запити та відповіді

Далі → Інтеграція з ApplePay та GooglePay