MerchantAPI: відмінності між версіями

← Попереднє редагування Наступне редагування →

Версія за 11:33, 2 вересня 2024

Загальні відомості

Протокол призначено для торговців, які є одержувачами платежів. Продавець підписує договір про прийняття платежів або анкету-акцепт до публічної оферти.

Щоб отримати платежі, ви можете використовувати web, мобільні версії сайтів, а також мобільні програми. У разі використання цього протоколу не здійснюється перевірка даних для ідентифікації замовлення або облікового запису. EasyPay завжди приймає дані, надіслані та створені продавцем.

Запит заголовків

Надсилання запиту та відповіді у форматі JSON.

Обов'язкові параметри для визначення запиту від торговця (мерчанта):

--header 'Content-Type: application/json'

--header 'AppId: cd7fde18-15db-4d94-a91b-7cf8edd81209'

--header 'PageId: 3e7bf353-417a-410c-a22e-df8bdcccb760'

--header 'PartnerKey: easypay-test'

--header 'locale: ua'

--header 'Sign: bS+vPOwu1Sif1Iz47Cdh+z1RAi0s6X21C3uU0YNBNWE='

URLS

Production - https://merchantapi.easypay.ua

(в т.ч. для надсилання тестових запитів)

Реєстрація партнера

Реєстрація нового торговця - отримання PartnerKey:

Параметр	Характеристика	Коментарій
`PartnerKey`	унікальний ідентифікатор партнера (продавця) у системі EasyPay.
`ServiceKey`	ідентифікатор сервісу торговця у системі EasyPay.	магазину чи послуги
`SecretKey`	секретний ключ для формування підпису	відомий лише торговцю та EasyPay
`AppId`	ідентифікатор торгової точки партнера	параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)
`PageId`	ідентифікатор сесії	параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID

Параметри PartnerKey, SeviceKey, SecretKey передаються партнеру після реєстрації у системі EasyPay відповідальним менеджером.

Для тестових* запитів використовуються наступні параметри:

PartnerKey = easypay-test

ServiceKey = MERCHANT-TEST

SecretKey = test

ℹ️ На даний момент відсутня можливість тестування з використанням фейкових оплат / тестових карток. Платежі тільки реальні, їх можна відмінити в день оплати методом cancelOrder (п. 2.6).

💡 На даний момент відсутня можливість тестування з використанням фейкових оплат / тестових карток. Платежі тільки реальні, їх можна відмінити в день оплати методом cancelOrder (п. 2.6).

❗️ На даний момент відсутня можливість тестування з використанням фейкових оплат / тестових карток. Платежі тільки реальні, їх можна відмінити в день оплати методом cancelOrder (п. 2.6).

GET /api/system/createApp

POST /api/system/createApp

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

Реєстрація точки та створення сесії

POST /api/system/createApp

Цей метод слід викликати, коли користувач вперше звертається до платіжної сторінки. Якщо браузер або пристрій змінюються, метод знову з'являється

Request

Headers

'PartnerKey: partnerName' 
'locale: ua'

Body

Response

headers
body
{
  "logoPath": "https://cdn.easypay.ua/logo/",
  "hintImagesPath": "https://cdn.easypay.ua/hint_images/",
  "apiVersion": "1.0",
  "appId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1",
  "pageId": "f3f2b678-a3c4-45ba-a865-a136fe4a62bd",
  "error": null
}

Параметр	Характеристика	Коментарій
`AppId`	ідентифікатор торгової точки партнера	за замовчуванням, якщо не було активності за запитами, час життя AppId - 3 місяці. З кожним запитом життя AppId автоматично продовжується.
`PageId`	ідентифікатор сесії	параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID

❗️ У разі отримання помилки APPID_NOT_FOUND у відповідь на будь-який метод, необхідно повторити запит createApp до отримання точки ІД.

Створення сесії

Створює новий екземпляр сеансу для користувача , PageId.

