Створення замовлення
Зміст
Merchant API
Головна сторінка- Загальні_відомості
- Заголовки запитів
- Основні запити та відповіді
- Реєстрація точки та створення сесії
- Створення замовлення
- Розхолдування платежу
- Параметри BrowseInfo при 3DS оплаті
- Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки
- Перевірка статусу платежу
- Скасування платежу
- Повідомлення про платіж
- Робота з токенізованими картами
(Токенізація з передачею даних картки у запиті
- Токенізація за допомогою введення даних картки користувачем на сторінці
- Отримання списку токенізованих карт
- Видалення токенізованих карт
- Видача кредиту (переказ на картку користувача)
- Нотифікації (колбеки) щодо операцій поповнення карток
- Інтеграція з ApplePay та GooglePay
- Створення підпису
- Можливі варіанти інструментів оплати
- SDK
Створення замовлення
Перед викликом цього методу потрібно викликати один із методів:
⚠️ Важливо! Для кожного нового запиту 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='
<br>
{
"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 | Значення:
|
urls |
|
|
Необов'язкові додаткові поля
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), див. Повідомлення про платіж. | Параметр не може бути порожнім і має відповідати формату URL. |
Merchant.Param1 |
індивідуальний параметр партнера Param1 узгоджується з EasyPay |
reccurentPayment - інформація для створення рекурентного платежу на основі поточного. Рекурентний платіж буде створений за розкладом, якщо основний платіж виконаний за допомогою інструментів 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 |
додаткові параметри (опціонально) |
|
bankingDetails - передача банківських реквізитів для перерахування коштів у випадку, якщо банківські реквізити можуть змінюватися щодо різних платежів одного сервісу продавця. На стороні EasyPay має бути увімкнено режим "Отримувати реквізити із запиту".
{
"bankingDetails": {
"payee": {
"id": "123664578",
"name": "департамент патрульної поліції",
"bank": {
"name": "пат пумб",
"mfo": "330556",
"account": "123654778889"
}
},
"payer": { "name": "Иванова Мария" },
"narrative": { "name": "Переказ коштів згідно договору з ФК № 111/11-П від 11.11.1111 р. за виключенням винагороди за їх переказ згідно реєстру від [work_date]р." }
}
}
Опис параметрів
| Параметр | Характеристика | Коментарій |
|---|---|---|
payee/ID |
код одержувача | ЄДРПОУ або ІПН |
payee/Name |
одержувач | до 38 символів |
Payee/Bank/Name |
банк отримувача | до 38 символів |
Payee/Bank/Mfo |
МФО банку | може не заповнюватися, якщо Payee/Bank/Account містить IBAN |
Payee/Bank/Account |
р/р одержувача або IBAN | |
Payer/Name |
платник | |
Narrative/Name |
призначення платежу | до 157 символів |
bankingDetailsId |
повну структуру bankingDetails можна не передавати, для цього достатньо передати | |
bankingDetailsId |
|
|
Splitting - інформація щодо сплітування (розщеплення) платежу.
Частина загальної суми з order/amount розподіляється відповідно до інформації в splitting/items/value, а залишок - йде на основні реквізити з bankingDetails (або bankingDetailsId). На стороні EasyPay має бути увімкнено режим “Отримувати реквізити із запиту
Структура items це масив. Основний платіж буде розщеплений стільки платежів, скільки міститься у цьому масиві плюс залишок. Кожен розщеплений платіж буде надіслано на відповідні банківські реквізити items/bankingDetails. Залишок коштів буде надіслано на реквізити основного платежу з BankingDetails або bankingDetailsId, які потрібно обов'язково вказувати під час сплітування.
},
"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
| Параметр | Характеристика | Коментарій |
|---|---|---|
items/serviceKey |
необов'язковий параметр. Ідентифікатор послуги, за якою ініціюється зарахування спліту (частини) платежу. | Якщо параметр відсутній, використовується значення ServiceKey з тіла запиту CreateOrder. |
items/orderId |
необов'язковий параметр. Ідентифікатор внутрішнього замовлення Мерчант для маркування конкретного спліту (частини) платежу. | Якщо параметр відсутній, використовується значення OrderId, передане в тілі запиту CreateOrder. |
items/bankingDetails |
банківські реквізити кожного розщепленого платежу. | |
items/unit |
може бути Amount (сума розщепленого платежу в грн.) або Percent (сума розщепленого платежу вважається відсотком від загального). | |
items/value |
значення у цифрах. | |
items/withCommission - true/false |
Вказує з якого з одержувачів слід утримати внутрішню комісію. | Сума комісії розраховується із загальної суми платежу, а утримується - з першого одержувача зі splitting, у якого withCommission=true. Якщо ні в кого з splitting не зазначено withCommission=true, то комісія втікає з “основного” одержувача, вказаного в bankingDetails.
Якщо у всіх значення withCommission=false (або не передали), то комісія утримається з "основного одержувача", вказаного в параметрі bankingDetails Якщо всі значення withCommission=true, то комісія утримається з першого одержувача, зазначеного в splitting. Залишок буде надіслано на реквізити основного платежу з bankingDetails або bankingDetailsId. При встановленому сервісом Типі розрахунків “За актами", одержувачам перераховується повна сума, без відрахування комісії, незалежно від значення WithComission. |
Після виконання сплітування під кожен спліт (частини) платежу на стороні EasyPay створюється фінансова транзакція з унікальним transactionID.
- Якщо списання грошей з картки пройшло успішно і всі реквізити для спліту вказані корректно (доступні) - всі транзакції набувають успішного статусу і по кожній транзакції відправляється колбек.
- Якщо списання грошей з картки пройшло неуспішно – запит відхиляється з кодом фінансової помилки;
- Якщо списання грошей з картки пройшло успішно, але хоча б один із реквізитів зазначено неправильно – всі транзакції спліту (частини) платежу – будуть відхилені.
Після проведення успішного списання та сплітування по кожній фінансовій транзакції в рамках спліту направляється колбек (нотифікація) про успішний платіж. Приклад коллбека (нотифікації) вказаний у повідомлення про платіж.
Якщо параметр userPaymentInstrument не є порожнім, створення платежу буде відбуватися автоматично.
Для різних інструментів передаються такі параметри:
userPaymentInstrument – інструмент оплати.
*Картка (PCI DSS)
"userPaymentInstrument": {
"instrumentType": "Card",
"pan": "5168123456780123",
"expire": "MM/YY",
"cvv": "string" }
*Токенізована Карта
{"userInfo":{"phone":"380935207603"}, /Phone,під яким токенізована карта/
…
"userPaymentInstrument": {
"instrumentType": "Card",
"cardGuid": "guid", /токен картки/
}
}
Kyivstar Money/Life Money /VodafoneMoney
"userPaymentInstrument": {
"instrumentType": "KSMoney / LifeMoney / VodafoneMoney",
"phone": "380xxYYYYYYY" }
ApplePay/GooglePay
"userPaymentInstrument": {
"instrumentType": "ApplePay / GooglePay",
"token": “string”/Токен, отриманий від Apple | Google /
}
- partnerInfo – інформація про партнера
- partnerInfo.name – найменування партнера
- partnerInfo.id – ВД (ЄДРПОУ) партнера
- partnerInfo.account – рахунок партнера (особовий рахунок/IBAN…)