MerchantAPI: відмінності між версіями
Немає опису редагування |
Немає опису редагування |
||
Рядок 906: | Рядок 906: | ||
<span style="margin-left: 5px; font-weight: bold; font-size: 16px;">/api/merchant/createOrder</span> | <span style="margin-left: 5px; font-weight: bold; font-size: 16px;">/api/merchant/createOrder</span> | ||
</p> | </p> | ||
==== '''Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки''' ==== | |||
У випадку "actionType": "ConfirmCode", клієнту прийде код підтвердження, який потрібно передати до EasyPay | |||
Версія за 11:37, 13 вересня 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. | передається партнеру після реєстрації у системі 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'
Body
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
RequestHeaders
'PartnerKey: partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
body
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) | передається партнеру після реєстрації у системі 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
Оплата 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="
}
}
]
}
]