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

Матеріал з apidocs
Перейти до: навігація, пошук
← Попереднє редагуванняНаступне редагування →
ВізуальнийВікірозмітка
Немає опису редагування
Немає опису редагування
Рядок 556: Рядок 556:
</table>
</table>


<br>'''Reccurent''' - інформація для створення рекурентного платежу на основі поточного. Рекурентний платіж буде створений за розкладом, якщо основний платіж виконаний за допомогою інструментів card, Rcard, Vcard, LifeMoney.<syntaxhighlight lang="json" line="1">
<br>'''Reccurent''' - інформація для створення рекурентного платежу на основі поточного. Рекурентний платіж буде створений за розкладом, якщо основний платіж виконаний за допомогою інструментів card, Rcard, Vcard, LifeMoney<syntaxhighlight lang="json" line="1">
reccurent": {
reccurent": {
     "cronRule": "string",
     "cronRule": "string",
Рядок 570: Рядок 570:
</syntaxhighlight>
</syntaxhighlight>


<div style="background-color: rgba(173, 216, 230, 0.5); padding: 15px; font-family: Arial, sans-serif; font-size: 14px; color: #333;">
<div style="background-color: rgba(173, 216, 230, 0.5); padding: 15px; font-family: Arial, sans-serif; font-size: 14px; color: #333; border-left: 5px solid rgba(70, 130, 180, 0.7);">
  <div style="border-left: 5px solid rgba(70, 130, 180, 0.7); padding-left: 10px;">
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. <br>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. <br>
  Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. <br>
    Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. <br>
  Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
  </div>
</div>
</div>




Версія за 09:05, 12 вересня 2024

Загальні відомості

Протокол призначено для торговців, які є одержувачами платежів. Продавець підписує договір про прийняття платежів або анкету-акцепт до публічної оферти.


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

Запит заголовків

Надсилання запиту та відповіді у форматі JSON.

Обов'язкові параметри для визначення запиту від торговця (мерчанта):

--header 'Content-Type: application/json'

--header 'AppId: cd7fde18-15db-4d94-a91b-7cf8edd81209'

--header 'PageId: 3e7bf353-417a-410c-a22e-df8bdcccb760'

--header 'PartnerKey: easypay-test'

--header 'locale: ua'

--header 'Sign: bS+vPOwu1Sif1Iz47Cdh+z1RAi0s6X21C3uU0YNBNWE='

URLS

Production - https://merchantapi.easypay.ua

(в т.ч. для надсилання тестових запитів)

Реєстрація партнера

Реєстрація нового торговця - отримання  PartnerKey:

Параметр Характеристика Коментарій
PartnerKey унікальний ідентифікатор партнера (продавця) у системі EasyPay. передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
ServiceKey ідентифікатор сервісу торговця у системі EasyPay. магазину чи послуги

передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.

SecretKey секретний ключ для формування підпису відомий лише торговцю та EasyPay

передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.

AppId ідентифікатор торгової точки партнера параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)
PageId ідентифікатор сесії параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID
Для тестових* запитів використовуються наступні параметри:

PartnerKey = easypay-test

ServiceKey = MERCHANT-TEST

SecretKey = test

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

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


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

GET /api/system/createApp

POST /api/system/createApp

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


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


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

POST /api/system/createApp

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

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$"
}, де

Параметр Характеристика Коментарій
PayerEmail мейл клієнта для оповіщення його у разі неоплаченого замовлення та для автоматичного заповнення поля “Надіслати квитанцію на email” на сторінці оплати. Якщо параметр передається – він не може бути порожнім і має відповідати формату email.
PayerPhone телефон клієнта, на який протягом 15-20 хв після виклику CreateOrder відправиться нагадування про неоплачене замовлення (смс або вайбер). Якщо параметр передається, він не може бути порожнім і повинен відповідати формату телефону.
Merchant.UrlNotify URL для надсилання нотифікації за успішним платежем (callback), див. п. 2.7. Параметр не може бути порожнім і має відповідати формату URL.
Merchant.Param1 індивідуальний параметр партнера Param1 узгоджується з EasyPay

Reccurent - інформація для створення рекурентного платежу на основі поточного. Рекурентний платіж буде створений за розкладом, якщо основний платіж виконаний за допомогою інструментів card, Rcard, Vcard, LifeMoney
reccurent": {
    "cronRule": "string",
    "dateExpire": "2019-01-21T08:24:38.741Z",
    "dateRun": "2019-01-20T08:24:38.741Z",
    "properties":
       {
         "failedCount":0,
         "failedRule":"string",
         "amount":1.0,
         "UrlNotify":"http://notify.url"
       }

 Lorem ipsum dolor sit amet, consectetur adipiscing elit. 

 Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 

 Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.



Оплата 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 може використовуватись для декількох платежів) тип платіжного процесу, можливі значення: PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення.

Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"} Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в п. 2.7, про токенізацію - в п. 4.1.2)

Отримано з https://apidocs.easypay.ua/index.php?title=MerchantAPI&oldid=497