Створення замовлення: відмінності між версіями

Матеріал з apidocs
Перейти до: навігація, пошук
← Попереднє редагування
ВізуальнийВікірозмітка
Немає опису редагування
Немає опису редагування
 
Рядок 1: Рядок 1:
== Зміст ==
{{APINav}}  
{{APINav}}  
==== Створення замовлення ====
==== Створення замовлення ====

Поточна версія на 09:26, 9 вересня 2025

Зміст

Merchant API

Головна сторінка

(Токенізація з передачею даних картки у запиті

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

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


⚠️ Важливо! Для кожного нового запиту 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 тип платіжного процесу Можливі значення:
  • PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення.
  • Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"}
  • Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в Повідомлення про платіж, про токенізацію.
userInfo/phone номер телефону (або ідентифікатор) клієнта Номер телефону необхідний:
  • для отримання списку токенізованих карток (інформація буде в масиві StoredCards)
  • при оплаті із зазначенням токена картки
  • для токенізації картки після успішної оплати разом із параметром
expire час життя замовлення Після закінчення заданого часу замовлення сплатити неможливо. Час життя сторінки може відображатися на платіжній сторінці у вигляді таймера (за замовчуванням таймер вимкнено). Значення має бути більшим за поточний час на 6 хвилин. Значення за замовчуванням - 3 дні
sOneTimePay включає можливість успішно оплатити замовлення лише 1 раз за конкретним forwardUrl Значення:
  • True - за замовчуванням;
  • False - оплатити замовлення по тому самому forwardUrl можна буде кілька разів;
urls
  • back - URL для повернення на вказану сторінку з фінальної сторінки успіху EasyPay.
  • success - URL сторінки успіху, для редиректу клієнта у разі успішної оплати.
  • failed - URL сторінки помилки для редиректу клієнта у разі неуспішної оплати
  • back - На фінальній сторінці EasyPay вгорі зліва з'явиться кнопка “Повернутись назад” з посиланням на вказану URL-адресу. Параметр не може бути порожнім і повинен відповідати формату URL.
  • success - у разі, якщо не було передано urls{success,failed} для редиректу після оплати. Після оплати клієнт може не дочекатися редиректу на цей url, тому редирект не можна використовувати як індикатор успішної оплати, отримання оповіщення про успішний платіж - див. Повідомлення про платіж
  • faild - приклад 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 – необов'язкові додаткові параметри, наприклад: 

"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 додаткові параметри (опціонально)
  • reccurent/properties/amount - сума кожного рекурентного платежу, наступного після основної оплати (опціонально)
  • reccurent/properties/failedCount - ккількість поспіль неуспішних викликів рекурентних оплат, після чого рекурентний платіж видаляється (опціонально). За замовчуванням - 4 спроби: при неуспіху - повторюється спроба кожні 20-30 хвилин, 4 неуспішних спроби поспіль по одному recurrentId - і рекурент відключається. Якщо після 3 неуспішних спроб була 1 успішна, то лічильник неуспішних для цього рекурента скидається.
  • reccurent/properties/failedRule - cron-правило (період) повтору при неуспішному виклику рекурента (опціонально)
  • reccurent/properties/UrlNotify - URL для надсилання нотифікації за успішним рекурентним платежем (callback), див. Повідомлення про платіж


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


ідентифікатор банківських реквізитів із довідника, який узгоджений із конкретним партнером та перебуває в системі EasyPay.



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


Отримано з https://apidocs.easypay.ua/index.php?title=Створення_замовлення&oldid=2212