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

Merchant API

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

• Загальні_відомості
• Заголовки запитів
  • URL
  • Налаштування безпеки
  • Реєстрація партнера в системі
  • Тестові параметри
• Основні запити та відповіді
• Реєстрація точки та створення сесії
• Створення замовлення
  • Створення замовлення для холдованих платежів
• Розхолдування платежу
• Параметри BrowseInfo при 3DS оплаті
• Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки
• Перевірка статусу платежу
• Скасування платежу
  • Скасування звичайного платежу
  • Скасування повної суми платежу (замовлення зі Splitting параметрами)
  • Приклади запитів
  • Часткове скасування (повернення) платежу (замовлення зі Splitting параметрами)
• Повідомлення про платіж
  • Отримання інформації про рекурентний платіж
  • Виклик рекурентного платежу
  • Видалення рекурентного платежу
• Робота з токенізованими картами

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

• Токенізація за допомогою введення даних картки користувачем на сторінці
• Отримання списку токенізованих карт
• Видалення токенізованих карт
• Видача кредиту (переказ на картку користувача)
• Нотифікації (колбеки) щодо операцій поповнення карток
• Інтеграція з ApplePay та GooglePay
  • Інтеграція з ApplePay
  • Інтеграція з GooglePay
• Створення підпису
• Можливі варіанти інструментів оплати
• SDK
  • IOS-SDK
  • Android-SDK
  • Flutter-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

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

• CreateAPP
• CreatePage

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