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
Цей метод слід викликати, коли користувач вперше звертається до платіжної сторінки. Якщо браузер або пристрій змінюються, метод знову з'являється
RequestHeaders
'PartnerKey: partnerName'
'locale: ua'
Bodyheaders
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
RequestHeaders
'PartnerKey: partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
bodyheaders
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) | передається партнеру після реєстрації у системі EasyPay відповідальним менеджером. |
orderId |
унікальний ідентифікатор номера замовлення у системі партнера | магазину чи послуги
передається партнеру після реєстрації у системі EasyPay відповідальним менеджером. |
description |
опис замовлення (до 120 символів) | відомий лише торговцю та EasyPay
передається партнеру після реєстрації у системі EasyPay відповідальним менеджером. |
amount |
сума замовлення, роздільник - точка | параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів) |
paymentOperation |
тип платіжного процесу | Можливі значення:
|
userInfo/phone |
номер телефону (або ідентифікатор) клієнта | Номер телефону необхідний:
|
expire |
час життя замовлення | Після закінчення заданого часу замовлення сплатити неможливо. Час життя сторінки може відображатися на платіжній сторінці у вигляді таймера (за замовчуванням таймер вимкнено). Значення має бути більшим за поточний час на 6 хвилин. Значення за замовчуванням - 3 дні |
sOneTimePay |
включає можливість успішно оплатити замовлення лише 1 раз за конкретним forwardUrl | Значення:
True - за замовчуванням; False - оплатити замовлення по тому самому forwardUrl можна буде кілька разів; |
urls |
|
back - На фінальній сторінці EasyPay вгорі зліва з'явиться кнопка “Повернутись назад” з посиланням на вказану URL-адресу. Параметр не може бути порожнім і повинен відповідати формату URL.
faild - приклад get-параметрів, які приходять на url.failed та url.succes (те ж, але без errorCode):
|
Необов'язкові додаткові поля
additionalItems – необов'язкові додаткові параметри, наприклад:"additionalItems":{
"PayerEmail":"[email protected]",
"PayerPhone":"380930007603",
"Merchant.UrlNotify":"https://notify.url",
"Merchant.Param1":"CustomValue",
"CurrencyAmountLabel":"123.56$"
}, де
| Параметр | Характеристика | Коментарій |
|---|---|---|
PayerEmail |
мейл клієнта для оповіщення його у разі неоплаченого замовлення та для автоматичного заповнення поля “Надіслати квитанцію на email” на сторінці оплати. | Якщо параметр передається – він не може бути порожнім і має відповідати формату email. |
PayerPhone |
телефон клієнта, на який протягом 15-20 хв після виклику CreateOrder відправиться нагадування про неоплачене замовлення (смс або вайбер). | Якщо параметр передається, він не може бути порожнім і повинен відповідати формату телефону. |
Merchant.UrlNotify |
URL для надсилання нотифікації за успішним платежем (callback), див. п. 2.7. | Параметр не може бути порожнім і має відповідати формату URL. |
Merchant.Param1 |
індивідуальний параметр партнера Param1 узгоджується з EasyPay |
Reccurent - інформація для створення рекурентного платежу на основі поточного. Рекурентний платіж буде створений за розкладом, якщо основний платіж виконаний за допомогою інструментів card, Rcard, Vcard, LifeMoney.
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"
}
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
Оплата 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="
}
}
]
}
]
| Параметр | Характеристика | Коментарій | ||
|---|---|---|---|---|
additionalItems |
необов'язкові додаткові параметри, наприклад | "additionalItems":{
|
||
PayerEmail |
Емейл клієнта для оповіщення його у разі неоплаченого замовлення та для автоматичного заповнення поля “Надіслати квитанцію на email” на сторінці оплати | Якщо параметр передається – він не може бути порожнім і має відповідати формату email | ||
AppId |
ідентифікатор торгової точки партнера | параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів) | ||
AppId |
ідентифікатор торгової точки партнера | параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів) | тип платіжного процесу, можливі значення: | PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення.
Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"} Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в п. 2.7, про токенізацію - в п. 4.1.2) |