MerchantAPI

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

---

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

Щоб отримати платежі, ви можете використовувати 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.	передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
ServiceKey	ідентифікатор сервісу торговця у системі EasyPay.	магазину чи послуги передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
SecretKey	секретний ключ для формування підпису	відомий лише торговцю та EasyPay передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
AppId	ідентифікатор торгової точки партнера	параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)
PageId	ідентифікатор сесії	параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID

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

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

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

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

---

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

---

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
}

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

Створення замовлення

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

POST /api/system/createPage

POST /api/system/CreateApp

❗️ Важливо! Для кожного нового запиту CreateOrder потрібно використовувати унікальний PageID.

POST /api/merchant/createOrder

headers
'Content-Type: application/json'
'PartnerKey: partnerName' 
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='
{
   "userInfo": {
       "phone": "string"
    },
    "order": {
       "serviceKey": "string",
       "orderId": "string",
       "description": "string",
       "amount":1.01, (decimal)
       "paymentOperation":"PaymentTokenization",
       "additionalItems": {},
       "expire": "2019-04-15T07:49:20",
       "isOneTimePay": true,
       "fields": [
          {
           "fieldName": "string",
           "fieldValue": "string",
           "fieldKey": "string",
          }
        ]
     },
  "urls": {
    "success": "string",
    "failed": "string",
    "back": "string",
  },
  "bankingDetailsId": "string",
"bankingDetails": {
    "payee": {
      "id": "string",
      "name": "string",
      "bank": {
        "name": "string",
        "mfo": "string",
        "account": "string"
      }
    },
    "payer": {
      "name": "string",
      "id": "string"
    },
    "narrative": {
      "name": "string"
    }
  },

  "reccurent": {
    "cronRule": "string",
    "dateExpire": "2019-01-21T08:24:38.741Z",
    "dateRun": "2019-01-20T08:24:38.741Z",
    "properties":
       {
         "failedCount":0,
         "failedRule":"string",
         "amount":1.0,
         "UrlNotify":"http://notify.url"
       }
  },
 "splitting": {
    "items": [
      {
     "serviceKey": "string",
     "orderId": "string”  
     "bankingDetailsId": "string",
     "bankingDetails": {
                      "payee": {
                                     "id": "string",
                                     "name": "string",
                                      "bank": {
                                                    "name": "string",
                                                     "mfo": "string",
                                                     "account": "string"
                                                  }
                                     },
                       "payer": {
                                      "name": "string"
                                     },
                       "narrative": {
                                      "name": "string"
                                     }
                                   },
        "unit": "Amount|Percent",
        "value": 0,
        "withCommission": false|true
      }
    ]
  },
  "userPaymentInstrument": {
      "instrumentType": "Card",
      "cardGuid": "guid",
  "pan": "string",
      "expire": "MM/YY",
      "cvv": "string",
  },
 "partnerInfo": {
      "id": "string",
      "name": "string",
      "account": "string"
}
}

Параметр	Характеристика	Коментарій
serviceKey	ідентифікатор послуги мерчанта (видає EasyPay);	.
orderId	ідентифікатор сервісу торговця у системі EasyPay.
description	секретний ключ для формування підпису	опис замовлення (до 120 символів)
amount	сума замовлення, роздільник - точка;
paymentOperation	тип платіжного процесу, можливі значення:	PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення. Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"} Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в п. 2.7, про токенізацію - в п. 4.1.2)

serviceKey	ідентифікатор послуги мерчанта (видає EasyPay);	.
orderId	ідентифікатор сервісу торговця у системі EasyPay.
description	секретний ключ для формування підпису	опис замовлення (до 120 символів)
amount	сума замовлення, роздільник - точка;
paymentOperation	тип платіжного процесу, можливі значення:	PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення. Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"} Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в п. 2.7, про токенізацію - в п. 4.1.2)

Параметр	Характеристика	Коментарій
userInfo/phone	номер телефону (або ідентифікатор) клієнта, необхідний:	для отримання списку карток MasterPass гаманця для отримання списку токенізованих карток (інформація буде в масиві StoredCards) при оплаті із зазначенням токена картки для токенізації картки після успішної оплати разом із параметром "paymentOperation":"PaymentTokenization"
expire	час життя замовлення. Після закінчення заданого часу замовлення сплатити неможливо. Час життя сторінки може відображатися на платіжній сторінці у вигляді таймера (за замовчуванням таймер вимкнено). Значення має бути більшим за поточний час на 6 хвилин. Значення за замовчуванням - 3 дні
sOneTimePay	включає можливість успішно оплатити замовлення лише 1 раз за конкретним forwardUrl. Значення за замовчуванням - True. При False - оплатити замовлення по тому самому forwardUrl можна буде кілька разів.
urls	back - URL для повернення на вказану сторінку з фінальної сторінки успіху EasyPay (у разі, якщо не було передано urls{success,failed} для редиректу після оплати). На фінальній сторінці EasyPay вгорі зліва з'явиться кнопка “Повернутись назад” з посиланням на вказану URL-адресу. Параметр не може бути порожнім і повинен відповідати формату URL. success - URL сторінки успіху, для редиректу клієнта у разі успішної оплати (після оплати клієнт може не дочекатися редиректу на цей url, тому редирект не можна використовувати як індикатор успішної оплати, отримання оповіщення про успішний платіж - див. п. 2.7) failed - URL сторінки помилки для редиректу клієнта у разі неуспішної оплати	приклад get-параметрів, які приходять на url.failed та url.succes (те ж, але без errorCode): ?serviceKey=merchanttest-5310&orderId=re9r9er94jr&amount=1.20&description=Тестове+описання+замовлення&transactionId=722443797&date=2019-06-11T14:49:07&recurrentId=&errorCode=PAYMENT_ALFABANK_-2006&sign=eYkFYixpB3wnKoZDzkAiqWgdMkeHETDWmDsFMCaPO44=
additionalItems	ідентифікатор сесії	необов'язкові додаткові параметри, наприклад:

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

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

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

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))

<body style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 16px; line-height: 1.5; color: #333; margin: 20px;">

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

Щоб отримати платежі, ви можете використовувати 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="
                    }
               }
           ]
       }
   ]