MerchantAPI

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

---

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

Щоб отримати платежі, ви можете використовувати 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);	.
orderId	ідентифікатор сервісу торговця у системі EasyPay.
description	секретний ключ для формування підпису	опис замовлення (до 120 символів)
amount	сума замовлення, роздільник - точка;
paymentOperation	тип платіжного процесу, можливі значення:	PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення. Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"} Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в п. 2.7, про токенізацію - в п. 4.1.2)