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

Матеріал з apidocs
Перейти до: навігація, пошук
← Попереднє редагування
ВізуальнийВікірозмітка
Немає опису редагування
 
(Не показані 33 проміжні версії цього користувача)
Рядок 1: Рядок 1:
== Реєстрація точки та створення сесії ==
{{APINav}}
Цей метод слід викликати, коли користувач вперше звертається до платіжної сторінки. Якщо браузер або пристрій змінюються, метод знову з'являється
<div style="width: 100%; display: flex; justify-content: space-between; gap: 16px; box-sizing: border-box; padding: 8px 0;">
<p style="border: 1px solid #9ACD32; background-color: rgba(192, 255, 192, 0.5); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; position: relative; padding-left: 80px;">
    <span style="position: absolute; top: 10px; left: 10px; background-color: #006400; color: white; padding: 2px 12px; border-radius: 4px; font-size: 14px; font-weight: bold;">POST</span>
    <span style="margin-left: 5px; font-weight: bold; font-size: 16px;">/api/system/createApp</span>
</p>
'''Request'''<syntaxhighlight line="1" lang="json">
headers:


"PartnerKey": "partnerName",
   <!-- Ліва кнопка -->
"locale": "ua"
  <div style="
 
     position: relative;
 
     flex: 1;  
 
     min-width: 150px;  
     background: rgba(135, 206, 250, 0.1);  
</syntaxhighlight>'''Response'''<syntaxhighlight lang="json-object" line="1">
     padding: 8px 14px;  
body:
     border-radius: 8px;  
 
     border: 1px solid #007BFF;  
{
     color: #007BFF;  
  "logoPath": "https://cdn.easypay.ua/logo/",
     font-weight: bold;  
  "hintImagesPath": "https://cdn.easypay.ua/hint_images/",
     font-size: 1em; /* пропорційний розмір */
  "apiVersion": "1.0",
     display: flex;  
  "appId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1",
     align-items: center;  
  "pageId": "f3f2b678-a3c4-45ba-a865-a136fe4a62bd",
     justify-content: center;
   "error": null
     text-align: center;
}
     cursor: pointer;
 
   ">
</syntaxhighlight>'''Характеристика параметрів'''<table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">        '''Параметри''' <table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
<!-- Текст у кутку --><span style="position: absolute; top: 6px; left: 8px;">← Назад</span>
    <!-- Перший рядок - заголовок -->
     <!-- Основний текст -->
    <tr>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
    </tr>
 
    <!-- Другий рядок --><!-- Третій рядок --><!-- Четвертий рядок --><!-- П'ятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">за замовчуванням, якщо не було активності за запитами,
час життя AppId - 3 місяці. З кожним запитом життя AppId автоматично продовжується.
</td>
    </tr>
 
    <!-- Шостий рядок -->
     <tr>
      <td style="border: none; padding-right: 10px; text-align: left;">'''<code>PageId</code>'''</td>
      <td style="border: none; padding-right: 10px; text-align: left;">ідентифікатор сесії </td>
      <td style="border: none; text-align: left;">параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID</td>
    </tr>
  </table>
<br>
 
== Створення сесії ==
----Даний метод створює новий екземпляр сеансу для користувача , <code>PageId</code>.
<br>
<p style="border: 1px solid #9ACD32; background-color: rgba(144, 238, 144, 0.5); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; position: relative; padding-left: 80px;">
     <span style="position: absolute; top: 10px; left: 10px; background-color: #006400; color: white; padding: 2px 12px; border-radius: 4px; font-size: 14px; font-weight: bold;">POST</span>
     <span style="margin-left: 5px; font-weight: bold; font-size: 16px;">/api/system/createPage</span>
</p>'''Request'''<syntaxhighlight line="1" lang="json">
headers
 
"PartnerKey":  "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
 
</syntaxhighlight>'''Response'''<syntaxhighlight lang="json" line="1">
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
}
 