POST /api/system/createPage

Request

Headers

'PartnerKey:  partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'

body

Response

headers
body
{
    "logoPath": "https://cdn.easypay.ua/logo/",
    "hintImagesPath": null,
    "apiVersion": "1.0",
    "appId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1",
    "pageId": "29bd7237-6b8d-4048-b028-6efc23d05988",
    "requestedSessionId": "fa3595d3-52de-4744-9fc6-ec2d3507d5a5",
    "error": null
}

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

Реєстрація точки та створення сесії

Цей метод слід викликати, коли користувач вперше звертається до платіжної сторінки. Якщо браузер або пристрій змінюються, метод знову з'являється.

QR MasterPass

Для мерчантів, які мають пряму інтеграцію з MasterPass

Опис:

Оплата з гаманця MasterPass із використанням QR-коду.

{
  "instrumentType": "QrMasterpass",
  "commission": 0.0,
  "amountMin": 1.00,
  "amountMax": 14999.00,
  "userPaymentInstruments": [
    {
      "instrumentId": 8499910,
      "instrumentType": "QrMasterpass",
      "instrumentValue": "00020101021252040000530398054034005802UA5909EasyPayUa6004Kiev64190002UK0109EasyPayUa80850017ua.mastercard.www010200020840703434032003434180702054456177041211109354874205020181500017ua.mastercard.www011720191111093548742020499996223030443590603391070410036304AF79",
      "alias": null,
      "commission": 0.0,
      "loyaltyCommission": null,
      "actionsKeys": null,
      "priorityIndex": 0,
      "additionalParams": {
        "OrderId": "4825209b-1caa-472e-b530-dc3e8efd541c"
      }
    }
  ]
}

Створення підпису

Формування підпису Sign (основний варіант для POST – запитів)

Sign = base64(sha256(secretKey+requestBody))

*requestBody - текст запиту у форматі json , ідентичний до EasyPay

Приклад на C#

Convert.ToBase64String(SHA256.Create().ComputeHash(Encoding.UTF8.GetBytes(data)))

Convert.ToBase64String(SHA256.Create().ComputeHash(Encoding.UTF8.GetBytes(data)))

Приклад на PHP

base64_encode(hash('sha256', ($secretKey.$requestbody), true))

base64_encode(hash('sha256', ($secretKey.$requestbody), true))

Протокол призначено для торговців, які є одержувачами платежів. Продавець підписує договір про прийняття платежів або анкету-акцепт до публічної оферти.

Щоб отримати платежі, ви можете використовувати web, мобільні версії сайтів, а також мобільні програми. У разі використання цього протоколу не здійснюється перевірка даних для ідентифікації замовлення або облікового запису. EasyPay завжди приймає дані, надіслані та створені продавцем.

</body>

Цей блок може використовуватися для спеціальних повідомлень або інформаційних нотаток.

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

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

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

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

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

- CreateApp (п. 2.1)

- CreatePage (п. 2.2)

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"
  }
}

Можливі варіанти інструментів оплати

Оплата VISA MasterCarD

"paymentInstrumentsTypes": [
       {
           "storedCards": [],
           "instrumentType": "Card",
           "commission": 2.00,
           "amountMin": 0.01,
           "amountMax": 14000.00,
           "userPaymentInstruments": [
               {
                   "instrumentId": 4211698,
                   "instrumentType": "Card",
                   "instrumentValue": null,
                   "alias": null,
                   "commission": 2.00,
                   "loyaltyCommission": null,
                   "actionsKeys": null,
                   "priorityIndex": 200,
                   "additionalParams": {}
               }
           ]
  ]
       },
       {
           "instrumentType": "RCard",
           "commission": 2.00,
           "amountMin": 0.01,
           "amountMax": 14000.00,
           "userPaymentInstruments": []
       },

