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"
}
| Параметр | Характеристика | Коментарій |
|---|---|---|
cronRule |
правило у cron-форматі, з якою періодичністю повторювати рекурентний платіж, наприклад 10 20 15 * * (кожного 15 числа місяця о 20:10). | Якщо ця властивість порожня, значить рекурентний платіж виконуватиметься на вимогу продавця. Плануйте перше виконання рекуренту щонайменше 20 хвилин від дати успішного платежу. |
dateExpire |
дата, після якої не проводити рекурентний платіж. | магазину чи послуги
передається партнеру після реєстрації у системі EasyPay відповідальним менеджером. |
dateRun |
дата першого запуску рекурентного платежу (опціонально). | Якщо не заданий, перший запуск розраховується за recurrent/cronRule |
properties |
додаткові параметри (опціонально) |
|
Splitting та BankingDetails
splitting – інформація щодо сплітування (розщеплення) платежу.
bankingDetails - передача банківських реквізитів для перерахування коштів у випадку, якщо банківські реквізити можуть змінюватися щодо різних платежів одного сервісу продавця. На стороні EasyPay має бути увімкнено режим “Отримувати реквізити із запиту”.},
"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
}
]
| Параметр | Характеристика | Коментарій |
|---|---|---|
splitting |
інформація щодо сплітування (розщеплення) платежу | Частина загальної суми з order/amount розподіляється відповідно до інформації в splitting/items/value, а залишок - йде на основні реквізити з bankingDetails (або bankingDetailsId).
На стороні EasyPay має бути увімкнено режим “Отримувати реквізити із запиту”. Структура items це масив. Основний платіж буде розщеплений стільки платежів, скільки міститься у цьому масиві плюс залишок. Кожен розщеплений платіж буде надіслано на відповідні банківські реквізити items/bankingDetails. Залишок коштів буде надіслано на реквізити основного платежу з BankingDetails або bankingDetailsId, які потрібно обов'язково вказувати під час сплітування. |
serviceKey |
необов'язковий параметр. Ідентифікатор послуги, за якою ініціюється зарахування спліту (частини) платежу. Якщо параметр відсутній, використовується значення ServiceKey з тіла запиту CreateOrder | |
orderId |
необов'язковий параметр. Ідентифікатор внутрішнього замовлення Мерчант для маркування конкретного спліту (частини) платежу. Якщо параметр відсутній, використовується значення OrderId, передане в тілі запиту CreateOrder | |
bankingDetails |
передача банківських реквізитів для перерахування коштів у випадку, якщо банківські реквізити можуть змінюватися щодо різних платежів одного сервісу продавця | На стороні EasyPay має бути увімкнено режим “Отримувати реквізити із запиту”. |
Payee/Id |
код одержувача (ЄДРПОУ або ІПН) | |
Payee/Name |
одержувач (до 38 символів) | |
Payee/Bank/Name |
банк отримувача (до 38 символів) | |
Payee/Bank/Mfo |
р/р одержувача або IBAN, | |
Payee/Bank/Account |
р/р одержувача або IBAN, | |
Payer/Name |
Платник | параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів) |
Narrative/Name |
Призначення платежу (до 157 символів) |
|
items/unit |
може бути Amount (сума розщепленого платежу в грн.)
або Percent (сума розщепленого платежу вважається відсотком від загального). |
параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів) |
items/value |
значення у цифрах | параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів) |
withCommission |
Вказує з якого з одержувачів слід утримати внутрішню комісію. | Сума комісії розраховується із загальної суми платежу, а утримується - з першого одержувача зі splitting, у якого withCommission=true. Якщо ні в кого з splitting не зазначено withCommission=true, то комісія втікає з “основного” одержувача, вказаного в bankingDetails.
Якщо у всіх значення withCommission=false (або не передали), то комісія утримається з "основного одержувача", вказаного в параметрі bankingDetails Якщо всі значення withCommission=true, то комісія утримається з першого одержувача, зазначеного в splitting. Залишок буде надіслано на реквізити основного платежу з bankingDetails або bankingDetailsId. При встановленому сервісом Типі розрахунків “За актами", одержувачам перераховується повна сума, без відрахування комісії, незалежно від значення WithComission. |
Після виконання сплітування під кожен спліт (частини) платежу на стороні EasyPay створюється фінансова транзакція з унікальним transactionID.
- Якщо списання грошей з картки пройшло успішно і всі реквізити для спліту вказані корректно (доступні) - всі транзакції набувають успішного статусу і по кожній транзакції відправляється колбек.
- Якщо списання грошей з картки пройшло неуспішно – запит відхиляється з кодом фінансової помилки;
- Якщо списання грошей з картки пройшло успішно, але хоча б один із реквізитів зазначено неправильно – всі
транзакції спліту (частини) платежу – будуть відхилені.
Після проведення успішного списання та сплітування по кожній фінансовій транзакції в рамках спліту направляється колбек (нотифікація) про успішний платіж. Приклад коллбека (нотифікації) вказаний у п.2.7 цієї документації.
userPaymentInstrument - інструмент оплати. Якщо параметр userPaymentInstrument не є порожнім, створення платежу буде відбуватися автоматично
},
"userPaymentInstrument": {
"instrumentType": "Card",
"cardGuid": "guid",
"pan": "string",
"expire": "MM/YY",
"cvv": "string",
},
"partnerInfo": {
"id": "string",
"name": "string",
"account": "string"
}
}
Для різних інструментів передаються такі параметри:
| № | Інструмент | Передані параметри |
|---|---|---|
| 1. | Картка (PCI DSS) | "userPaymentInstrument": {
|
| 2. | *Токенізована Карта | {"userInfo":{"phone":"380935207603"},
|
| 3. | MasterPass | {"userInfo":{"phone":"380935207603"},
|
| 4. | Kyivstar Money /
Life Money /VodafoneMoney |
"userPaymentInstrument": {
|
| 5. | *ApplePay /
GooglePay |
"userPaymentInstrument": {
|
Параметры BrowseInfo при 3DS оплаті
У зв'язку з переходом банків - екваєрів на модель роботи 3D Secure 2.x, при створенні замовлення з одночасною передачею інструменту оплати в запиті (карта, токен карти, токен Apple / Google Pay), необхідно передавати додаткові параметри пристрою (браузера) клієнта в заголовках і в тілі запиту createOrder, у прикладі вони виділені:
POST /api/merchant/createOrder
Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки
У випадку "actionType": "ConfirmCode", клієнту прийде код підтвердження, який потрібно передати до EasyPay
POST /api/payment/confirmCodeVerification
Requestheaders
'Content-Type: application/json'
'PartnerKey: partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='
body
{
"code": "string"
}
headers
body
{ }
Опис процесу перевірки 3DS
Якщо "status":"Need3Ds", клієнту потрібно пройти 3D Secure перевірку в залежності від значення "actionType":
- "FormRedirect" – Необхідно СТВОРИТИ сторінку (форму) з HTML-коду, що переданий у параметрі
"actionContent":"<html>...</html>". Цю сторінку потрібно відкрити для клієнта для проходження ним 3D Secure перевірки. Альтернативним варіантом є переадресація клієнта за посиланням з параметра"alternativeRedirectUrl". - "UrlRedirect" – Клієнта потрібно переадресувати на посилання з параметра
"action"або за посиланням з"alternativeRedirectUrl".
Відобразиться форма банку емітента картки для перевірки 3D Secure.
Після введення коду клієнт буде переадресований на сторінку успіху або помилки.
Адреси сторінок передаються на етапі створення замовлення:"urls": {
"success": "string",
"failed": "string"
}
Перевірка статусу платежу
POST /api/merchant/orderState
Requestheaders
'Content-Type: application/json'
'PartnerKey: partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='
body
{
"serviceKey":"MERCHANT-TEST",
"orderId":"test_20240524-0015",
"transactionId":"1413668587"
}
headers
body
"merchantKey":"easypay-test",
"transactionId":1413668587,
"orderId":"test_20240524-0015",
"amount":3.000000,
"paymentState":"declined",
"refundTransactionId":1413673292,
"":
"paymentsList":[
],
"refunds":[
{
"refundTransactionId":1413669380,
"paymentState":"accepted",
"refundAmount":1.10,
"dateAccepted":"2024-05-24T16:14:45+03:00",
"dateDeclined":null,
"datePost":"2024-05-24T16:14:39+03:00"
},
{
"refundTransactionId":1413673292,
"paymentState":"accepted",
"refundAmount":1.90,
"dateAccepted":"2024-05-24T16:19:40+03:00",
"dateDeclined":null,
"datePost":"2024-05-24T16:19:33+03:00"
}
],
"error":null
}
- запит повинен виконуватися за операціями, проведеними не пізніше ніж 90 днів тому.
- у запиті можна відправити як orderId, і transactionId, чи його комбінацію. Якщо у запиті надіслати тільки orderId, то за наявності кількох транзакцій із зазначеним orderId - повернеться статус останнього з них.
- refundTransactionId - номер транзакції повернення, якщо платіж із запиту було скасовано методом cancelOrder
- paymentState - Статус платежу. Можливі
paymentState:
| Фінальний статус? | Значення/ подальші дії | |
|---|---|---|
accepted |
так | платіж прийнято |
declined |
так | платіж відхилений |
pending |
ні | платіж знаходиться в обробці, необхідно повторити запит статусу пізніше |
none |
- | статус платежу не визначено, необхідно повторити запит статусу до отримання кінцевого статусу |
Нетипові відповіді запит статусу
Якщо платіж не знайдено, прийде відповідь:{
"error":{
"errorCode":"MERCHANT_ORDERID_NOT_FOUND",
"title":null,
"description":null,
"errorMessage":"MERCHANT_ORDERID_NOT_FOUND",
"fieldErrors":[ ]
}
{
"merchantKey": "easypay-test",
"transactionId": 0,
"orderId": "Some orderId2",
"amount": 0,
"paymentState": "pending",
"refundTransactionId": null,
"paymentsList": [],
"error": null
}
{
"merchantKey": "easypay-test",
"transactionId": 0,
"orderId": "Some orderId",
"amount": 0,
"paymentState": "declined",
"refundTransactionId": null,
"paymentsList": [],
"error": {
"errorCode": "PROVIDER_ACCOUNT_INVALID", (ерор код може (має) відрізнятися від того, що в прикладі)
"title": "Помилка системи",
"description": "Акаунт не знайдено",
"errorMessage": "string"
}
}
При виконанні запиту статусу на замовлення, у яких є спліт (платіжна опція) - повертається наступна модель:
Requestheaders
'Content-Type: application/json'
'PartnerKey: partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='
body
{
"serviceKey":"easypay-test",
"orderId":"full_split_11",
"transactionId":""
}
headers
body
{
"merchantKey": "easypay-test",
"transactionId": 991379504,
"orderId": "full_split_11",
"amount": 3.150000,
"paymentState": "accepted",
"refundTransactionId": null,
"paymentsList": [
{
"merchantKey": "easypay-test",
"transactionId": 991379509,
"orderId": "full_split_11",
"amount": 1.030000,
"paymentState": "accepted",
"refundTransactionId": null,
"date": "2021-09-15T14:07:38+03:00",
"error": null
},
{
"merchantKey": "easypay-test",
"transactionId": 991379508,
"orderId": "full_split_11",
"amount": 0.050000,
"paymentState": "accepted",
"refundTransactionId": null,
"date": "2021-09-15T14:07:38+03:00",
"error": null
},
{
"merchantKey": "easypay-test",
"transactionId": 991379507,
"orderId": "full_split_11",
"amount": 1.020000,
"paymentState": "accepted",
"refundTransactionId": null,
"date": "2021-09-15T14:07:38+03:00",
"error": null
},
{
"merchantKey": "easypay-test",
"transactionId": 991379506,
"orderId": "full_split_11ID",
"amount": 1.050000,
"paymentState": "accepted",
"refundTransactionId": null,
"date": "2021-09-15T14:07:38+03:00",
"error": null
}
],
"error": null
}
У випадку зі сплітованими платежами, в основному тілі відповіді OrderState - параметру transactionId присвоюється внутрішній технічний номер (нефінансової) операції.
Скасування платежу
Метод викликається лише для платежів у статусі "accepted". Для успішного скасування має бути достатньо суми прийнятих платежів у день скасування. Можна скасовувати платежі, які не старші 30 днів. Успішне повернення після цього терміну – не гарантується, залежить від умов банків-еквайєрів.
Повернення суми на картку відбувається в строк 0-3 робочих дні, в окремих випадках – до 30 робочих днів. Це залежить від умов банку-еквайєра, через який пройшов основний платіж, а також банку-емітента.
Скасування звичайного платежу
POST /api/merchant/cancelOrder
Requestheaders
'Content-Type: application/json'
'PartnerKey: partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='
body
{
"serviceKey": "MERCHANT-TEST",
"orderId": "test_20210217-121843",
"transactionId": 913141164,
"amount":1
}
headers
body
{
"merchantKey":"easypay-test",
"transactionId":913141164,
"refundTransactionId":913141464,
"orderId":"test_20210217-121843",
"amount":1.000000,
"paymentState":"accepted",
"error":null
}
| Параметр | Характеристика | Коментарій |
|---|---|---|
amount |
скасована сума | для часткового скасування - передається із сумою, яку потрібно скасувати.
для скасування повної суми - параметр amount не передається |
transactionId |
оригінальна транзакція | магазину чи послуги
передається партнеру після реєстрації у системі EasyPay відповідальним менеджером. |
refundTransactionId |
транзакція рефанду (скасування) | транзакція рефанду (скасування) |
paymentState |
статус транзакції рефанду (скасування). Можливі значення: | Можливі значення:
|
Якщо скасування пройшло успішно, запит статусу оригінальної транзакції повинен тепер повертати "paymentState":"declined", а запит статусу транзакції скасування - "paymentState": "accepted"
При успішному скасуванні платежу, якщо налаштована HTTP - нотифікація (див. п. 2.7), на Merchant.UrlNotify буде одноразово надіслано POST - запит із параметром "action": "refund" та сумою (amount), яка була скасована. Нотифікація надсилається одноразово без повторних спроб, статус у відповідь код нами не перевіряється.
Скасування платежу (замовлення зі Splitting параметрами)
Скасування платежу (Замовлення) можна робити:
- на всю суму платежу (замовлення)
- на суму одного спліту (Часткова скасування платежу (замовлення))
- на суму меншу від суми спліту (Часткова скасування спліту)
Скасування повної суми платежу (замовлення зі Splitting параметрами)
- Для скасування повної суми Splitting транзакції необхідно виконати запит статусу транзакції згідно з п.2.5, (Перевірка статусу платежу) використовуючи основний OrderID
- Отриманий у відповіді кореневий transactionID використовувати у запиті cancelOrder
- У відповідь на запит cancelOrder буде отримано відповідь зі статусом скасування, а також буде отримано коллбек по кожній транзакції, яка входила до Splitting транзакції.
- Коллбек на загальну суму Splitting транзакції не надходить.
POST /api/merchant/cancelOrder
Requestheaders
'Content-Type: application/json'
'PartnerKey: partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='
body
{
"serviceKey": "easypay-test",
"orderId": "full_split_11",
"transactionId": 991379504,
}
headers
body
{
"merchantKey":"easypay-test",
"transactionId": 991379504,
"refundTransactionId":913141464,
"orderId":"full_split_11",
"amount":1.000000,
"paymentState":"accepted",
"error":null
}
| Параметр | Характеристика | Коментарій |
|---|---|---|
transactionId |
номер транзакції, що скасовується, приходить при отриманні коллбека за оплаченим замовленням (параметр payment_id) | |
amount |
сума, що скасовується:
для часткового скасування - передається із сумою, яку потрібно скасувати. |
|
transactionId |
оригінальна транзакція, яка була відправлена у запиті cancelOrder | |
refundTransactionId |
транзакція рефанду (скасування) | |
amount |
сума, яка була скасована | |
paymentState |
статус транзакції рефанду (скасування) | Можливі значення:
|
Повідомлення про платіж
Партнер обов'язково вибирає 1 або кілька способів сповіщення та повідомляє його в EasyPay. Партнер зазначає платіж успішним на своїй стороні лише після отримання цього повідомлення
Ми надсилаємо HTTP - колек з IP 93.183.196.26 методом POST з інформацією про платіж.
Запит надсилає EasyPay партнеру після того, як транзакція набула фінального статусу (Accepted, Declined).
URL для повідомлень (UrlNotify) партнер направляє у запиті createOrder у параметрі:
"order":{
"additionalItems":{
"Merchant.UrlNotify":"https://notify.url"
}
}
"Merchant.UrlNotify" Параметр не може бути порожнім і має відповідати формату URL.
❗️ Важливо: якщо у відповіді не отримано HTTP StatusCode 200, запит нотифі буде надіслано повторно протягом 1-10 хвилин. І може продовжуватися визначену кількість разів (по замовчанню - 50), поки не отримано статусу “200 ОК”
headers
'Sign: Bq2d0oaqVGMRWpX5wsGpOlpqLg42pBdDO7TfTPYVmnU='
body
{
"OperationType": "Payment",
"PartnerKey": "groshi-com",
"ServiceKey": "GROSHI-COM-GOOGLEPAY",
"TransactionStatus": "Accepted",
"MerchantOrderId": "3127194_28_450866",
"DateTime": "2023-12-09T14:00:48",
"Amount": 2059.08,
"Commission": 28.83,
"TransactionId": 1336448544,
"AdditionalItems": {
"Merchant.Inn": "3178404189",
"Merchant.Details": ";0;0;;4;",
"Merchant.UrlNotify": "https://testpartner.ua/callback",
"Merchant.ClientFullName": "Іванов Дмитро"
"Acquirer.MerchantId":"12345678"
"Acquirer.TerminalId":"E1234567"
"Card.BrandType":"Visa"
"AuthCode":"012345"
}
}
| Параметр | Характеристика | Коментарій |
|---|---|---|
OperationType |
тип оповіщення | Можливі значення:
payment - про успішний платіж (повторюється, якщо у відповідь не отримано статусу 200) refund - про успішне скасування платежу (відправляється разово) |
PartnerKey |
ІД партнера у системі EasyPay | |
ServiceKey |
ІД сервісу партнера у системі EasyPay | |
TransactionStatus |
статус платежу | |
MerchantOrderId |
номер замовлення партнера із запиту createOrder | |
Acquirer.MerchantId |
ідентифікатор торговця | |
Acquirer.TerminalId |
ідентифікатор платіжного пристрою | |
Card.BrandType |
найменування платіжної системи, платіжний інструмент якої використовується | |
AuthCode |
Код авторизації |
Оплата 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="
}
}
]
}
]