</syntaxhighlight>'''Характеристика параметрів''' <table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">        <table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
    <!-- Перший рядок - заголовок -->
     <tr>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
    </tr>
 
    <!-- Другий рядок --><!-- Третій рядок --><!-- Четвертий рядок --><!-- П'ятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">за замовчуванням, якщо не було активності за запитами,
час життя AppId - 3 місяці. З кожним запитом життя AppId автоматично продовжується.
</td>
    </tr>
 
    <!-- Шостий рядок -->
    <tr>
      <td style="border: none; padding-right: 10px; text-align: left;">'''<code>PageId</code>'''</td>
      <td style="border: none; padding-right: 10px; text-align: left;">ідентифікатор сесії </td>
      <td style="border: none; text-align: left;">За замовчуванням, якщо не було активності за запитами, час життя PageId - 20 хвилин. З кожним запитом життя PageId автоматично продовжується.</td>
    </tr>
  </table>
 
== Створення замовлення ==
Перед викликом цього методу потрібно викликати один із методів:
 
* [[MerchantAPI#Реєстрація точки та створення сесії|CreateApp]]
* [[MerchantAPI#Створення сесії|CreatePage]]
 
<br>
<p style="border: 1px solid #FFA500; background-color: rgba(255, 165, 0, 0.1); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; color: #333; position: relative;">
     ⚠️ <strong>Важливо!</strong> Для кожного нового запиту <span style="background-color: #EDEDED; padding: 2px 5px; border-radius: 4px; font-family: monospace; color: #D63384;">CreateOrder</span> потрібно використовувати унікальний <span style="background-color: #EDEDED; padding: 2px 5px; border-radius: 4px; font-family: monospace; color: #D63384;">PageID</span>.
</p>
<p style="border: 1px solid #9ACD32; background-color: rgba(144, 238, 144, 0.5); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; position: relative; padding-left: 80px;">
     <span style="position: absolute; top: 10px; left: 10px; background-color: #006400; color: white; padding: 2px 12px; border-radius: 4px; font-size: 14px; font-weight: bold;">POST</span>
    <span style="margin-left: 5px; font-weight: bold; font-size: 16px;"> /api/merchant/createOrder</span>
</p>
 
</p><syntaxhighlight lang="markdown" line="1">
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>
</syntaxhighlight><syntaxhighlight lang="json" line="1">
{
  "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"
}
}
 
</syntaxhighlight>'''Опис  параметрів''' <table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
<!-- Перший рядок - заголовок -->
    <tr>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
 
    <!-- Другий рядок -->
     <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>serviceKey</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор послуги мерчанта (видає EasyPay)</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.</td>
     </tr>
 
    <!-- Третій рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>orderId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">унікальний ідентифікатор номера замовлення у системі партнера</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">магазину чи послуги
передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
</td>
    </tr>
 
    <!-- Четвертий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>description</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">опис замовлення (до 120 символів)</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">відомий лише торговцю та EasyPay
передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
</td>
    </tr>
 
    <!-- П'ятий рядок -->
     <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>amount</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">сума замовлення, роздільник - точка </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
   
    </tr>
 
    <!-- Шостий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>paymentOperation</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">тип платіжного процесу </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Можливі значення:
 
* '''PaymentTokenization -''' використовується для токенізації картки, якою буде сплачено це замовлення.
* '''Працює лише для інструмента “карта”'''. Повинен бути заповнений ідентифікатор клієнта '''"userInfo": { "phone": "string"}'''
* Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в [[MerchantAPI#Повідомлення про платіж|Повідомлення про платіж]], про [[MerchantAPI#Токенізація за допомогою введення даних картки користувачем на сторінці (сертифікація PCI:DSS не потрібна)|токенізацію]].
</td>
    </tr>
 
    <!-- Cьомий рядок-->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>userInfo/phone</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">номер телефону (або ідентифікатор) клієнта </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Номер телефону необхідний:
 
* для отримання списку токенізованих карток (інформація буде в масиві StoredCards)
* при оплаті із зазначенням токена картки
* для токенізації картки після успішної оплати разом із параметром
</td>
    </tr>
 
    <!-- Восьмий рядок->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
      </tr>
 
  <!-- Девятий рядок->
      <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
  </table>
 
      <!-- Десятий рядок->
      <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
 
      </tr>
 
    <!-- Одинадцятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>expire</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">час життя замовлення </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Після закінчення заданого часу замовлення сплатити неможливо. Час життя сторінки може відображатися на платіжній сторінці у вигляді таймера (за замовчуванням таймер вимкнено). Значення має бути більшим за поточний час на 6 хвилин.
'''Значення за замовчуванням - 3 дні'''</td>
    </tr>   
 
    <!-- Дванадцятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>sOneTimePay</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">включає можливість успішно оплатити замовлення лише 1 раз за конкретним forwardUrl </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Значення:
 
* True - за замовчуванням;
* False - оплатити замовлення по тому самому ''forwardUrl'' можна буде кілька разів;</td>
</tr>
 
    <!-- Тринадцятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>urls</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">
*'''back -''' URL для повернення на вказану сторінку з фінальної сторінки успіху EasyPay.
* '''success -''' URL сторінки успіху, для редиректу клієнта у разі успішної оплати.
* '''failed -''' URL сторінки помилки для редиректу клієнта у разі неуспішної оплати</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">
* '''back -'''  На фінальній сторінці EasyPay вгорі зліва з'явиться кнопка “Повернутись назад” з посиланням на вказану URL-адресу. Параметр не може бути порожнім і повинен відповідати формату URL.
* '''success''' -  у разі, якщо не було передано urls{success,failed} для редиректу після оплати. Після оплати клієнт може не дочекатися редиректу на цей url, тому редирект не можна використовувати як індикатор успішної оплати, отримання оповіщення про успішний платіж - '''див.''' [[MerchantAPI#Повідомлення про платіж|Повідомлення про платіж]]
* '''faild -''' приклад get-параметрів, які приходять на '''url.failed та url.succes''' (те ж, але без ''errorCode''):
 
<code>?serviceKey=merchanttest-5310&orderId=re9r9er94jr&amount=1.20&description=</code>
 
<code>Тестове+описання+замовлення&transactionId=722443797&date=2019-06-11T14:49:07&recurrentId=&''errorCode=PAYMENT_ALFABANK_-2006''&sign=</code>
 
<code>eYkFYixpB3wnKoZDzkAiqWgdMkeHETDWmDsFMCaPO44=</code>
</td>
  </table>
 
<br>
 
'''Необов'язкові додаткові поля'''
 
'''<code>additionalItems</code> –''' необов'язкові додаткові параметри, наприклад:
<br>
<syntaxhighlight lang="json" line="1">
"additionalItems":{
  "PayerEmail":"[email protected]",
  "PayerPhone":"380930007603",
  "Merchant.UrlNotify":"https://notify.url",
  "Merchant.Param1":"CustomValue",
  "CurrencyAmountLabel":"123.56$"
},
</syntaxhighlight>'''Опис параметрів<br>'''
<table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
     <!-- Перший рядок - заголовок -->
    <tr>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
    </tr>
 
    <!-- Другий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>PayerEmail</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">емейл клієнта для оповіщення його у разі неоплаченого замовлення та для автоматичного заповнення поля “Надіслати квитанцію на email” на сторінці оплати. </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Якщо параметр передається – він не може бути порожнім і має відповідати формату email.</td>
    </tr>
 
    <!-- Третій рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>PayerPhone</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">телефон клієнта, на який протягом 15-20 хв після виклику CreateOrder відправиться нагадування про неоплачене замовлення (смс або вайбер). </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Якщо параметр передається, він не може бути порожнім і повинен відповідати формату телефону.
</td>
    </tr>
 
    <!-- Четвертий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>Merchant.UrlNotify</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">URL для надсилання нотифікації за успішним платежем (callback), див. [[MerchantAPI#Повідомлення про платіж|Повідомлення про платіж]]. </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Параметр не може бути порожнім і має відповідати формату URL.
</td>
    </tr>
 
    <!-- П'ятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>Merchant.Param1</code>''' </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">індивідуальний параметр партнера Param1 узгоджується з EasyPay </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;"></td>
   
    </tr>
</table>
 
<br>
'''<code>reccurentPayment</code> -''' інформація для створення рекурентного платежу на основі поточного. Рекурентний платіж буде створений за розкладом, якщо основний платіж виконаний за допомогою інструментів card, Rcard, Vcard, LifeMoney
<br><syntaxhighlight lang="json-object" line="1">
"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"
      }
 
</syntaxhighlight>'''Опис параметрів'''<table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
    <!-- Перший рядок - заголовок -->
    <tr>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
    </tr>
 
    <!-- Другий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>cronRule</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">правило у cron-форматі, з якою періодичністю повторювати рекурентний платіж, наприклад 10 20 15 * * (кожного 15 числа місяця о 20:10). </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Якщо ця властивість порожня, значить рекурентний платіж виконуватиметься на вимогу продавця.
'''Плануйте перше виконання рекуренту щонайменше 20 хвилин від дати успішного платежу.'''</td>
    </tr>
 
    <!-- Третій рядок -->
     <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>dateExpire</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">дата, після якої не проводити рекурентний платіж.</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">магазину чи послуги
передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
</td>
    </tr>
 
    <!-- Четвертий рядок -->
     <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>dateRun</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">дата першого запуску рекурентного платежу (опціонально). </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Якщо не заданий, перший запуск розраховується за '''recurrent/cronRule'''
</td>
    </tr>
 
    <!-- П'ятий рядок -->
     <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>properties</code>''' </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">додаткові параметри (опціонально) </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">
* '''reccurent/properties/amount -''' сума кожного рекурентного платежу, наступного після основної оплати (опціонально)
* '''reccurent/properties/failedCount -''' ккількість поспіль неуспішних викликів рекурентних оплат, після чого рекурентний платіж видаляється (опціонально). За замовчуванням - 4 спроби: при неуспіху - повторюється спроба кожні 20-30 хвилин, 4 неуспішних спроби поспіль по одному recurrentId - і рекурент відключається. Якщо після 3 неуспішних спроб була 1 успішна, то лічильник неуспішних для цього рекурента скидається.
* '''reccurent/properties/failedRule -''' cron-правило (період) повтору при неуспішному виклику рекурента (опціонально)
* '''reccurent/properties/UrlNotify''' - URL для надсилання нотифікації за успішним '''рекурентним''' платежем (callback), див. [[MerchantAPI#Повідомлення про платіж|Повідомлення про платіж]]
</td>
  </table> 
<br>
'''<code>bankingDetails</code> -''' передача банківських реквізитів для перерахування коштів у випадку, якщо банківські реквізити можуть змінюватися щодо різних платежів одного сервісу продавця. На стороні EasyPay має бути увімкнено режим "Отримувати реквізити із запиту".
<br>
<syntaxhighlight lang="json" line="1">
{
  "bankingDetails": {
    "payee": {
      "id": "123664578",
      "name": "департамент патрульної поліції",
      "bank": {
        "name": "пат пумб",
        "mfo": "330556",
        "account": "123654778889"
      }
    },
    "payer": { "name": "Иванова Мария" },
    "narrative": { "name": "Переказ коштів згідно договору з ФК № 111/11-П від 11.11.1111 р. за виключенням винагороди за їх переказ згідно реєстру від [work_date]р." }
  }
}
 
</syntaxhighlight>'''Опис параметрів''' <table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;"><tr>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>payee/ID</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">код одержувача</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">ЄДРПОУ або ІПН</td>
     </tr><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>payee/Name</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">одержувач </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">до 38 символів
</td>
    </tr><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>Payee/Bank/Name</code>''' </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">банк отримувача</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">до 38 символів
 
</td>
    </tr><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>Payee/Bank/Mfo</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">МФО банку </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">може не заповнюватися, якщо Payee/Bank/Account містить IBAN</td>
   
    </tr><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>Payee/Bank/Account</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">р/р одержувача або IBAN </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">
</td>
    </tr><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>Payer/Name</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">платник </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">
</td>
    </tr><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>Narrative/Name</code>''' </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">призначення платежу </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">до 157 символів</td>
    </tr><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>bankingDetailsId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">повну структуру bankingDetails можна не передавати, для цього достатньо передати  </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;"></td>
</tr><tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>bankingDetailsId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">
 
 
ідентифікатор банківських реквізитів із довідника, який узгоджений із конкретним партнером та перебуває в системі EasyPay.
</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">
 
 
</td>
  </table>
 
 
'''Splitting''' - інформація щодо сплітування (розщеплення) платежу.
 
Частина загальної суми з order/amount розподіляється відповідно до інформації в splitting/items/value, а залишок - йде на основні реквізити з bankingDetails (або bankingDetailsId). На стороні EasyPay має бути увімкнено режим “Отримувати реквізити із запиту
 
Структура '''items''' це масив. Основний платіж буде розщеплений стільки платежів, скільки міститься у цьому масиві плюс залишок. Кожен розщеплений платіж буде надіслано на відповідні банківські реквізити <code>items/bankingDetails</code>. Залишок коштів буде надіслано на реквізити основного платежу з <code>BankingDetails</code> або <code>bankingDetailsId,</code> які потрібно обов'язково вказувати під час сплітування.
<br>
<syntaxhighlight lang="json" line="1">
  },
"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
 
</syntaxhighlight><table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
    <!-- Перший рядок - заголовок -->
    <tr>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
    </tr>
 
    <!-- П'ятий рядок -->    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>items/serviceKey</code>''' </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">необов'язковий параметр. Ідентифікатор послуги, за якою ініціюється зарахування спліту (частини) платежу.  </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Якщо параметр відсутній, використовується значення ServiceKey з тіла запиту CreateOrder'''.'''
 
</td>
</tr>
 
    <!-- П'ятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>items/orderId</code>''' </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">необов'язковий параметр. Ідентифікатор внутрішнього замовлення Мерчант для маркування конкретного спліту (частини) платежу.  </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Якщо параметр відсутній, використовується значення OrderId, передане в тілі запиту CreateOrder.</td></tr>
 
    <!-- П'ятий рядок -->
     <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>items/bankingDetails</code>''' </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">банківські реквізити кожного розщепленого платежу. </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;"></td>
</tr>           
 
    <!-- Восьмий рядок->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
      </tr>
 
  <!-- Десятий рядок->
      <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
   </table>
 
      <!-- Десятий рядок->
      <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
 
      </tr>
 
    <!-- П'ятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>items/unit</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">може бути '''Amount''' (сума розщепленого платежу в грн.) або '''Percent''' (сума розщепленого платежу вважається відсотком від загального). </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;"></td>
    </tr>   
 
    <!-- П'ятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>items/value</code>''' </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">значення у цифрах. </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;"></td>
 
      </tr>
 
    <!-- П'ятий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>items/withCommission - true/false</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">Вказує з якого з одержувачів слід утримати внутрішню комісію. </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Сума комісії розраховується із загальної суми платежу, а утримується - з першого одержувача зі '''splitting,''' у якого '''withCommission=true'''. Якщо ні в кого з '''splitting''' не зазначено '''withCommission=true''', то комісія втікає з “основного” одержувача, вказаного в bankingDetails.
Якщо у всіх значення '''withCommission=false''' (або не передали), то комісія утримається з "основного одержувача", вказаного в параметрі '''bankingDetails'''
 
Якщо всі значення '''withCommission=true,''' то комісія утримається з першого одержувача, зазначеного в splitting. Залишок буде надіслано на реквізити основного платежу з '''bankingDetails''' або '''bankingDetailsId.'''
 
При встановленому сервісом Типі розрахунків “За актами", одержувачам перераховується повна сума, без відрахування комісії, незалежно від значення WithComission.
</td>
</tr>
 
     <!-- П'ятий рядок --></table>
<br>
 
Після виконання сплітування під кожен спліт (частини) платежу на стороні EasyPay створюється фінансова   транзакція з унікальним transactionID.
<br>
* Якщо списання грошей з картки пройшло успішно і всі реквізити для спліту вказані корректно (доступні) - всі транзакції набувають успішного статусу і по кожній транзакції відправляється колбек.
* Якщо списання грошей з картки пройшло неуспішно – запит відхиляється з кодом фінансової помилки;
* Якщо списання грошей з картки пройшло успішно, але хоча б один із реквізитів зазначено неправильно – всі транзакції спліту (частини) платежу – будуть відхилені.
<br>
<br>
Після проведення успішного списання та сплітування по кожній фінансовій транзакції в рамках спліту направляється колбек (нотифікація) про успішний платіж. Приклад коллбека (нотифікації) вказаний у [[MerchantAPI#Повідомлення про платіж|повідомлення про платіж]]'''''.'''''
<span>[[Загальні відомості]]</span>
 
<p style="border: 1px solid #4A90E2; background-color: rgba(74, 144, 226, 0.1); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; color: #333; position: relative;">
    Якщо параметр <span style="background-color: #EDEDED; padding: 2px 5px; border-radius: 4px; font-family: monospace; color: #D63384;">userPaymentInstrument</span> не є порожнім, створення платежу буде відбуватися автоматично.
</p>
 
 
Для різних інструментів передаються такі параметри:
 
'''userPaymentInstrument –''' інструмент оплати.
 
'''*Картка (PCI DSS)'''<syntaxhighlight lang="json" line="1">
"userPaymentInstrument": {
      "instrumentType": "Card",
      "pan": "5168123456780123",
      "expire": "MM/YY",
      "cvv": "string" }
 
</syntaxhighlight>
 
'''*Токенізована Карта'''<syntaxhighlight lang="json" line="1">
{"userInfo":{"phone":"380935207603"}, /Phone,під яким токенізована карта/
…
"userPaymentInstrument": {
      "instrumentType": "Card",
      "cardGuid": "guid", /токен картки/
}
}


</syntaxhighlight>
</div>
'''Kyivstar Money/Life Money /VodafoneMoney'''<syntaxhighlight lang="json" line="1">
"userPaymentInstrument": {
      "instrumentType": "KSMoney / LifeMoney / VodafoneMoney",
      "phone": "380xxYYYYYYY" }


</syntaxhighlight>'''ApplePay/GooglePay'''
  <!-- Права кнопка -->
<syntaxhighlight lang="json" line="1">
  <div style="
"userPaymentInstrument": {
    position: relative;
      "instrumentType": "ApplePay / GooglePay",
    flex: 1;
      "token": “string”/Токен, отриманий від Apple | Google /
    min-width: 150px;
}
    background: rgba(135, 206, 250, 0.1);
    padding: 8px 14px;
    border-radius: 8px;
    border: 1px solid #007BFF;
    color: #007BFF;
    font-weight: bold;
    font-size: 1em; /* пропорційний розмір */
    display: flex;
    align-items: center;
    justify-content: center;
    text-align: center;
    cursor: pointer;
  ">


</syntaxhighlight>


* '''partnerInfo –''' інформація про партнера
<span style="position: absolute; top: 6px; right: 8px;">Далі →</span>
* '''partnerInfo.name –''' найменування партнера
    <!-- Основний текст -->
* '''partnerInfo.id –''' ВД (ЄДРПОУ) партнера
<span>[[Реєстрація точки та створення сесії#Вступ|Реєстрація точки та створення сесії]]</span>
* '''partnerInfo.account –''' рахунок партнера (особовий рахунок/IBAN…)
  </div>


*
</div>
 
<br>

Поточна версія на 13:16, 14 серпня 2025

Merchant API

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

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

Отримано з https://apidocs.easypay.ua/index.php?title=Основні_запити_та_відповіді&oldid=2145