Мобільні гроші КиївстарLifecellVodafone

 {
           "instrumentType": "KSMoney",
           "commission": 0.0,
           "amountMin": 0.01,
           "amountMax": 14000.00,
           "userPaymentInstruments": [
               {
                   "instrumentId": 4958975,
                   "instrumentType": "KSMoney",
                   "instrumentValue": null,
                   "alias": null,
                   "commission": 0.0,
                   "loyaltyCommission": null,
                   "actionsKeys": null,
                   "priorityIndex": 1,
                   "additionalParams": {}
               }
           ]
       },
       {
           "instrumentType": "LifeMoney",
           "commission": 0.03,
           "amountMin": 0.01,
           "amountMax": 6000.00,
           "userPaymentInstruments": [
               {
                   "instrumentId": 5098216,
                   "instrumentType": "LifeMoney",
                   "instrumentValue": null,
                   "alias": null,
                   "commission": 0.03,
                   "loyaltyCommission": null,
                   "actionsKeys": null,
                   "priorityIndex": 0,
                   "additionalParams": {}
               }
           ]

Картки лояльності Fishka

 ]
       },
       {
           "instrumentType": "FishkaB2B",
           "commission": 2.00,
           "amountMin": 0.01,
           "amountMax": 1000.00,
           "userPaymentInstruments": []
       },
       {
           "instrumentType": "FishkaB2C",
           "commission": 2.00,
           "amountMin": 0.01,
           "amountMax": 1000.00,
           "userPaymentInstruments": []
       },

Оплата ApplePay GPAY

 {
           "instrumentType": "ApplePay",
           "commission": 2.00,
           "amountMin": 0.01,
           "amountMax": 9999.00,
           "userPaymentInstruments": [
               {
                   "instrumentId": 10958126,
                   "instrumentType": "ApplePay",
                   "instrumentValue": null,
                   "alias": null,
                   "commission": 2.00,
                   "loyaltyCommission": null,
                   "actionsKeys": null,
                   "priorityIndex": 0,
                   "additionalParams": {}
               }
           ]
       },
       {
           "instrumentType": "GooglePay",
           "commission": 2.00,
           "amountMin": 0.01,
           "amountMax": 9999.00,
           "userPaymentInstruments": [
               {
                   "instrumentId": 10958137,
                   "instrumentType": "GooglePay",
                   "instrumentValue": null,
                   "alias": null,
                   "commission": 2.00,
                   "loyaltyCommission": null,
                   "actionsKeys": null,
                   "priorityIndex": 0,
                   "additionalParams": 
                    {
                       "PublicKey": "BKdzipvJvJzcbTMm3dO0LEh1AXFr8qfSiPjwrI7vv9F6hqhDJB1M="
                    }
               }
           ]
       }
   ]

@@ Рядок 133: / Рядок 133: @@
 </p>
 Цей метод слід викликати, коли користувач вперше звертається до платіжної сторінки. Якщо браузер або пристрій змінюються, метод знову з'являється
-'''Request''' <syntaxhighlight lang="json" line="1">
+'''Request''' <syntaxhighlight line="1">
-headers
+Headers
-  'PartnerKey: partnerName'
-  'locale: ua'
+'PartnerKey: partnerName'
+'locale: ua'
+Body
-body
 </syntaxhighlight>
-'''Response'''<syntaxhighlight lang="json">
+'''Response'''<syntaxhighlight lang="json" line="1">
 headers
 body
@@ Рядок 154: / Рядок 156: @@
    "error": null
 }
@@ Рядок 197: / Рядок 200: @@
 </p>'''Request'''<syntaxhighlight line="1">
 Headers
-'PartnerKey: partnerName'
+'PartnerKey:  partnerName'
 'locale: ua'
+'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
 body
 </syntaxhighlight>'''Response'''<syntaxhighlight lang="json" line="1">
@@ Рядок 212: / Рядок 218: @@
      "error": null
 }
 </syntaxhighlight>