MerchantAPI: відмінності між версіями

← Попереднє редагування Наступне редагування →

Версія за 11:09, 11 вересня 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).

GET /api/system/createApp

POST /api/system/createApp

❗️ На даний момент відсутня можливість тестування з використанням фейкових оплат / тестових карток. Платежі тільки реальні, їх можна відмінити в день оплати методом cancelOrder (п. 2.6).

Основні запити/відповіді

Реєстрація точки та створення сесії

POST /api/system/createApp

Цей метод слід викликати, коли користувач вперше звертається до платіжної сторінки. Якщо браузер або пристрій змінюються, метод знову з'являється

Request

Headers

'PartnerKey: partnerName' 
'locale: ua'

Body

Response

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

Request

Headers

'PartnerKey:  partnerName'
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'

body

Response

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`	тип платіжного процесу	Можливі значення: PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення. Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"} Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в п. 2.7, про токенізацію - в п. 4.1.2)
`userInfo/phone`	номер телефону (або ідентифікатор) клієнта	Номер телефону необхідний: для отримання списку карток MasterPass гаманця для отримання списку токенізованих карток (інформація буде в масиві 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, тому редирект не можна використовувати як індикатор успішної оплати, отримання оповіщення про успішний платіж - див. п. 2.7) 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$"
},

Reccurent - інформація для створення рекурентного платежу на основі поточного.

"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"
       }

Параметр	Характеристика	Коментарій
`additionalItems`	необов'язкові додаткові параметри
`PayerEmail`	Емейл клієнта для оповіщення його у разі неоплаченого замовлення та для автоматичного заповнення поля “Надіслати квитанцію на email” на сторінці оплати.	Якщо параметр передається – він не може бути порожнім і має відповідати формату email.
`PayerPhone`	Телефон клієнта, на який протягом 15-20 хв після виклику CreateOrder відправиться нагадування про неоплачене замовлення (смс або вайбер).	Якщо параметр передається, він не може бути порожнім і повинен відповідати формату телефону.
`Merchant.UrlNotify`	URL для надсилання нотифікації за успішним платежем (callback).	див. п. 2.7. Параметр не може бути порожнім і має відповідати формату URL.
`Merchant.Param1`	індивідуальний параметр партнера	Param1 узгоджується з 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="
                    }
               }
           ]
       }
   ]

Параметр	Характеристика	Коментарій
`additionalItems`	необов'язкові додаткові параметри, наприклад	`"additionalItems":{` `"PayerEmail":"[email protected]",` `"PayerPhone":"380930007603",` `"Merchant.UrlNotify":"https://notify.url",` `"Merchant.Param1":"CustomValue",` `"CurrencyAmountLabel":"123.56$"` `}`
`PayerEmail`	Емейл клієнта для оповіщення його у разі неоплаченого замовлення та для автоматичного заповнення поля “Надіслати квитанцію на email” на сторінці оплати	Якщо параметр передається – він не може бути порожнім і має відповідати формату email
`AppId`	ідентифікатор торгової точки партнера	параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)
`AppId`	ідентифікатор торгової точки партнера	параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)
`AppId`	ідентифікатор торгової точки партнера	параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)	тип платіжного процесу, можливі значення:	PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення. Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"} Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в п. 2.7, про токенізацію - в п. 4.1.2)

@@ Рядок 629: / Рядок 629: @@
+<br>
-<table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
-    <!-- Перший рядок - заголовок -->
-    <!-- Другий рядок -->
-    <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;">.</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;">ідентифікатор сервісу торговця у системі EasyPay.</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>description</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;">опис замовлення (до 120 символів)
-</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;"></td>
-    </tr>
-    <!-- Шостий рядок -->
-    <tr>
-      <td style="border: none; padding-right: 10px; text-align: left;">'''<code>paymentOperation</code>'''</td>
        <td style="border: none; padding-right: 10px; text-align: left;">тип платіжного процесу, можливі значення: </td>
        <td style="border: none; text-align: left;">PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення.