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='

URL

---

Посилання	Характеристика	Коментарій
https://merchantapi.easypay.ua	Production	в т.ч. для надсилання тестових запитів

Налаштування безпеки

---

Партнер надає IP, з яких будуть здійснюватися запити.

Реєстрація партнера в системі EasyPay

---

Реєстрація нового торговця передбачає отримання унікального ідентифікатора 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 (Скасування платежу)

Тестове середовище

Перед початком використання тестового середовища необхідно надати ір з яких будуть надходити запити, для відкриття доступу. На тестовому середовищі використовуються методи аналогічні Merchant Api.

Тестові дані:

• PartnerKey:credit-test
• SecretKey: credit-test

• serviceKey:TEST-CREDIT-PAYMENT - погашення
• serviceKey:TEST-CREDIT-PAYMENT - погашення
• serviceKey:TEST-CREDIT-TO-CARD - виплата
• Надсилання колбеків з Iр: 195.230.131.50
  

Тестові картки для верифікації/виплат:

Код підтвердження для 2дс при верифікації картки: 123456

Pan	Card.Expire/CVV	Статус виплати
5167803258208169	0525/111	Успішна виплата
4235751329985326	0525/111	Неуспішна виплата
4111111111111111	0525/111	Неуспішна без створення транзакції
4999999999990011	0525/111	Успішна виплата з затримкою статусу 5 хв
4217198608967728	0525/111	Неуспішна виплата з затримкою статусу 5 хв

Тестові картки для оплати:

Pan	Card.Expire/CVV	Статус виплати
5168752081922117	0128/111	Успішна оплата з 3ДС/ або не успішна оплата з 3ДС
4909150002132451	0129/111	Успішна 2ДС оплата
4300380058021820	0130/111	Не успішна з 3ДС + помилка PAYMENT_ALFABANK_116
5567217349220669	0130/111	Успішна оплата з 3ДС/ або не успішна оплата з 3ДС

У разі отримання помилки APPID_NOT_FOUND у відповідь на будь-який метод, необхідно повторити запит createApp до отримання точки ІД.

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

---

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

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

POST /api/system/createApp

Request

headers:

"PartnerKey": "partnerName",
"locale": "ua"

Response

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

Створення сесії

---

Даний метод створює новий екземпляр сеансу для користувача , PageId.

POST /api/system/createPage

Request

headers

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

Response

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 автоматично продовжується.

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

---

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

• CreateApp
• CreatePage

⚠️ Важливо! Для кожного нового запиту CreateOrder потрібно використовувати унікальний PageID.

POST /api/merchant/createOrder

headers

'Content-Type': 'application/json'
'PartnerKey': 'partnerName'
'locale': 'ua'
'AppId': 'a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId': '2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'Sign': 'e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='

<br>

{
   "userInfo": {
       "phone": "string"
    },
Обов'язкові параметри:

     "order": {
       "serviceKey": "string",
       "orderId": "string",
       "description": "string",
       "amount":1.01, (decimal)

Необов'язкові параметри:
       "paymentOperation":"PaymentTokenization",
       "additionalItems": {},
       "expire": "2019-04-15T07:49:20",
       "isOneTimePay": true,
       "fields": [
          {
           "fieldName": "string",
           "fieldValue": "string",
           "fieldKey": "string",
          }
        ]
     },
  "urls": {
    "success": "string",
    "failed": "string",
    "back": "string",
  },
  "bankingDetailsId": "string",
 "bankingDetails": {
    "payee": {
      "id": "string",
      "name": "string",
      "bank": {
        "name": "string",
        "mfo": "string",
        "account": "string"
      }
    },
    "payer": {
      "name": "string",
      "id": "string"
    },
    "narrative": {
      "name": "string"
    }
  },

  "reccurent": {
    "cronRule": "string",
    "dateExpire": "2019-01-21T08:24:38.741Z",
    "dateRun": "2019-01-20T08:24:38.741Z",
    "properties":
       {
         "failedCount":0,
         "failedRule":"string",
         "amount":1.0,
         "UrlNotify":"http://notify.url"
       }
  },
 "splitting": {
    "items": [
      {
     "serviceKey": "string",
     "orderId": "string”  
     "bankingDetailsId": "string",
     "bankingDetails": {
                      "payee": {
                                     "id": "string",
                                     "name": "string",
                                      "bank": {
                                                    "name": "string",
                                                     "mfo": "string",
                                                     "account": "string"
                                                  }
                                     },
                       "payer": {
                                      "name": "string"
                                     },
                       "narrative": {
                                      "name": "string"
                                     }
                                   },
        "unit": "Amount|Percent",
        "value": 0,
        "withCommission": false|true
      }
    ]
  },
  "userPaymentInstrument": {
      "instrumentType": "Card",
      "cardGuid": "guid",
     "pan": "string",
      "expire": "MM/YY",
      "cvv": "string",
  },
 "partnerInfo": {
      "id": "string",
      "name": "string",
      "account": "string"
}
}

Опис параметрів

Параметр	Характеристика	Коментарій
serviceKey	ідентифікатор послуги мерчанта (видає EasyPay)	передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
orderId	унікальний ідентифікатор номера замовлення у системі партнера	магазину чи послуги передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
description	опис замовлення (до 120 символів)	відомий лише торговцю та EasyPay передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
amount	сума замовлення, роздільник - точка	параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)
paymentOperation	тип платіжного процесу	Можливі значення: PaymentTokenization - використовується для токенізації картки, якою буде сплачено це замовлення. Працює лише для інструмента “карта”. Повинен бути заповнений ідентифікатор клієнта "userInfo": { "phone": "string"} Якщо передано URL для колбеку, то після успішної оплати відправляється колбек про платіж та колбек про токенізацію (приклади колбеків про оплату - в Повідомлення про платіж, про токенізацію.
userInfo/phone	номер телефону (або ідентифікатор) клієнта	Номер телефону необхідний: для отримання списку токенізованих карток (інформація буде в масиві StoredCards) при оплаті із зазначенням токена картки для токенізації картки після успішної оплати разом із параметром
expire	час життя замовлення	Після закінчення заданого часу замовлення сплатити неможливо. Час життя сторінки може відображатися на платіжній сторінці у вигляді таймера (за замовчуванням таймер вимкнено). Значення має бути більшим за поточний час на 6 хвилин. Значення за замовчуванням - 3 дні
sOneTimePay	включає можливість успішно оплатити замовлення лише 1 раз за конкретним forwardUrl	Значення: True - за замовчуванням; False - оплатити замовлення по тому самому forwardUrl можна буде кілька разів;
urls	back - URL для повернення на вказану сторінку з фінальної сторінки успіху EasyPay. success - URL сторінки успіху, для редиректу клієнта у разі успішної оплати. failed - URL сторінки помилки для редиректу клієнта у разі неуспішної оплати	back - На фінальній сторінці EasyPay вгорі зліва з'явиться кнопка “Повернутись назад” з посиланням на вказану URL-адресу. Параметр не може бути порожнім і повинен відповідати формату URL. success - у разі, якщо не було передано urls{success,failed} для редиректу після оплати. Після оплати клієнт може не дочекатися редиректу на цей url, тому редирект не можна використовувати як індикатор успішної оплати, отримання оповіщення про успішний платіж - див. Повідомлення про платіж faild - приклад get-параметрів, які приходять на url.failed та url.succes (те ж, але без errorCode): ?serviceKey=merchanttest-5310&orderId=re9r9er94jr&amount=1.20&description= Тестове+описання+замовлення&transactionId=722443797&date=2019-06-11T14:49:07&recurrentId=&errorCode=PAYMENT_ALFABANK_-2006&sign= eYkFYixpB3wnKoZDzkAiqWgdMkeHETDWmDsFMCaPO44=

Необов'язкові додаткові поля

additionalItems – необов'язкові додаткові параметри, наприклад:

"additionalItems":{
  "PayerEmail":"[email protected]",
  "PayerPhone":"380930007603",
  "Merchant.UrlNotify":"https://notify.url",
  "Merchant.Param1":"CustomValue",
  "CurrencyAmountLabel":"123.56$"
},

Опис параметрів

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

reccurentPayment - інформація для створення рекурентного платежу на основі поточного. Рекурентний платіж буде створений за розкладом, якщо основний платіж виконаний за допомогою інструментів card, Rcard, Vcard, LifeMoney

"reccurent": {
    "cronRule": "string",
    "dateExpire": "2019-01-21T08:24:38.741Z",
    "dateRun": "2019-01-20T08:24:38.741Z",
    "properties":
       {
         "failedCount":0,
         "failedRule":"string",
         "amount":1.0,
         "UrlNotify":"http://notify.url"
       }

Опис параметрів

Параметр	Характеристика	Коментарій
cronRule	правило у cron-форматі, з якою періодичністю повторювати рекурентний платіж, наприклад 10 20 15 * * (кожного 15 числа місяця о 20:10).	Якщо ця властивість порожня, значить рекурентний платіж виконуватиметься на вимогу продавця. Плануйте перше виконання рекуренту щонайменше 20 хвилин від дати успішного платежу.
dateExpire	дата, після якої не проводити рекурентний платіж.	магазину чи послуги передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
dateRun	дата першого запуску рекурентного платежу (опціонально).	Якщо не заданий, перший запуск розраховується за recurrent/cronRule
properties	додаткові параметри (опціонально)	reccurent/properties/amount - сума кожного рекурентного платежу, наступного після основної оплати (опціонально) reccurent/properties/failedCount - ккількість поспіль неуспішних викликів рекурентних оплат, після чого рекурентний платіж видаляється (опціонально). За замовчуванням - 4 спроби: при неуспіху - повторюється спроба кожні 20-30 хвилин, 4 неуспішних спроби поспіль по одному recurrentId - і рекурент відключається. Якщо після 3 неуспішних спроб була 1 успішна, то лічильник неуспішних для цього рекурента скидається. reccurent/properties/failedRule - cron-правило (період) повтору при неуспішному виклику рекурента (опціонально) reccurent/properties/UrlNotify - URL для надсилання нотифікації за успішним рекурентним платежем (callback), див. Повідомлення про платіж

bankingDetails - передача банківських реквізитів для перерахування коштів у випадку, якщо банківські реквізити можуть змінюватися щодо різних платежів одного сервісу продавця. На стороні EasyPay має бути увімкнено режим "Отримувати реквізити із запиту".

{
  "bankingDetails": {
    "payee": {
      "id": "123664578",
      "name": "департамент патрульної поліції",
      "bank": {
        "name": "пат пумб",
        "mfo": "330556",
        "account": "123654778889"
      }
    },
    "payer": { "name": "Иванова Мария" },
    "narrative": { "name": "Переказ коштів згідно договору з ФК № 111/11-П від 11.11.1111 р. за виключенням винагороди за їх переказ згідно реєстру від [work_date]р." }
  }
}

Опис параметрів

Параметр	Характеристика	Коментарій
payee/ID	код одержувача	ЄДРПОУ або ІПН
payee/Name	одержувач	до 38 символів
Payee/Bank/Name	банк отримувача	до 38 символів
Payee/Bank/Mfo	МФО банку	може не заповнюватися, якщо Payee/Bank/Account містить IBAN
Payee/Bank/Account	р/р одержувача або IBAN
Payer/Name	платник
Narrative/Name	призначення платежу	до 157 символів
bankingDetailsId	повну структуру bankingDetails можна не передавати, для цього достатньо передати
bankingDetailsId	ідентифікатор банківських реквізитів із довідника, який узгоджений із конкретним партнером та перебуває в системі EasyPay.

Splitting - інформація щодо сплітування (розщеплення) платежу.

Частина загальної суми з order/amount розподіляється відповідно до інформації в splitting/items/value, а залишок - йде на основні реквізити з bankingDetails (або bankingDetailsId). На стороні EasyPay має бути увімкнено режим “Отримувати реквізити із запиту

Структура items це масив. Основний платіж буде розщеплений стільки платежів, скільки міститься у цьому масиві плюс залишок. Кожен розщеплений платіж буде надіслано на відповідні банківські реквізити items/bankingDetails. Залишок коштів буде надіслано на реквізити основного платежу з BankingDetails або bankingDetailsId, які потрібно обов'язково вказувати під час сплітування.

  },
 "splitting": {
    "items": [
      {
     "serviceKey": "string",
     "orderId": "string" 
     "bankingDetailsId": "string",
     "bankingDetails": {
                      "payee": {
                                     "id": "string",
                                     "name": "string",
                                      "bank": {
                                                    "name": "string",
                                                     "mfo": "string",
                                                     "account": "string"
                                                  }
                                     },
                       "payer": {
                                      "name": "string"
                                     },
                       "narrative": {
                                      "name": "string"
                                     }
                                   },
        "unit": "Amount|Percent",
        "value": 0,
        "withCommission": false|true

Параметр	Характеристика	Коментарій
items/serviceKey	необов'язковий параметр. Ідентифікатор послуги, за якою ініціюється зарахування спліту (частини) платежу.	Якщо параметр відсутній, використовується значення ServiceKey з тіла запиту CreateOrder.
items/orderId	необов'язковий параметр. Ідентифікатор внутрішнього замовлення Мерчант для маркування конкретного спліту (частини) платежу.	Якщо параметр відсутній, використовується значення OrderId, передане в тілі запиту CreateOrder.
items/bankingDetails	банківські реквізити кожного розщепленого платежу.
items/unit	може бути Amount (сума розщепленого платежу в грн.) або Percent (сума розщепленого платежу вважається відсотком від загального).
items/value	значення у цифрах.
items/withCommission - true/false	Вказує з якого з одержувачів слід утримати внутрішню комісію.	Сума комісії розраховується із загальної суми платежу, а утримується - з першого одержувача зі splitting, у якого withCommission=true. Якщо ні в кого з splitting не зазначено withCommission=true, то комісія втікає з “основного” одержувача, вказаного в bankingDetails. Якщо у всіх значення withCommission=false (або не передали), то комісія утримається з "основного одержувача", вказаного в параметрі bankingDetails Якщо всі значення withCommission=true, то комісія утримається з першого одержувача, зазначеного в splitting. Залишок буде надіслано на реквізити основного платежу з bankingDetails або bankingDetailsId. При встановленому сервісом Типі розрахунків “За актами", одержувачам перераховується повна сума, без відрахування комісії, незалежно від значення WithComission.

Після виконання сплітування під кожен спліт (частини) платежу на стороні EasyPay створюється фінансова   транзакція з унікальним transactionID.

• Якщо списання грошей з картки пройшло успішно і всі реквізити для спліту вказані корректно (доступні) - всі транзакції набувають успішного статусу і по кожній транзакції відправляється колбек.
• Якщо списання грошей з картки пройшло неуспішно – запит відхиляється з кодом фінансової помилки;
• Якщо списання грошей з картки пройшло успішно, але хоча б один із реквізитів зазначено неправильно – всі транзакції спліту (частини) платежу – будуть відхилені.

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

Якщо параметр userPaymentInstrument не є порожнім, створення платежу буде відбуватися автоматично.

Для різних інструментів передаються такі параметри:

userPaymentInstrument – інструмент оплати.

*Картка (PCI DSS)

 "userPaymentInstrument": {
      "instrumentType": "Card",
      "pan": "5168123456780123",
      "expire": "MM/YY",
      "cvv": "string" }

*Токенізована Карта

{"userInfo":{"phone":"380935207603"}, /Phone,під яким токенізована карта/
…
"userPaymentInstrument": {
      "instrumentType": "Card",
      "cardGuid": "guid", /токен картки/
 }
}

Kyivstar Money/Life Money /VodafoneMoney

"userPaymentInstrument": {
      "instrumentType": "KSMoney / LifeMoney / VodafoneMoney",
      "phone": "380xxYYYYYYY" }

ApplePay/GooglePay

"userPaymentInstrument": {
      "instrumentType": "ApplePay / GooglePay",
      "token": “string”/Токен, отриманий від Apple | Google /
 }

• partnerInfo – інформація про партнера
• partnerInfo.name – найменування партнера
• partnerInfo.id – ВД (ЄДРПОУ) партнера
• partnerInfo.account – рахунок партнера (особовий рахунок/IBAN…)

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

Перед використанням методу потрібне додаткове налаштування терміналів зі сторони техпідтримкиEasyPay.

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

- CreateApp

- CreatePage

POST /api/merchant/createOrder

REQUEST HEADERS

  PartnerKey: partnerName
  locale: ua
  AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1
  PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d
  Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4=

REQUEST BODY

{
  "order": {
    "serviceKey": "string",
    "orderId": "string",
    "description": "string",
    "amount": 1.01,
    "paymentOperation": "Hold",
    "expire": "2019-04-15T07:49:20.009Z",
    "isOneTimePay": true,
    "additionalItems": {}
  },
  "urls": {
    "success": "string",
    "failed": "string"
  }
}

Опис параметрів

Параметр	Характеристика
serviceKey	ідентифікатор послуги
orderId	унікальний ідентифікатор замовлення в системі партнера
description	опис замовлення
amount	сума замовлення
paymentOperation = Hold	параметр, що вказує, що подальший платіж буде холдовано(зарезервовано) з можливістю підтвердження або скасування.

Необов'язкові параметри

Параметр	Характеристика	Коментарій
expire	час життя замовлення.	Після закінчення вказаного часу замовлення оплатити неможливо. При ненульовому значенні на платіжній сторінці відображатиметься таймер. Значення повинне перевищувати поточний час щонайменше на 5 хвилин. Типове значення — 3 дні.
isOneTimePay	вказує, чи можна оплатити одне замовлення кілька разів.	Типове значення — True.
additionalItems	додаткові параметри	наприклад: "additionalItems": { "PayerEmail" : "[email protected]", "PayerPhone" : "380930007603" }, де PayerEmail — емейл клієнта для сповіщення у разі неоплаченого замовлення та автоматичної підстановки на платіжній сторінці. PayerPhone — номер телефону для надсилання повідомлення (SMS або Viber) про неоплачене замовлення (через 15–20 хвилин після виклику CreateOrder).
URLs	URL сторінки успішної оплати для редиректу клієнта.	failed — URL сторінки помилки для редиректу клієнта. приклад параметрів, що передаються на url.success (без errorCode) і url.failed: ?serviceKey=merchanttest-5310&orderId=re9r9er94jr&amount=1.20&description=Тестове+описання+ замовлення&transactionId=722443797&date=2019-06-11T14:49:07&recurrentId=&errorCode=PAYMENT_ALFABANK_-2006&sign= eYkFYixpB3wnKoZDzkAiqWgdMkeHETDWmDsFMCaPO44=

RESPONSE

HEADERS 
-------
BODY
{
  "accountInfo": null,
  "bankingDetails": null,
  "amount": 1,
  "amountMax": 4999,
  "amountMin": 0.01,
  "paymentInstrumentsTypes": [
    {
      "instrumentType": "EMoney",
      "commission": 0,
      "amountMin": 0.01,
      "amountMax": 4999,
      "userPaymentInstruments": []
    },
    {
      "instrumentType": "RCard",
      "commission": 2,
      "amountMin": 0.01,
      "amountMax": 4999,
      "userPaymentInstruments": []
    },
    {
      "storedCards": [],
      "instrumentType": "Card",
      "commission": 2,
      "amountMin": 0.01,
      "amountMax": 4999,
      "userPaymentInstruments": [
        {
          "instrumentId": 4211698,
          "instrumentType": "Card",
          "instrumentValue": null,
          "alias": null,
          "commission": 2,
          "loyaltyCommission": null,
          "actionsKeys": null,
          "priorityIndex": 0,
          "additionalParams": {}
        }
      ]
    },
    {
      "walletStatus": "NotRegistered",
      "instrumentType": "MasterPass",
      "commission": 2,
      "amountMin": 0.01,
      "amountMax": 4999,
      "userPaymentInstruments": []
    },
    {
      "instrumentType": "LifeMoney",
      "commission": 0.03,
      "amountMin": 0.01,
      "amountMax": 4999,
      "userPaymentInstruments": [
        {
          "instrumentId": 5098216,
          "instrumentType": "LifeMoney",
          "instrumentValue": null,
          "alias": null,
          "commission": 0.03,
          "loyaltyCommission": null,
          "actionsKeys": null,
          "priorityIndex": 0,
          "additionalParams": {}
        }
      ]
    }
  ],
  "forwardUrl": "https://easypay.ua/whitepage/81b14a73-730c-40d4-8064-ce1c10e0c53b",
  "error": null
}

Параметр	Характеристика	Коментарій
accountInfo	додаткова інформація про послугу
amount	сума замовлення
amountMax	максимальна сума платежу за послугою
amountMin	мінімальна сума за послугою
forwardUrl	URL сторінки оплати, для партнерів, у яких немає сертифікатів PCI DSS для обробки карткових даних. Або якщо у партнера немає власної платіжної сторінки.
paymentInstrumentsTypes	список інструментів оплати. Інструмент RCard надається лише користувачам, які авторизовані в системі EasyPay. Можливі значення instrumentType	Можливі значення instrumentType: Card – платіжна картка RCard – платіжна картка, підв'язана в системі EasyPay

Холдування платежу можна здійснити, оплативши замовлення на сторінці оплати (перейти за forwardUrl), або вказавши в запиті createOrder інструмент оплати у userPaymentInstrument (див. Створення замовлення).

Клієнту відобразиться сторінка успішного платежу EasyPay, або сторінка, вказана в “urls”:{}.

Після спроби холдування платежу партнеру буде відправлено сповіщення, згідно з варіантом, вказаним в налаштуваннях сервісу Повідомлення про платіж.

Статус платежу необхідно перевірити методом orderState

Після успішного холдування необхідно викликати або unHoldOrder , або orderCancel

Якщо протягом повних 10 днів після холдування жоден з цих методів не буде викликаний, на 11-й день близько 05:00 платіж може бути відхилений емітентом, і кошти стануть доступні клієнту.

У транзакцію додається коментар: Автоматично відхилено через 10 днів. (SYSTEM ACCOUNT [dateTime])

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

Розхолдування платежу

Якщо цей метод не буде викликано протягом 10 днів, кошти повертаються клієнту, а платіж у системі відхиляється.

Перед викликом цього методу необхідно здійснити холдування транзакції

POST /api/merchant/unHoldOrder

REQUEST HEADERS

'PartnerKey: easypay-test' 
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='

REQUEST BODY

{
  "transactionId":955537573,
  "orderId":"hold_4",
  "serviceKey":"MERCHANT-TEST",
   "amount": 1.2
}

RESPONSE

{
 "paymentState": "accepted",
 "error": null
}

Опис параметрів запиту

Параметр	Характеристика	Коментарій
transactionId	унікальний номер платежу в системі EasyPay
orderId	унікальний ідентифікатор замовлення в системі партнера
amount	необов’язковий параметр, торгова сума, яку слід списати з картки.	Різниця повернеться клієнту на картку протягом 1–2 днів, залежно від регламенту банку

Опис параметрів відповіді

Параметр	Характеристика	Коментарій
paymentState	статус платежу	Можливі paymentState: • accepted - платіж успішний (кінцевий статус) • pending - платіж в обробці (некінцевий статус) • declined - платіж відхилений (кінцевий статус) • none - платіж не знайдено

Для платежів з 2DS переадресація на сторінку банку-емітента не відбувається, і користувач відразу отримує статус платежу.

Після спроби розхолдування платежу партнеру буде надіслано сповіщення згідно з варіантом, вказаним в налаштуваннях сервісу Повідомлення про платіж

Статус платежу необхідно перевіряти методом orderState

Параметри BrowseInfo при 3DS оплаті

У зв'язку з переходом банків - екваєрів на модель роботи 3D Secure 2.x, при створенні замовлення з одночасною передачею інструменту оплати в запиті (карта, токен карти, токен Apple / Google Pay), необхідно передавати додаткові параметри пристрою (браузера) клієнта в заголовках і в тілі запиту createOrder, у прикладі вони виділені:

POST /api/merchant/createOrder

HEADERS

 "appId: b15c4b64-8964-4c80-852e-df59a0e0d9b6",

   "pageId: 607514b8-1da5-490a-bdf3-0c6883131625",

   "partnerKey: easypay-test",

   "sign: XJ3roGhTLwAZXigBp/iVRdsXlZYdTSen3xSM+29GaRg=",

   "Content-Type:application/json",

   "AcceptHeader:*/*",

   "User-Agent:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36"

BODY

 "order":{
   "serviceKey":"MERCHANT-TEST",
   "orderId":"test_3ds2x",
   "additionalItems":{
     "Merchant.UrlNotify":"http://url.noti.fy"
   },
   "description":"Easy test payment",
   "amount":"1"
 },
 "userPaymentInstrument":{
   "instrumentType":"Card",
   "pan":"4444444444444444",
   "expire":"0599",
   "cvv":"123"
 },
 
 "browserInfo":{
   "colorDepth":"24",
   "screenHeight":"824",
   "screenWidth":"1536",
   "language":"uk-UA",
   "javaEnabled":"false",
   "javascriptEnabled": "true",
   "timeZone":"-180"
 }
 

Параметри

Параметр	Характеристика
AcceptHeader:*/*	передавайте без змін
User-Agent	передавайте клієнтський User-Agent

Приклад, як збирати дані на JS:

getBrowserInfo() {
    let browserInfoModel = {};
    browserInfoModel.colorDepth = window.screen.colorDepth.toString();
    browserInfoModel.screenHeight = window.screen.height.toString();
    browserInfoModel.screenWidth = window.screen.width.toString();
    browserInfoModel.language = window.navigator.language;
    browserInfoModel.javaEnabled = window.navigator.javaEnabled();
    browserInfoModel.timeZone = (new Date()).getTimezoneOffset().toString();
    return browserInfoModel;
  }

Якщо все передано правильно, то отримайте відповідь як нижче у прикладі "Якщо передано userPaymentInstrument (для випадку з 3DSecure)", або помилку оплати з картки, наприклад, "Недостатньо коштів". У випадку, якщо додаткові параметри передані неправильно, отримайте помилку платіжного сервісу, наприклад:

"errorCode":"PAYMENT_PUMB_SERVICE_FAILURE",
    "errorMessage":"Технічна помилка екваєра. Зверніться до служби підтримки EasyPay, або спробуйте пізніше"

Відповідь (RESPONSE):

header:
відсутній

body:
{
    "accountInfo": null,
    "bankingDetails": null,
    "amount": 1,
    "amountMax": 4999,
    "amountMin": 0.01,
    "paymentInstrumentsTypes": [
        {
            "instrumentType": "EMoney",
            "commission": 0,
            "amountMin": 0.01,
            "amountMax": 4999,
            "userPaymentInstruments": []
        },
        {
            "instrumentType": "RCard",
            "commission": 2,
            "amountMin": 0.01,
            "amountMax": 4999,
            "userPaymentInstruments": []
        },
        {
            "storedCards": [],
            "instrumentType": "Card",
            "commission": 2,
            "amountMin": 0.01,
            "amountMax": 4999,
            "userPaymentInstruments": [
                {
                    "instrumentId": 4211698,
                    "instrumentType": "Card",
                    "instrumentValue": null,
                    "alias": null,
                    "commission": 2,
                    "loyaltyCommission": null,
                    "actionsKeys": null,
                    "priorityIndex": 0,
                    "additionalParams": {}
                }
            ]
        },

        {
            "walletStatus": "NotRegistered",
            "instrumentType": "MasterPass",
            "commission": 2,
            "amountMin": 0.01,
            "amountMax": 4999,
            "userPaymentInstruments": []
        },
        {
            "instrumentType": "LifeMoney",
            "commission": 0.03,
            "amountMin": 0.01,
            "amountMax": 4999,
            "userPaymentInstruments": [
                {
 "instrumentId": 5098216,
                    "instrumentType": "LifeMoney",
                    "instrumentValue": null,
                    "alias": null,
                    "commission": 0.03,
                    "loyaltyCommission": null,
                    "actionsKeys": null,
                    "priorityIndex": 0,
                    "additionalParams": {}
                }
            ]
        }
    ],
    "forwardUrl": https://easypay.ua/whitepage/81b14a73-730c-40d4-8064-ce1c10e0c53b,
  "error": null,
}

Якщо передано userPaymentInstrument (для випадку з 3DSecure):
{
  "paymentState":"WaitVerify",
  "action":"https://merchantapi.easypay.ua/api/payment/redirect/4df828bf-379b-4e88-8868-f667f12d74a9",
  "actionContent":"<html><head></head><body><form action='https://acs.monobank.com.ua/PaReqVISA.jsp' method='post' id='submitForm'><input type='hidden' name='PaReq'  value='eJxVUsluwjAQ/RWUY6VgO2RFg1FoqJpDUgThwNF1XAglS7NUpF9fm4alt3nzxvNm3hjm5/w0+hZ1k5XFTCNjrI1Ewcs0K/YzbZu86K42p5AcaiGCjeBdLShEomnYXoyydKY5mGNuWh966mKmm6lH9HcHY91zLeZMmGkT19EorPy1+KIwCFGpMzYAXaHsWPMDK1oKjH8twpiaBBumBWiAkIs6DCgh9oQ4rmsRW2pgQH9pKFgu6NLf7Fb+7ikIN8k6XGyT8C0GdKGAl13R1j21zQmgK4CuPtFD21bNFCHBmr5i/bhjCJAiAN2HWnUqamSjc5bS+Mj7+Pg5iY5LIwp8HCe7nyjZ4igJZ4BUBaSsFdTABsYecUfEmxIyteQ6lzywXE1AidpgiKFSEv4D8ZgA6Xstz9JTz5XUDYE4V2UhZIU08xYDus/7/Kos5a0yz7Kx6dgWNpStl5R6n0knDBNblwYKAFKP0HAxNBxbRv8+wS+7NLXc' /><input type='hidden' name='TermUrl' value='https://merchantapi.easypay.ua/api/payment/confirm/185ff3c7-8daa-4715-af1a-23f7554d19bb,0e101596-2a6a-4a0e-92e2-dac1e7a5c69d,-1' /><input type='hidden' name='MD' value='ee6eda7e-6252-41af-a696-825e85b34878' /></form><script>document.getElementById('submitForm').submit();</script> </body></html>",
  "actionType":"FormRedirect",
  "status":"Need3Ds", "alternativeRedirectUrl":"https://merchantapi.easypay.ua/api/payment/altredirect/00f9befe-a200-4e4d-ae27-0a4bdbc443fc",
  "transactionId":860094566,
  "retrievalReferenceNo":null,
  "responseItems":{
    "SessionId":"a9692063-2db5-4d25-8a66-e62b4476d1e4",
    "MerchantOpertion":"CheckPaymentOperationOrder",
    "Operation":"CheckPayment",
    "BankingDetails":""
  },
  "error":null
}

Якщо передано userPaymentInstrument (для випадку без 3DSecure):
{
  "redirectUrl":null,
  "action":null,
  "paymentState":"Confirmed",
  "status":"Done",
  "actionType":"UrlRedirect",
  "transactionId":847870521,
"retrievalReferenceNo":null,
  "responseItems": null,
  "error":null
}

Опис параметрів

Параметр	Характеристика	Коментарій
accountInfo	додаткова інформація про послугу	Якщо параметр відсутній, використовується значення ServiceKey з тіла запиту CreateOrder.
amount	сума замовлення	Якщо параметр відсутній, використовується значення OrderId, передане в тілі запиту CreateOrder.
amountMax	максимальна сума платежу за послугою
amountMin	мінімальна сума за послугою
forwardUrl	URL сторінки оплати, для партнерів які не мають сертифікатів PCI DSS для обробки карткових даних. Або якщо партнер не має платіжної сторінки.	на сторінці оплати можемо відключати елементи інтерфейсу: - логотип EasyPay можемо приховувати - лічильник часу, що залишився до оплати, може бути відображений/прихований - поле "Призначення" (можемо вимкнути, або за замовчуванням зробити відкритим/закритим) - рядок з логотипом партнера та назвою можемо приховати - поле введення імейл сховати / відобразити - рядок з "Номер замовлення" приховати/показати
paymentInstrumentsTypes	список інструментів оплати. Інструменти Emoney, vcard та RCard видаємо тільки для користувачів, які авторизовані в системі EasyPay.	Можливі значення instrumentType Emoney – гаманець EasyPay Card – платіжна картка RCard – платіжна картка, підв'язана в системі EasyPay ApplePay – оплата через  ApplePay GooglePay – оплата через GooglePay LifeMoney – мобільні гроші Лайф. KsMoney –  мобільні гроші Київстар VodafoneMoney – мобільні гроші Водафон картки лояльності Fishka

3DSecure / mobile payments case:

Якщо передано userPaymentInstrument (для випадку з 3DSecure):

{
  "paymentState":"WaitVerify",
  "action":"https://merchantapi.easypay.ua/api/payment/redirect/4df828bf-379b-4e88-8868-f667f12d74a9",
  "actionContent":"<html><head></head><body><form" action="https://acs.monobank.com.ua/PaReqVISA.jsp' method='post' id='submitForm'><input type="hidden" name="PaReq" value='eJxVUsluwjAQ/RWUY6VgO2RFg1FoqJpDUgThwNF1XAglS7NUpF9fm4alt3nzxvNm3hjm5/w0+hZ1k5XFTCNjrI1Ewcs0K/YzbZu86K42p5AcaiGCjeBdLShEomnYXoyydKY5mGNuWh966mKmm6lH9HcHY91zLeZMmGkT19EorPy1+KIwCFGpMzYAXaHsWPMDK1oKjH8twpiaBBumBWiAkIs6DCgh9oQ4rmsRW2pgQH9pKFgu6NLf7Fb+7ikIN8k6XGyT8C0GdKGAl13R1j21zQmgK4CuPtFD21bNFCHBmr5i/bhjCJAiAN2HWnUqamSjc5bS+Mj7+Pg5iY5LIwp8HCe7nyjZ4igJZ4BUBaSsFdTABsYecUfEmxIyteQ6lzywXE1AidpgiKFSEv4D8ZgA6Xstz9JTz5XUDYE4V2UhZIU08xYDus/7/Kos5a0yz7Kx6dgWNpStl5R6n0knDBNblwYKAFKP0HAxNBxbRv8+wS+7NLXc' /><input type='hidden' name='TermUrl' value='https://merchantapi.easypay.ua/api/payment/confirm/185ff3c7-8daa-4715-af1a-23f7554d19bb,0e101596-2a6a-4a0e-92e2-dac1e7a5c69d,-1' /><input type='hidden' name='MD' value='ee6eda7e-6252-41af-a696-825e85b34878' /></form><script>document.getElementById('submitForm').submit();</script> </body></html>",
  "actionType":"FormRedirect",
  "status":"Need3Ds", "alternativeRedirectUrl":"https://merchantapi.easypay.ua/api/payment/altredirect/00f9befe-a200-4e4d-ae27-0a4bdbc443fc",
  "transactionId":"860094566",
  "retrievalReferenceNo":"null",
  "responseItems":{
    "SessionId":"a9692063-2db5-4d25-8a66-e62b4476d1e4",
    "MerchantOpertion":"CheckPaymentOperationOrder",
    "Operation":"CheckPayment",
    "BankingDetails":""
  },
  "error":null
}

Якщо передано userPaymentInstrument (для випадку без 3DSecure):
{
  "redirectUrl":null,
  "action":null,
  "paymentState":"Confirmed",
  "status":"Done",
  "actionType":"UrlRedirect",
  "transactionId":847870521,
"retrievalReferenceNo":null,
  "responseItems": null,
  "error":null
}

Опис параметрів

Параметр	Характеристика
paymentState	Confirmed - платіж підтверджений (кінцевий статус, якщо "status": "done") WaitConfirm - платіж у статусі "обробляється", необхідно додатково запросити фінальний статус платежу WaitVerify - від клієнта очікується підтвердження (наприклад, якщо "status": "Need3Ds" - необхідно пройти перевірку 3D Secure)
status	Done - додаткові дії не потрібні, якщо при цьому "зберіганнядержави":"затверджено", означає платіж повністю успішний. При іншому значенні paymentState- платіж не прийняв кінцевий статус, необхідно запросити статус (Перевірка статусу платежу). Need3Ds - необхідно підтвердження 3D Secure від клієнта (Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки) NeedConfirmCode - необхідно надіслати код перевірки зі смс методом confirmCodeVerification (Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки) NeedLookup - необхідно надіслати код перевірки з смс методом confirmCodeVerification (Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки)
actionType	тип наступної дії: "FormRedirect" -  необхідно створити сторінку (форму) з html-коду, який передано у параметрі "actionContent" :"<html>...</html>", відкрити її клієнту, наприклад, для проходження ним 3D-secure перевірки. Альтернативним варіантом є переадресація клієнта за посиланням параметра "alternativeRedirectUrl". Після проходження перевірки клієнт буде передресовано на фінальну сторінку EasyPay або на "urls": { "success": "string", "failed": "string" } "UrlRedirect" - переадресувати клієнта на посилання з "action" або переадресувати клієнта за посиланням з "alternativeRedirectUrl". "ConfirmCode" -необхідно надіслати код перевірки з смс методом confirmCodeVerification (Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки) "None" - можливий при використанні інструменту гаманець ("instrumentType": "EMoney"), кошти успішно списані з гаманця, партнеру надсилається повідомлення про списання.
actionContent	"<html>...</html>" - html форма сторінки банку для введення коду 3DS. Сформувати сторінку з коду та відкрити її клієнту. Після підтвердження платежу відбудеться 302-й редирект на ваші "urls" із запиту createOrder, або на фінальну сторінку EasyPay
transactionId	номер транзакції в EasyPay

2DSecure case:

Параметр	Характеристика
paymentState	"Confirmed" та "status": "Done" - платіж пройшов успішно. При інших значеннях необхідно перевірити статус платежу (Перевірка статусу платежу)
status	"Done" -платіж завершено, додаткові дії не потрібні. При "paymentState": "Confirmed" - означає, що транзакція на стороні EasyPay прийнята (http - оповіщення успішно доставлено партнеру)
transactionId	номер транзакції до EasyPay

Підтвердження платежу клієнтом. Введення смс. Проходження 3DS перевірки

---

У випадку "actionType": "ConfirmCode", клієнту прийде код підтвердження, який потрібно передати до EasyPay

POST /api/payment/confirmCodeVerification

Request

headers

"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "code": "string"
}

Response

headers 
відсутній

body
{  }

Якщо "status":"Need3Ds", то клієнту потрібно пройти 3DS перевірку в залежності від значення "actionType".

Опис параметрів:

Параметр	Характеристика
FormRedirect	необхідно СТВОРИТИ  сторінку (форму) з html-коду, який передано у параметрі
actionContent	"<html>...</html>", відкрити її клієнту для проходження ним 3D-secure перевірки. Альтернативним варіантом є переадресація клієнта за посиланням параметра "alternativeRedirectUrl"
UrlRedirect	необхідно переадресувати клієнта на посилання з "action" або переадресувати клієнта за посиланням з "alternativeRedirectUrl". Відобразиться форма банку емітента картки для перевірки 3D Secure. Після введення коду клієнта переадресує на сторінку успіху чи помилки. Адреси сторінок передаються на етапі створення замовлення. "urls": {    "success": "string",    "failed": "string" }

Перевірка статусу платежу

---

POST /api/merchant/orderState

Request

headers:
"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
   "serviceKey":"MERCHANT-TEST",
   "orderId":"test_20240524-0015",
   "transactionId":"1413668587"
}

Response

headers:
відсутній 

body:
"merchantKey":"easypay-test",
  "transactionId":1413668587,
  "orderId":"test_20240524-0015",
  "amount":3.000000,
  "paymentState":"declined",
  "refundTransactionId":1413673292,
  "":
  "paymentsList":[
    
  ],
  "refunds":[
    {
      "refundTransactionId":1413669380,
      "paymentState":"accepted",
      "refundAmount":1.10,
      "dateAccepted":"2024-05-24T16:14:45+03:00",
      "dateDeclined":null,
      "datePost":"2024-05-24T16:14:39+03:00"
    },
    {
      "refundTransactionId":1413673292,
      "paymentState":"accepted",
      "refundAmount":1.90,
      "dateAccepted":"2024-05-24T16:19:40+03:00",
      "dateDeclined":null,
 "datePost":"2024-05-24T16:19:33+03:00"
    }
  ],
  "error":null
}

Опис параметрів

	Фінальний статус?	Значення/ подальші дії
accepted	так	платіж прийнято
declined	так	платіж відхилений
pending	ні	платіж знаходиться в обробці, необхідно повторити запит статусу пізніше
none	-	статус платежу не визначено, необхідно повторити запит статусу до отримання кінцевого статусу

Нетипові відповіді запит статусу:

• Якщо платіж не знайдено, прийде відповідь:

{
"error":{
"errorCode":"MERCHANT_ORDERID_NOT_FOUND",
"title":null,
"description":null,
"errorMessage":"MERCHANT_ORDERID_NOT_FOUND",
"fieldErrors":[   ]
}

• Якщо платіж (сторінка, замовлення) не були відкриті клієнтом або не було спроби оплати, прийде відповідь:

{
"merchantKey": "easypay-test",
"transactionId": 0,
"orderId": "Some orderId2",
"amount": 0,
"paymentState": "pending",
"refundTransactionId": null,
"paymentsList": [],
"error": null
}

• Якщо отримано помилку на замовлення на етапі визначення реквізитів:

{
  "merchantKey": "easypay-test",
  "transactionId": 0,
  "orderId": "Some orderId",
  "amount": 0,
  "paymentState": "declined",
  "refundTransactionId": null,
  "paymentsList": [],
  "error": {
    "errorCode": "PROVIDER_ACCOUNT_INVALID", (ерор код може (має) відрізнятися від того, що в прикладі)
    "title": "Помилка системи",
    "description": "Акаунт не знайдено",
    "errorMessage": "string"
  }
}

При виконанні запиту статусу на замовлення, у яких є спліт (платіжна опція) - повертається наступна модель:

Request:

headers:

"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
   "serviceKey":"easypay-test",
   "orderId":"full_split_11",
   "transactionId":""
}

Response

headers
відсутній

body
{
    "merchantKey": "easypay-test",
    "transactionId": 991379504,
    "orderId": "full_split_11",
    "amount": 3.150000,
    "paymentState": "accepted",
    "refundTransactionId": null,
    "paymentsList": [
        {
            "merchantKey": "easypay-test",
            "transactionId": 991379509,
            "orderId": "full_split_11",
            "amount": 1.030000,
            "paymentState": "accepted",
            "refundTransactionId": null,
            "date": "2021-09-15T14:07:38+03:00",
            "error": null
        },
        {
            "merchantKey": "easypay-test",
            "transactionId": 991379508,
            "orderId": "full_split_11",
            "amount": 0.050000,
            "paymentState": "accepted",
            "refundTransactionId": null,
            "date": "2021-09-15T14:07:38+03:00",
            "error": null
        },
        {
            "merchantKey": "easypay-test",
            "transactionId": 991379507,
            "orderId": "full_split_11",
            "amount": 1.020000,
 "paymentState": "accepted",
            "refundTransactionId": null,
            "date": "2021-09-15T14:07:38+03:00",
            "error": null
        },
        {
            "merchantKey": "easypay-test",
            "transactionId": 991379506,
            "orderId": "full_split_11ID",
            "amount": 1.050000,
            "paymentState": "accepted",
            "refundTransactionId": null,
            "date": "2021-09-15T14:07:38+03:00",
            "error": null
        }
    ],
    "error": null
}

Опис параметрів

Параметр	Характеристика
paymentsList	список платежів у структурі спліту з деталізацією.

У випадку зі сплітованими платежами, в основному тілі відповіді OrderState - параметру transactionId присвоюється внутрішній технічний номер (нефінансової) операції.

"urls": {
   "success": "string",
   "failed": "string"
}

Скасування платежу

---

Метод викликається лише для платежів у статусі "accepted". Для успішного скасування має бути достатньо суми прийнятих платежів у день скасування. Можна скасовувати платежі, які не старші 30 днів. Успішне повернення після цього терміну – не гарантується, залежить від умов банків-еквайєрів.

Повернення суми на картку відбувається в строк 0-3 робочих дні, в окремих випадках – до 30 робочих днів. Це залежить від умов банку-еквайєра, через який пройшов основний платіж, а також банку-емітента.

Скасування звичайного платежу

---

POST /api/merchant/cancelOrder

Request

headers
"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "serviceKey": "MERCHANT-TEST",
  "orderId": "test_20210217-121843",
  "transactionId": "913141164",
  "amount":"1"
}

Response

headers
body
{
  "merchantKey":"easypay-test",
  "transactionId":913141164,
  "refundTransactionId":913141464,
  "orderId":"test_20210217-121843",
  "amount":1.000000,
  "paymentState":"accepted",
  "error":null
}

Опис параметрів

Параметр	Характеристика	Коментарій
amount	скасована сума	для часткового скасування - передається із сумою, яку потрібно скасувати. для скасування повної суми - параметр amount не передається
transactionId	оригінальна транзакція	магазину чи послуги передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
refundTransactionId	транзакція рефанду (скасування)	транзакція рефанду (скасування)
paymentState	статус транзакції рефанду (скасування). Можливі значення:	Можливі значення: accepted - скасування успішне. Створено транзакцію рефанду з негативною сумою declined - скасування пройшло неуспішно pending або будь-який інший статус – вимагає перевірки статусу основної транзакції перед повторним запитом скасування.

Якщо скасування пройшло успішно, запит статусу оригінальної транзакції повинен повертати "paymentState":"declined", а запит статусу транзакції скасування - "paymentState": "accepted"

При успішному скасуванні платежу, якщо налаштована HTTP - нотифікація (Повідомлення про платіж), на Merchant.UrlNotify буде одноразово надіслано POST - запит із параметром "action": "refund" та сумою (amount), яка була скасована. Нотифікація надсилається одноразово без повторних спроб, статус у відповідь код нами не перевіряється.

Скасування платежу (замовлення зі Splitting параметрами)

---

Скасування платежу (Замовлення) можна робити:

• на всю суму платежу (замовлення)
• на суму одного спліту (Часткова скасування платежу (замовлення))
• на суму меншу від суми спліту (Часткова скасування спліту)

Скасування повної суми платежу (замовлення зі Splitting параметрами)

---

• Для скасування повної суми Splitting транзакції необхідно виконати запит статусу транзакції згідно з розділом "Перевірка статусу платежу" використовуючи основний OrderID
• Отриманий у відповіді кореневий transactionID використовувати у запиті cancelOrder
• У відповідь на запит cancelOrder буде отримано відповідь зі статусом скасування, а також буде отримано коллбек по кожній транзакції, яка входила до Splitting транзакції.
• Коллбек на загальну суму Splitting транзакції не надходить.

POST /api/merchant/cancelOrder

Request

headers
"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "serviceKey": "easypay-test",
  "orderId": "full_split_11",
  "transactionId": 991379504,
}

Response

headers
відсутній 

body
{
  "merchantKey":"easypay-test",
  "transactionId": 991379504,
  "refundTransactionId":913141464,
  "orderId":"full_split_11",
  "amount":1.000000,
  "paymentState":"accepted",
  "error":null
}

Опис параметрів

Параметр	Характеристика	Коментарій
transactionId	номер транзакції, що скасовується, приходить при отриманні коллбека за оплаченим замовленням (параметр payment_id)
amount	сума, що скасовується: для часткового скасування - передається із сумою, яку потрібно скасувати.
transactionId	оригінальна транзакція, яка була відправлена ​​у запиті cancelOrder
refundTransactionId	транзакція рефанду (скасування)
amount	сума, яка була скасована
paymentState	статус транзакції рефанду (скасування)	Можливі значення: accepted - скасування успішне. Створено транзакцію рефанду з негативною сумою declined - скасування пройшло неуспішно Pending або будь-який інший статус – вимагає перевірки статусу основної транзакції перед повторним запитом скасування.

Якщо скасування пройшло успішно, запит статусу оригінальної транзакції повинен тепер повертати "paymentState":"declined" як для основної так і для окремих транзакцій, а запит статусу транзакції скасування - "paymentState":"accepted".

При успішному скасуванні платежу, якщо налаштована HTTP - нотифікація (див. Повідомлення про платіж), на Merchant.UrlNotify буде одноразово надіслано POST - запит із параметром "action": "refund" та сумою (amount), яка була скасована. Нотифікація надсилається одноразово без повторних спроб, статус у відповідь код нами не перевіряється.

Часткове скасування (повернення) платежу (замовлення зі Splitting параметрами)

Для часткового скасування платежу необхідно виконати запит cancelCurder використовуючи transactionID який був отриманий в коллбеку (параметр payment_id), а також вказавши суму скасування (вона має бути меншою або дорівнює сумі транзакції, що скасовується).

• У відповідь на запит cancelOrder буде отримано відповідь зі статусом скасування, а також буде отримано коллбек про успішне скасування цієї транзакції.

POST /api/merchant/cancelOrder

Request

headers

"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "serviceKey": "easypay-test",
  "orderId": "full_split_11",
  "transactionId": 991379509,
  "amount":1.00
}

Опис параметрів

Параметр	Характеристика	Коментарій
transactionId	номер транзакції, що скасовується, приходить при отриманні коллбека за оплаченим замовленням (параметр payment_id)
amount	сума, що скасовується: для часткового скасування - передається із сумою, яку потрібно скасувати.

Response

headers
відсутній

body
{
  "merchantKey":"easypay-test",
  "transactionId":"991379509",
  "refundTransactionId":"913141464",
  "orderId":"full_split_11",
  "amount":"1.000000",
  "paymentState":"accepted",
  "error":"null"
}

Опис параметрів

Параметр	Характеристика	Коментарій
transactionId	оригінальна транзакція, яка була відправлена ​​у запиті cancelOrder
refundTransactionId	транзакція рефанду (скасування)
amount	сума, яка була скасована
paymentState	транзакція рефанду (скасування)	accepted - скасування успішне. Створено транзакцію рефанду з негативною сумою declined - скасування пройшло неуспішно pending або будь-який інший статус – вимагає перевірки статусу основної транзакції перед повторним запитом скасування.

Якщо скасування пройшло успішно, запит статусу оригінальної транзакції повинен тепер повертати "paymentState":"declined", а запит статусу транзакції скасування - "paymentState":"accepted" При успішному скасуванні платежу, якщо налаштована HTTP - нотифікація (див. Повідомлення про платіж), на Merchant.UrlNotify буде одноразово надіслано POST - запит із параметром "action": "refund" та сумою (amount), яка була скасована. Нотифікація надсилається одноразово без повторних спроб, статус у відповідь код нами не перевіряється.

Повідомлення про платіж

---

1. Партнер обов'язково вибирає 1 або кілька способів сповіщення та повідомляє його в EasyPay. Партнер зазначає платіж успішним на своїй стороні лише після отримання цього повідомлення
2. Ми надсилаємо HTTP - колек з IP 93.183.196.26 методом POST з інформацією про платіж.
3. Запит надсилає EasyPay партнеру після того, як транзакція набула фінального статусу (Accepted, Declined).
4. URL для повідомлень (UrlNotify) партнер направляє у запиті createOrder у параметрі:

"order":{
"additionalItems":{
"Merchant.UrlNotify":"https://notify.url"
}
}

"Merchant.UrlNotify" Параметр не може бути порожнім і має відповідати формату URL.

⚠️ Важливо! Якщо у відповіді не отримано HTTP StatusCode 200, запит нотифікації буде надіслано повторно протягом 1-10 хвилин. Повторення може продовжуватися визначену кількість разів (за замовчуванням – 50 разів), поки не буде отримано статусу "200 ОК".

Request

headers

"Sign": "Bq2d0oaqVGMRWpX5wsGpOlpqLg42pBdDO7TfTPYVmnU="
body
{
  "OperationType": "Payment",
  "PartnerKey": "groshi-com", 
  "ServiceKey": "GROSHI-COM-GOOGLEPAY",
  "TransactionStatus": "Accepted",
  "MerchantOrderId": "3127194_28_450866",
  "DateTime": "2023-12-09T14:00:48",
  "Amount": 2059.08,
  "Commission": 28.83,
  "TransactionId": 1336448544,
  "AdditionalItems": {
    "Merchant.Inn": "3178404189",
    "Merchant.Details": ";0;0;;4;",
    "Merchant.UrlNotify": "https://testpartner.ua/callback",
    "Merchant.ClientFullName": "Іванов Дмитро"
    "Acquirer.MerchantId":"12345678"
    "Acquirer.TerminalId":"E1234567"
    "Card.BrandType":"Visa"
    "AuthCode":"012345"
   }
}

Опис параметрів

Параметр	Характеристика	Коментарій
OperationType	тип оповіщення	Можливі значення: payment - про успішний платіж (повторюється, якщо у відповідь не отримано статусу 200) refund - про успішне скасування платежу (відправляється разово)
PartnerKey	ІД партнера у системі EasyPay
ServiceKey	ІД сервісу партнера у системі EasyPay
TransactionStatus	статус платежу
MerchantOrderId	номер замовлення партнера із запиту createOrder
Acquirer.MerchantId	ідентифікатор торговця
Acquirer.TerminalId	ідентифікатор платіжного пристрою
Card.BrandType	найменування платіжної системи, платіжний інструмент якої використовується
AuthCode	Код авторизації
DateTime	час надання платежу статусу на стороні EasyPay	якщо партнер не відповість статусом 200 на запит з action:payment, то в наступному запиті час буде новим
TransactionId	ID транзакції на стороні EasyPay

Необхідно перевіряти підпис у нашому HTTP notify, налаштувати прийом лише для наших IP 93.183.196.26. Для правильного обчислення підпису, тіло з нотифай потрібно брати як є, без перетворень та форматувань. У випадку, якщо підпис notify не перевірено, всі фінансові ризики перекладаються на партнера.

Отримання інформації про рекурентний платіж

---

GET /api/merchant/reccurent/info

Request

headers

"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="
queryParams
"serviceKey": "string"
 "orderId": "string"
 "reccurentId":  "0"
 "dateFrom": 2025-03-10
 "dateTo": 2025-03-17
 "isEnabled": true|false
 "pageNumber": 1
 "countPerPage": 3

Response

headers

body
{
  "merchantReccurentPaymentDetails":[
    {
      "recurrentId":14433854,
      "orderDescription":"Easy payment",
      "serviceName":"Мерчант Тест UA",
      "serviceKey":"MERCHANT-TEST",
      "orderId":"test_20250312-153601+url",
      "amount":1.000000,
      "croneRule":"* 17 * * *",
      "dateCreate":"2025-03-12T16:38:02+02:00",
      "dateRun":"2025-03-13T17:00:00+02:00",
      "dateLastPayment":"2025-03-12T19:47:05+02:00",
      "isEnabled":true,
      "dateExpire":"2025-03-12T21:37:42+02:00",
      "properties":{
        "failedCount":"1",
"urlNotify":"http://109.251.205.8:9987/merch/notifysigncheckexample.php"
      }
    },
    {
      "recurrentId":14433852,
      "orderDescription":"Easy payment",
      "serviceName":"Мерчант Тест UA",
      "serviceKey":"MERCHANT-TEST",
      "orderId":"test_20250312-153601",
      "amount":1.000000,
      "croneRule":"* 17 * * *",
      "dateCreate":"2025-03-12T16:37:25+02:00",
      "dateRun":"2025-03-13T17:00:00+02:00",
      "dateLastPayment":"2025-03-12T19:47:05+02:00",
      "isEnabled":true,
      "dateExpire":"2025-03-12T21:37:03+02:00",
      "properties":{
        "failedCount":"1"
      }
    }
  ],
  "totalCount":2,
  "totalFilteredCount":2,
  "pageFilteredCount":2,
  "currentPageNumber":1,
  "numberOfPages":1,
  "error":null
}

Параметр	Характеристика
serviceKey	ІД сервісу партнера у системі EasyPay
orderId	номер замовлення партнера із запиту createOrder
reccurentId	номер рекурента
dateFrom	дата створення рекурента з..
dateTo	дата створення рекурента по..
isEnabled	відобразити лише активні / або неактивні рекуренти
pageNumber	відобразити сторінку номер..
countPerPage	кількість записів на сторінці
templateId	номер рекуренту (reccurentId)

Виклик рекурентного платежу

---

POST /api/merchant/reccurent/payment

Request

headers

"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "reccurentId": 0,
  "amount": 0
}

Response

headers

body
{
  "reccurentId": 0,
  "transactionId": 0,
  "transactionStatus": "None",
  "error": {
    "errorCode": "string",
    "title": "string",
    "description": "string",
    "errorMessage": "string",
    "fieldErrors": [
      {
        "fieldName": "string",
        "errorCode": "string",
        "errorMessage": "string"
      }
    ]
  }
}

Також буде надіслано нотифікацію у разі успішного платежу. Створення рекурентного платежу на операцію, у структурі якої є спліт – не підтримується.

Видалення рекурентного платежу

---

DELETE /api/merchant/reccurent/delete/{id}

Request

headers

"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
відсутній

Response

headers

- 

body

-

Робота з токенізованими картами

---

Токенізація карти

Метод призначений для токенізації (збереження) картки для ідентифікатора користувача під конкретним торговцем.

Токенізація з передачею даних картки у запиті (заборонено без PCI:DSS сертифікації мерчанта)

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

- CreateApp

- CreatePage

POST /api/merchant/tokenCard

Request

headers

"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "phone": "380501002030ws",
  "pan": "4874120123567889",
  "expire": "1222",
  "cvv": "012",
  "vсode": "123654"
}

Response

headers
відсутній

body
{
  "activateCodeType": "code|amount",
  "cardGuid: "55F5118B-B695-43BA-8555-AF8B698C4D2C",
  "pan”: "48741201****1234",
  "expire”: "1222" 
  "error": "null"
}

Токенізація картки - процес двоетапний.

На першому етапі у запиті йдуть параметри картки та номер телефону користувача. У відповіді, залежно від activateCodeType, може бути активація за кодом підтвердження з виписки або SMS або за сумою списання.

З другого краю етапі до всіх параметрів додається ще vcode – код верифікації. При успішному відповіді прийдуть параметри токенізованої карти чи помилка.

Токенізація за допомогою введення даних картки користувачем на сторінці (сертифікація PCI:DSS не потрібна)

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

- CreateApp;

- CreatePage;

POST api/merchant/tokenCard/create

Request

headers 
"Content-Type: application/json"
"PartnerKey: partnerName"
"locale: ua"
"AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
  "phone": "8888",
  "expire": "2020-12-06T12:54:32.043Z",
  "urls": {
    "success": "https://test.ua",
    "failed": "https://test1.ua",
    "notify": "https://test2.ua",
    "back": "https://test3.ua"
  },
  "description": "testtts",
  "checkExistingToken": false
  "operationType":"SingleToken | createToken | ExistingToken"
}

Response

headers

body
{
"forwardUrl": "https://easypay.ua/ua/tokencard/cae16afc-be56-4a39-8ce1-5de4f4142e76",
"error": null
}

Параметр	Характеристика	Коментарій
description	опис, який відобразиться на сторінці токенізації
expire	час життя сторінки токенізації (по дефолту - 15 хвилин)
phone	ідентифікатор клієнта, під яким збережеться картка (будь-які літери, цифри, GUID.	Не повинен містити символ ‘+’
urls	містить інформацію про: сторінці успіху партнера (success) для переадресації клієнта після успішної токенізації, потрібно обов'язково передавати сторінці помилки (failed) для переадресації клієнта у разі помилки адреса для відправки callback-запиту з деталями при успішній токенізації (notify) адресу для повернення назад зі сторінки токенізації (back)
forwardUrl	сторінка для додавання картки (токенізації)
checkExistingToken	перевірка наявності токена по карті, що вводиться у даного партнера.	Параметр може набувати значення: true - проводити валідацію на наявність раніше створеного токена по цій карті; false - валідація відсутня; null - валідація відсутня; Якщо параметру checkExistingToken присвоєно значення true, слід очікувати наступних сценаріїв поведінки: “checkExistingToken” : true, і в системі немає раніше створених токенів під зазначену карту під даним партнером (partnerKey) - формується запит на верифікацію введених даних картки (надсилання коду верифікації). За результатом успішної верифікації – створюється токен. При неуспішній верифікації – токен не створюється. У callback пишуться дані щодо створеного токену; “checkExistingToken” : true, і в системі є раніше створені токени під зазначену карту під даним партнером (partnerKey) - користувачу відкривається сторінка успіху, додаткова верифікація (надсилання коду верифікації не відбувається), токен не створюється, а в callback вказується масив раніше створених токенів; “checkExistingToken” : false / null, ​​і в системі немає раніше створених токенів під зазначену карту під даним партнером (partnerKey) - формується запит на верифікацію введених даних картки (надсилання коду верифікації). За результатом успішної верифікації – створюється токен. При неуспішній верифікації – токен не створюється. У callback пишуться дані щодо створеного токену; “checkExistingToken” : false / null, ​​і в системі є раніше створені токени під зазначену карту під даним партнером (partnerKey) – формується запит на верифікацію введених даних картки (надсилання коду верифікації). За результатом успішної верифікації – створюється токен. При неуспішній верифікації – токен не створюється. У callback пишуться дані щодо створеного токену.
operationType	(Новий параметр) задає тип операції токенізації	SingleToken - для однієї карти завжди повертається той самий токен. Логіка така: перевіряємо чи є токен для цієї картки під partnerKey із запиту якщо є 1 або більше токенів - беремо останній з них, створюємо новий запис з цим токеном для переданого ідентифікатора клієнта (phone), відправляємо цей токен в callback у кореневому параметрі cardGuid якщо токенів немає - створюємо новий для цього phone і відправляємо його в callback в кореневому параметрі cardGuid (один і той же cardGuid може бути прив'язаний до різних phone) createToken - значення за замовчуванням, звичайне створення токена (можна не передавати) ExistingToken - поведінка аналогічна checkExistingToken:true

На сторінці токенізації можемо керувати інтерфейсом (на стороні EasyPay):

• відображати/сховати логотип EasyPay
• відображати/приховати логотип та назву партнера
• відображати/приховати опис з деталями токенізації
• відображати опис у згорнутому/розгорнутому вигляді

Приклад callback - запит з IP адреси 93.183.196.26 після успішної токенізації:

Request

headers

Sign : AStbusXxzYdr48vssdr4/VXZCITrad8vr1A/tWhCBP8=

body
{ 
   "partnerKey":"partnerName",
   "phone":"test989",
   "cardGuid":"2ad57b2e-eb5b-4a99-ad05-788cf589b8af",
   "pan":"44411122****3558",
   "expire":"0524",
   "datePost":"2021-02-24T17:32:07.447",
   "codeType":"Mpi3Ds"
}

Параметр	Характеристика
phone	ідентифікатор клієнта, під яким збережено картку
cardGuid	токен збереженої карти
pan	маскований номер картки
expire	термін дії карти
datePost	час додавання картки
codeType	ознака типу верифікації картки. Mpi3Ds – з використанням 3ds.

Приклад callback - запит з IP адреси 93.183.196.26 з параметром ExistingToken:

Request

headers
Sign : AStbusXxzYdr48vssdr4/VXZCITrad8vr1A/tWhCBP8=

body
{
   "partnerKey":"easypay-test",
   "phone":"380509899549",
   "cardGuid":null,
   "pan":"44411122****3558",
   "expire":"0524",
   "datePost":"2021-05-18T18:41:53.152",
   "codeType":"Code",
   "existingTokens":[
      {
         "partnerKey":"easypay-test",
         "phone":"380509899549",
         "cardGuid":"bac4f855-xxxx-xxxx-bece-14cdf23c6c52",
         "pan":"44411122****3558",
         "expire":"0524",
         "datePost":"2021-05-18T18:28:23.840",
         "codeType":"Mpi3Ds"
      },
      {
         "partnerKey":"easypay-test",
         "phone":"380509899549",
         "cardGuid":"6338e8b4-xxxx-xxxx-a3e5-f46ad0cb0efa",
         "pan":"44411123****3558",
         "expire":"0524",
         "datePost":"2021-05-18T18:34:25.733",
         "codeType":"Mpi3Ds"
  },
      {
         "partnerKey":"easypay-test",
         "phone":"380509899549",
         "cardGuid":"18e3c35e-xxxx-xxxx-ba59-9506154394c0",
         "pan":"44411123****3558",
         "expire":"0524",
         "datePost":"2021-05-18T18:39:42.010",
         "codeType":"Mpi3Ds"
      }
   ]
}

Параметр	Характеристика
existingTokens	масив з даними раніше створених токенів по цій карті під даного партнера (partnerKey)

Отримання списку токенізованих карт

---

Метод призначений для отримання списку токенізованих карток за номером телефону (ознакою) користувача.

GET /api/merchant/tokenCards/get

Request

headers 

'PartnerKey: partnerName' 
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'TimeStamp: 1554360173'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='

queryparams
phone = string 
cardGuid= Guid

Response

headers 
відсутній

body
{
  "tokenCards": [
  {
     "cardGuid": "55F5118B-B695-43BA-8555-AF8B698C4D2C",
     "pan": "48741234****1234",
     "expire”: "1222"
   }],
  "error": "null"
}

Якщо передати тільки ідентифікатор клієнта (параметр phone) - у відповіді будуть всі карти поточного клієнта. Якщо передати phone та cardGuid - у відповіді буде одна карта поточного клієнта.

Видалення токенізованих карт

---

Метод призначений для видалення токенізованих карток за номером телефону. Якщо у клієнта під одним номером кілька карток, всі картки будуть видалені.

DELETE /api/merchant/tokenCards/delete/phone

DELETE /api/merchant/tokenCards/delete/phone?CardGuid=Guid

Request

headers

'PartnerKey: partnerName' 
'locale: ua'
'AppId: a5806a5f-dbb8-496a-a23f-aab6d2fcbce1'
'PageId: 2ce7dba6-4600-456e-b9c8-f13cacf1c85d'
'TimeStamp: 1554360173'
'Sign: e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4='

queryparams

cardGuid= Guid

Response

headers 
відсутній 

body 
відсутній

Видача кредиту (переказ на картку користувача)

Метод призначений для переказу на картку користувача суми кредиту.

POST /api/merchant/createOrder

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

• CreateAPP
• CreatePage

Request:

headers

"Content-Type": "application/json"
"PartnerKey": "partnerName"
"locale": "ua"
"AppId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1"
"PageId": "2ce7dba6-4600-456e-b9c8-f13cacf1c85d"
"Sign": "e0v1vIOMyNt2qSmrG5+sjAq8wOhvgDDUEyfVP21mRU4="

body
{
   "order":{
  	"serviceKey":"CARD-FILL",
  	"description":"test top up card",
  	"amount":1.12, (decimal)
  	"orderId":"test",
  	"fields":[
     	{
        	"fieldName":"Pan",
        	"fieldValue":"4102321200001111",
        	"fieldKey":"b95d541a-c11f-49bc-9042-295dbf74ccn6"
     	},
     	{
        	"fieldName":"Phone",
        	"fieldValue":"38093520000"
     	}
  	],
     	"additionalItems": {
	      "Merchant.ClientFullName": "Иванов Петр Сергеевич",
                     "Merchant.Address": "04080, Київ, вул.Межигірська 82а корп.Б, кв.32",
                    "Merchant.Inn": "3334445823"
        }
   },
   "userPaymentInstrument":{
  	"instrumentType":"Vcash"
   }
}

Response

headers
відсутній 

body 
{
	"redirectUrl": null,
	"action": null,
	"paymentState": "Confirmed",
	"status": "Done",
	"actionType": "UrlRedirect",
	"transactionId": "766934634",
	"retrievalReferenceNo": "null",
	"responseItems": "null",
	"error": "null"
}

Опис параметрів

Параметр	Характеристика	Коментарій
paymentState	Confirmed оплата пройшла успішно WaitConfirm  очікується підтвердження платежу Rejected і Refunded платіж відхинело
transactionId	ідентифікатор платежу в системі Easypay	У об'єкти поля передається інформація для поповнення карти. Номер картки можна вказувати: для випадку з PCI DSS сертифікацією: у відкритому вигляді "fieldName":"Pan", "fieldValue":"4102321200001111", для випадку без PCI DSS сертифікації: у вигляді токена (як отримати токен картки - див. Токенізація карти): "fieldName":"Pan", "fieldKey":"b95d541a-c11f-49bc-9042-295dbf74ccn6" Також потрібно вказати: - номер телефону клієнта: "fieldName":"Phone", "fieldValue":"38093520000" - ПІБ та адреса клієнта АБО ПІБ та ІПН клієнта: "additionalItems": {       "Merchant.ClientFullName": "Іванов Петро Сергійович"                   "Merchant.Address": "04080, Київ, вул.Межигірська 82а корп.Б, кв.32"       "Merchant.Inn": "3334445862"         }

Статус видачі кредиту:

• Якщо у відповіді отримано кінцевий статус (paymentState = Confirmed / Rejected / Refunded) - необхідно присвоїти його платежу.
• Якщо кінцевий статус у відповіді не отримано (paymentState = WaitConfirm), у тому числі при серверних, мережевих та будь-яких інших відповідях та помилках - необхідно запросити статус платежу методом orderState (Перевірка статусу платежу) до отримання кінцевого статусу.

Важливо врахувати, що нотифікація про оплату не надсилається (якщо партнер/мерчант не повідомив про необхідність такого налаштування).

Скасування транзакції не передбачено.

Response (Приклади відповідей при помилках: status code = 400)

{
    "error": {
        "errorCode": "MERCHANT_CREATEORDER_VALIDATION_EXCEPTION",
        "title": null,
        "description": null,
        "errorMessage": "MERCHANT_CREATEORDER_VALIDATION_EXCEPTION",
        "fieldErrors": [
            {
                "fieldName": "Order.Fields[0]",
                "errorCode": "SERVICE_FIELDS_VALIDATION_EXCEPTION",
                "errorMessage": "Вказана умова не була виконана для значення поля."
            }
        ]
    }
}


{
    "error": {
        "errorCode": "PAYMENT_ALFABANK_CASH2CARD_C2Pv2",
        "title": "Платіжна помилка",
        "description": "Платіжна помилка",
        "errorMessage": "Обслуговуються тільки карти емітовані українськими банками",
        "fieldErrors": []
    }
}


{
    "error": {
        "errorCode": "PAYMENT_ALFABANK_CASH2CARD_C2Pa8",
        "title": "Платіжна помилка",
        "description": "Платіжна помилка",
        "errorMessage": "Необхідно уточнити реквізити картки одержувача у банку емітента",
        "fieldErrors": []
    }
}

Нотифікації (колбеки) щодо операцій поповнення карток

Дані колбеки є опціональним (додатковим) способом отримання інформації від EasyPay про результат виконання запиту на поповнення картки.

Для активації отримання колбеків мерчант (партнер) повинен повідомити EasyPay про таку необхідність, після чого EasyPay включає цю опцію.

Спосіб відправки колбека - HTTP - з IP 93.183.196.26 буде надіслано POST запит з інформацією про платіж на вказаний urlNotify.

urlNotify прописується на стороні EasyPay і використовується за замовчуванням, якщо партнер не передав його у своєму запиті.

URL для повідомлень (UrlNotify) повідомляє партнер (мерчант).

Партнер може передавати UrlNotify у запиті createOrder у параметрі:

"order":{

"additionalItems":{

"Merchant.UrlNotify":"https://notify.url"

}

}

"Merchant.UrlNotify" параметр не може бути порожнім і повинен відповідати формату URL.

Якщо у відповідь не отримано HTTP StatusCode 200 - запит нотифі буде надіслано повторно, доки не отримано статусу “200 ОК”.

Коли нотифікацію (колбек) успішно доставлено (отримано статус 200 ОК), повторне відправлення колбеків припиняється.

Відправлення колбеків можливе за двома сценаріями:

1) лише за успішними операціями (транзакціями);

2) за операціями (транзакціями) у фінальному статусі (успішні та відхилені).

Надання фінального статусу операції (транзакції) асинхронно з процесом відправки колбека (фінансова транзакція набуває фінального статусу незалежно від статусу прийняття колбека партнером).

Request

headers 

"Sign: "Bq2d0oaqVGMRWpX5wsGpOlpqLg42pBdDO7TfTPYVmnU="
"User-Agent": "EasyPay.MerchantNotifyService"

body

{
  "action": "payment",
  "merchant_id": 5347,
  "order_id": "5",
  "date": "2019-06-19T15:38:10.7802613+03:00",
  "details": {
    "amount": 1.00,
    "desc": "Wooden tables x 10",
    "payment_id": 724502946,
    "recurrent_id": null
  },
  "additionalitems": {
    "BankName": "CB PRIVATBANK",
    "Card.Pan": "414962******1234",
  }
}

Опис параметрів

Параметр	Характеристика	Коментарій
action	тип оповіщення	payment - про успішний платіж (повторюється, якщо у відповідь не отримано статусу 200)
merchant_id	номер сервісу партнера на стороні EasyPay;
order_id	номер замовлення партнера із запиту createOrder;
date	час надання платежу статусу на стороні EasyPay;	необов'язковий параметр (потрібно вказати, якщо потрібно замінити картку Одержувача)
details	детальна інформація про платіжну операцію (транзакцію)	payment_id - ID детальна інформація про платіжну операцію (транзакцію): amount - сума фінансової операції; desc - опис замовлення, отриманий під час запиту CreateOrder; recurrent_id - ознака реккурентного платежу (завжди за замовчуванням на операціях поповнення картки – null);
additionalitems	блок додаткових параметрів, до якого можуть включатися додаткові айтеми, отримані в запиті CreateOrder:	BankName - назва банку власника картки; Card.Pan - номер картки у маскованому вигляді.

Необхідно перевіряти підпис у нашому HTTP notify, налаштувати прийом лише для наших IP 93.183.196.26.

⚠️ Важливо! У випадку, якщо підпис notify не перевірено, всі фінансові ризики перекладаються на партнера.

Інтеграція з ApplePay

---

Вимоги

1. Ваш сайт повинен працювати за схемою HTTPS та підтримувати протокол TLS 1.2.
2. Потрібно погодитись з умовами надання послуг Apple Pay.
3. Необхідно укласти договір із Easypay.ua.

Apple Pay надає простий та безпечний спосіб проведення платежів у додатках iOS, watchOS та сайтах Safari. Використовуючи Face ID, Touch ID або двічі клацнувши Apple Watch, користувачі можуть швидко та безпечно передавати свої платіжні дані для оплати.

Оплата з платіжної сторінки Easypay

---

При такому способі підключення немає потреби у додаткових інтеграціях. Кнопка Apple Pay буде відображена на сторінці оплати EasyPay

Оплата ApplePay з додатку

---

Вимоги:

1. Необхідно мати акаунт у Apple Developer, в який потрібно зареєструвати індивідуальний Merchant ID.
2. Необхідно дотримуватися вимоги до брендування.

Реєстрація та перевірка в системі Apple Pay

1. Зареєструйте MerchantID та надішліть до EasyPay:
   1. Увійдіть до свого облікового запису Apple Developer Account.
   2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
   3. У розділі "Identifiers" виберіть "Merchant IDs".
   4. Додайте новий Merchant ID, натиснувши на "+" у верхньому правому куті екрана.
   5. Заповніть поля * і натисніть «Continue».
   6. Натисніть Register, щоб підтвердити введені дані.
   7. Повідомте EasyPay ваш MerchantID.

Примітка: * - Description – опис; Identifier – домен вашого сайту у зворотному порядку, з додаванням «merchant» на початку (наприклад, сайт shop.ua, Identifier – merchant.ua.shop).

1. Отримайте від EasyPay сформований CSR-файл, який буде необхідний для подальших кроків.
2. Сформуйте Apple Pay Payment Processing Certificate та надішліть до EasyPay:
   1. Увійдіть до свого облікового запису Apple Developer Account.
   2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
   3. У розділі "Identifiers" виберіть "Merchant IDs".
   4. Виберіть створений вами Merchant ID та натисніть «Edit».
   5. У розділі Apple Pay Payment Processing Certificate, натисніть "Create Certificate".
   6. На наступному екрані натисніть Continue.
   7. Візьміть отриманий від EasyPay CSR-файл і завантажте його на сайт, натиснувши Choose File, а потім Continue.
   8. Завантажте згенерований сертифікат.
   9. Надішліть сертифікат (файл apple_pay.cer) до EasyPay

Технічна інтеграція з ApplePay

1. Щоб інтегрувати Apple Pay у мобільний додаток, дотримуйтесь інструкцій за посиланням: https://developer.apple.com/documentation/passkit/apple_pay.

Приклад відповіді ApplePay

{
 "paymentData":
  {
    "version":"EC_v1",    "data":"FDXK/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ/dGK9UZDP/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp/clv4",    "signature":"UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkJvjg3qQ0QAAAAAAAA=",
    "header":
    {      "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==",
      "publicKeyHash":"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=",
      "transactionId":"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4"
    }
  },
  "paymentMethod":
  {
    "displayName":"MasterCard 5179",
    "network":"MasterCard",
    "type":"debit"
  },  "transactionIdentifier":"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4"
}

2. Надішліть paymentData в поле userPaymentInstrument / token в Easypay (Створення замовлення). Приклад запиту createOrder:

{
  "order":{
    "serviceKey":"MERCHANT-TEST",
    "orderId":"test_20210309-171148",
    "description":"Test payment",
    "amount":"1"
  },
  "userPaymentInstrument":{
    "instrumentType":"ApplePay",
    "token":"{\"paymentData\": {\"version\":\"EC_v1\",  \"data\":\"FDXK\/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8\/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV\/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ\/dGK9UZDP\/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp\/clv4\",  \"signature\":\"UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkJvjg3qQ0QAAAAAAAA=\",\"header\":{  \"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo\/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==\", \"publicKeyHash\":\"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=\",\"transactionId\":\"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4\"}  },  \"paymentMethod\":  {   \"displayName\":\"MasterCard 5179\",\"network\":\"MasterCard\",\"type\":\"debit\"  },  \"transactionIdentifier\":\"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4\"}",
    "gatewayMerchantId":"{ApplePayMerchantId}"
  }
}

Оплата із сайту

---

Вимоги:

1. Необхідно мати акаунт у Apple Developer, до якого потрібно зареєструвати індивідуальний Merchant ID.
2. Необхідно дотримуватися вимог до брендування.

Реєстрація та перевірка в системі Apple Pay

1. Зареєструйте MerchantID та надішліть до EasyPay:
   1. Увійдіть до свого облікового запису Apple Developer Account.
   2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
   3. У розділі "Identifiers" виберіть "Merchant IDs".
   4. Додайте новий Merchant ID, натиснувши на "+" у верхньому правому куті екрана.
   5. Заповніть поля * і натисніть «Continue».
   6. Натисніть Register, щоб підтвердити введені дані.
   7. Повідомте EasyPay ваш MerchantID.

Примітка: * - Description – опис; Identifier – домен вашого сайту у зворотному порядку, з додаванням «merchant» на початку (наприклад, сайт shop.ua, Identifier – merchant.ua.shop).

1. Отримайте від EasyPay сформований CSR-файл, який буде необхідний для подальших кроків.
2. Сформуйте Apple Pay Payment Processing Certificate та надішліть до EasyPay:
   1. Увійдіть до свого облікового запису Apple Developer Account.
   2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
   3. У розділі "Identifiers" виберіть "Merchant IDs".
   4. Виберіть створений вами Merchant ID та натисніть «Edit».
   5. У розділі Apple Pay Payment Processing Certificate, натисніть "Create Certificate".
   6. На наступному екрані натисніть Continue.
   7. Візьміть отриманий від EasyPay CSR-файл і завантажте його на сайт, натиснувши Choose File, а потім Continue.
   8. Завантажте згенерований сертифікат.
   9. Надішліть сертифікат (файл apple_pay.cer) до EasyPay
3. Зареєструйте та підтвердіть свій домен:
   1. Увійдіть до свого облікового запису Apple Developer Account.
   2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
   3. У розділі "Identifiers" виберіть "Merchant IDs".
   4. Виберіть створений вами Merchant ID та натисніть «Edit».
   5. У розділі "Merchant Domains" натисніть "Add Domain".
   6. Введіть ім'я домену та натисніть "Continue" *.
   7. Завантажте файл apple-developer-merchantid-domain-association.txt.
   8. Збережіть файл на сервері від Apple.
   9. Натисніть Verify.

Примітка: * - домен повинен підтримувати HTTPS.

1. Створіть Apple Pay Merchant Identity Certificate:
   1. Увійдіть до свого облікового запису Apple Developer Account.
   2. Перейдіть до розділу «Certificates, Identifiers & Profiles».
   3. У розділі "Identifiers" виберіть "Merchant IDs".
   4. Виберіть створений вами Merchant ID та натисніть «Edit».
   5. У розділі Apple Pay Merchant Identity Certificate натисніть Create Certificate.
   6. Виконайте дії, описані на сайті Apple, а потім натисніть «Continue».
   7. Скопіюйте згенерований CSR-файл, вибравши Choose File, а потім Continue.
   8. Завантажте згенерований сертифікат (merchant_id.cer) і відкрийте його у програмі Keychain Access на комп'ютері Mac.
   9. У Keychain Access виберіть сертифікат, що імпортується, та експортувати його у формат .p12 (Personal Information Exchange).
   10. Виконайте команду: openssl pkcs12 -in merchant_id.p12 -out merchant_id.pem -nodes -clcerts
   11. Скопіюйте створений сертифікат у форматі PEM на сервер. Це буде потрібно для створення Apple Pay Payment Session в процесі перевірки магазину.

Технічна інтеграція з ApplePay

Для створення сертифікату (-ів) від Партнера потрібні:

1. Country Name (2 letter code) [AU]: ?
2. State or Province Name (full name) [Some-State]: ?
3. Locality Name (eg, city) []: ?
4. Organization Name (eg, company) [Internet Widgits Pty Ltd]: ?
5. Organizational Unit Name (eg, section) []: ?
6. Common Name (e.g. server FQDN or YOUR name) []:?
7. Email Address []: ?

Повідомте, чи буде оплата тільки в додатку, або також і на WEB.

Щоб інтегрувати Apple Pay на сайт, дотримуйтесь інструкцій за посиланням

1. Перевірте можливість оплати з Apple Pay. Виконується перевірка, підтримує або браузер оплату з Apple Pay, а також є у Wallet картку, якою можна оплачувати.

if (window.ApplePaySession) {
    var promise = ApplePaySession.canMakePaymentsWithActiveCard({YOUR_MERCHANT_ID});
    promise.then(function(canMakePayments) {
        if (canMakePayments)
    });
} else {
}

2. Сформуйте структуру платежу для сесії

document.getElementById("apple-pay-button").onclick = function(event) {
    var paymentRequest = {
        currencyCode: 'UAH',
        countryCode: 'UA',
        total: {
            label: {PRODUCT_NAME},
            amount: {PAYMENT_AMOUNT}
        },
        merchantCapabilities: ['supports3DS'],
        supportedNetworks: ['masterCard', 'visa']
    };

var session = new ApplePaySession(3, paymentRequest)

3. Відкрити платіжну сесію з Apple, отримати від них paymentData:

POST /api/applePay/validateSession

headers 

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

body
{
  "url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
  "merchantIdentifier": "string", /ідентифікатор мерчанту в Apple/
  "displayName": "test", /ідентифікатор магазина/послуги/товару (латиниці) ; буде відображатися в toolBar/
  "initiative": "web", /Канал оплати/
  "initiativeContext": "string" /Доменне ім’я, Доменное имя, пов'язане із сертифікатом Apple Identity/
}

*response з цього методу передається в сесію Apple, після чого при успішній авторизації платежу, повернеться до необхідний для завершення платежу.

4. Приклад відповіді ApplePay

{
 "paymentData":
  {
    "version":"EC_v1",    "data":"FDXK/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ/dGK9UZDP/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp/clv4",    "signature":"UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB/wQEAwIBBjAQBgoqhkJvjg3qQ0QAAAAAAAA=",
    "header":
    {      "ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==",
      "publicKeyHash":"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=",
      "transactionId":"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4"
    }
  },
  "paymentMethod":
  {
    "displayName":"MasterCard 5179",
    "network":"MasterCard",
    "type":"debit"
  },  "transactionIdentifier":"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4"
}

5. Надішліть paymentData в поле userPaymentInstrument / token в Easypay (Створення замовлення). Перед цим потрібно викликати метод EasyPayApi CreateApp. Приклад запиту  createOrder:

{
  "order":{
    "serviceKey":"MERCHANT-TEST",
    "orderId":"test_20210309-171148",
    "description":"Test payment",
    "amount":"1"
  },
  "userPaymentInstrument":{
    "instrumentType":"ApplePay",
    "token":"{\"paymentData\": {\"version\":\"EC_v1\",  \"data\":\"FDXK\/fkIXGh07D5QU5eUK3ZK8BxKk6syu+Hf0DH6DBZ8\/loNHFWHULxsmfIAyaKzvkUjm2dHaR36pS4x8UXuQ3JhzeB7AfDmZsP8JcL16OOyZKZP3JjOwdkUVvzUyPWtjtlrtXDaBmJ5jPcT8bgnLZV\/7RcC9HpRkdmUqVyJ042wAvPNxF7SVt57PcMyMeccVL6yWUk6N2oV7ESFoGVbAeJdpn5zZT8lebigrnhZRhvwoJ5ZJ\/dGK9UZDP\/swhH8nMLjK620Wu9rvidhsSheJCwM2sCH27fKpeEO2x+vWaLlL9ukwDms9ciOGvSyb+tDvRD9MheecGri1XCC6DxQT5JkHDH7mi1vev0QFjjVY6bmh26iNC0lIB4FKVznNv03yjkKNJhEMbp\/clv4\",  \"signature\":\"UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkJvjg3qQ0QAAAAAAAA=\",\"header\":{  \"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXaMJN7PRXhkoMa1n1wOnut4KIkIX0WuyXenzRukdDUzo\/GZ+TRqTSPjZDOPoZkisqifaroXUJZP9xCUlJQ3iqQ==\", \"publicKeyHash\":\"48145ri0BI4zYNGguvfW+7qJc3kQlcGdil64a4cg+Ag=\",\"transactionId\":\"cd80b9fc31c9a850c14c697bd4c258aa51e63bf72bba46394eebbc3fae1b58e4\"}  },  \"paymentMethod\":  {   \"displayName\":\"MasterCard 5179\",\"network\":\"MasterCard\",\"type\":\"debit\"  },  \"transactionIdentifier\":\"CD80B9FC31C9A850C14C697BD4C258AA51E63BF72BBA46394EEBBC3FAE1B58E4\"}",
    "gatewayMerchantId":"{YOUR_MERCHANT_ID}"
  }
}

Інтеграція з GooglePay

---

Вимоги

1. Ваш сайт повинен працювати за схемою HTTPS та підтримувати протокол TLS 1.2.
2. Потрібно погодитися з умовами надання  послуг GooglePay.
3. Необхідно укласти договір із Easypay.ua.

Google Pay™  - це миттєвий спосіб оплати від Google, який дозволяє просто та швидко сплатити карткою, без необхідності вводити дані для кожного платежу. Ці картки надійно зберігаються в Google. Даний метод доступний для оплати в мобільних програмах на будь-яких пристроях Android і при здійсненні платежу в браузері Chrome.

• Документація

1. Для додатків
2. Для веб-сайтів

• Вимоги щодо брендування

1. Для додатків
2. Для веб-сайтів

Оплата з платіжної сторінки Easypay

---

При такому способі підключення немає потреби у додаткових інтеграціях. Кнопка GooglePay відображається на сторінці оплати EasyPay.

Отримання токена GooglePay для оплати

---

*Використовуйте бойове середовище GooglePay для отримання PaymentData

Для отримання PaymentData. Як параметри скрипта вкажіть:

1. Доступні методи платежу: var allowedPaymentMethods = ['CARD', 'TOKENIZED_CARD'];
2. Тип токенізації- PAYMENT_GATEWAY: tokenizationType: 'PAYMENT_GATEWAY';
3. Параметр gateway: easypay;
4. Параметр gatewayMerchantId: Ваш бойовий merchantAccount от Google, який повідомляє в EasyPay.

Якщо з вашого боку інтеграція виконана правильно, Ви на своєму сайті/додатку отримаєте кнопку

Після натискання кнопки на пристрої з підключеним Google Pay з'явиться спливаюче вікно або форма вибору прив'язаної картки.

Приклад відповіді від GooglePay Api

{
    "apiVersionMinor":0,
    "apiVersion":2,
    "paymentMethodData":{
        "description":"Mastercard  •••• 1164",
        "tokenizationData":{
            "type":"PAYMENT_GATEWAY",
"token":"{"signature":"MEUCeretMPEQPUMnvMOnDAgZsOLVnFnfjmo5ALe/1D6o7hdzAiEA94L1GfNWW84kbUdHHn+l6B6n18VgIA3sdkPqKL36tqk\u003d","intermediateSigningKey":{"signedKey":"{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEem3biYxltOBuMV+Dd9g+ZhV3VEzP2vAlFXvb9tJoYGLtetxDYWTUqnXPvKGDeAnSNrkPo8hu5kLtxN0QXCYkqQ\\u003d\\u003d\",\"keyExpiration\":\"1551385212256\"}","signatures":["MEYCIQD/TWKunZJhG/u3iL2H5P3i9r0rCbpw1/+z9dr/yGytvwIhAPfV2zF5cqP/L+42W+JKv6fgQKBEc67HTtfderefdghJ"]},"protocolVersion":"ECv2","signedMessage":"{\"encryptedMessage\":\"OidSptk8w+I3FnR1VFmiVswXaZ7ADnmMP1MQelp6GSg0/3aVpAXeLRH/fT1wN7gpxNPy7tFITeQenrJm3QG19tAPuVhcAVM26DMU6LAmZPyPXALktpnYrUj6etCjvWWM/1LkhjDBSjtkmpWRiHIyqj5aud/j8rxFEk06GhwqPWbnJwdCgNf32LJP7bSpUWvHOioaZIV1vdeV6d7iQ6EDWWAS/z9pXWkqpW//M/TVTrcKFXh4C2TI2O+qyBD9VzK3TqU6wS5VsYL69W9/4xzV5L5irpp/wzNfPHkJd8QIwcsIPuNWBtGm3v+JCaqIA3oK9Sw/5o/gZp/pnOhUdax0VjGEvmbGXs2+ufBChCkh+/BpobbpzVS9T/DZSlUO2FLANMjSaEQzh74ymtDgP4x9O64RAdySW+V7lVZMa7FVZ3PFnTfa8W89pzIgo6ocSGHQPBFnExTmSbDpUU0L12wzHkAcZSyngPAljqg\\u003d\",\"ephemeralPublicKey\":\"BBKgbSbykNy1111QYRmGJEhnCorkt+VoDYlYbAlg0a5WO2uV/M50XqOSG0uxWAvUqrZolQuEX6yZ+dvvufLEZtI\\u003d\",\"tag\":\"p9ItvOfsQVTzhTPHq6ycYjKX1TtozP/yym4QWWVRVCk\\u003d\"}"}"
        },
        "type":"CARD",
        "info":{
            "cardNetwork":"MASTERCARD",
            "cardDetails":"1164",
            "billingAddress":{
                "phoneNumber":"+380 93 000 00 11",
                "address3":"",
                "sortingCode":"",
                "address2":"",
                "countryCode":"UA",
                "address1":"ул. ",
                "postalCode":"49107",
                "name":"Super 1",
                "locality":"Київ",
                "administrativeArea":"Київська область"
            }
        }
    },
    "email":"test@easypay.ua"
}

Передача токена для оплати

Надішліть дані з поля token з відповіді від GooglePay Api у поле userPaymentInstrument/token у Easypay (розділ Створення замовлення)

Перед цим потрібно викликати метод EasyPayApi createApp.

Приклад запиту

POST /api/merchant/createOrder

{
  "order":{
    "serviceKey":"MERCHANT-TEST",
    "orderId":"test_20210000-171148",
    "description":"Test payment",
    "amount":"1"
  },
  "userPaymentInstrument":{
    "instrumentType":"GooglePay",
"token":"{\"signature\":\"MEQCIFTFadYw15Cqfk7+YiM9pp5zEvyTI7oWVZCNFKr1cMthAiAFMv+nt0PWOEhj6LmmMNTByP9E4OhGrSoE7rDvzLDIZw\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEsrkMsOBN8N0xL8AsTVUIETODhCva5PpGFxvPm56pWmI5MG2HKKHXjsdhdvcP6N3d40x90E0rZzDrxBC2ywERXg\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1618591579000\\\"}\",\"signatures\":[\"MEUCIHX0SawuKctPUEjdFu2sDiE81aSSdf8i0KNvdg1dlsWoAiEAye8TEWpPk4sp7EjTovN7DichK6YxY1DajYN9/ArHDYI\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"vlLmhIBndM4a/GWFsvbFZrZOygjAwUao/NlvlJlhAQ3kdprI3gubAcQxAau8L74dkzGJh8w7AD2E77XOHycdwG91NUvsJ0xiXuMCXHJ9NPMhp7k49OUIJjOpJG+RqUM9/SPBgx69eDD7skhG+axZYr/m36LFjIlk5WhmumQgIrfojm02uRm0nOcZ2wbvrwQKZyL1IeTv/txqcYMuQqYWzs/FPkIEbiQ80z6dRhVszrEXcHLKcfBmNmcn/Vk90ArXCotOD52V0JS/Q+Mf9mCoe9G2bABo9R9PAYT/FrKIEOQEhzLCI7m4/vyIlCMf69d6PjigP3AOGxykbS0Kvsxqoh+HYRFCSLCd+8O2Us2wCYD09/OBqcQi78/fs2vwyg4nrWQQJ6ZGwTKHHxVRY8VGAUUnMFr18HPsN1BQNuz08M4t6Qx6X0nEZ3hseSIcUMVcBm+NyvL2T/XSWqTh2poDuQ4B+UJ59gMrsPapzouxk2iC/+vS1Bs/2sSf77Nsqr7BhE7SMgnZ/a2LF+Shx2aOKSIGflMz+MjVSzpMg2AUh43pbcsi8g\\\\u003d\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BDJpYzoN9XPVKrHIxwNes83HbR0/AOUPpQgAwi3fTzR+TIB8/VAc9CdI9guWX8Pjvii/T+WxwcByuo9pzJC7518\\\\u003d\\\",\\\"tag\\\":\\\"LFOOTwd5Crtn60KnT0J6MHuFlGE0+EYL3D7IrWrPsRA\\\\u003d\\\"}\"}",
  }
}

Створення підпису

---

Формування підпису Sign (основний варіант для POST – запитів)

Sign = base64(sha256(secretKey + requestBody))

Де:

• secretKey – секретний ключ.
• requestBody – тіло запиту у форматі JSON (ідентичне формату EasyPay).

Приклади коду

---

C#

Convert.ToBase64String(SHA256.Create().ComputeHash(Encoding.UTF8.GetBytes(data)))

PHP

base64_encode(hash('sha256', ($secretKey.$requestbody), true))

Можливі варіанти інструментів оплати

---

Оплата 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="
                    }
               }
           ]
       }
   ]

Управління інструментами оплати

---

Управління інструментами оплати на сторінці оплати EasyPay здійснюється при створенні замовлення. Параметр allowedInstruments визначає, які інструменти оплати будуть відображатися на сторінці платіжного шлюзу.

 "userInfo": { 
      "phone": "string"
   },

Обов'язкові параметри:
    "order": {
      "serviceKey": "string",
      "orderId": "string",
      "description": "string",
      "amount":1.01, (decimal)
"allowedInstruments": [ "string" ]

Опис параметрів

Параметр	Характеристика	Коментарій
allowedInstruments	параметр в якому передаються інструменти оплати, які будуть відображені на сторінці	Можливі значення: RCard Card EBank FishkaB2C ApplePay GooglePay

Поведінка системи

1. Якщо параметр allowedInstruments не передано або він порожній: На сторінці оплати будуть відображені всі доступні інструменти, які підключені для партнера.
2. Якщо з переданих інструментів немає доступних для оплати: Повертається помилка: PAYMENTINSTRUMENT_NOT_FOUND
3. Приклад помилки: У разі, якщо у партнера активні ApplePay і Card, а в запиті передається GooglePay, повертається помилка PAYMENTINSTRUMENT_NOT_FOUND.
4. Якщо передані доступні інструменти оплати: У разі, якщо партнер передає, наприклад, GooglePay та Card, але GooglePay не активний для цього партнера, система поверне посилання з активним інструментом Card.

Технічна підтримка

---

За потреби консультацій з питань реалізації API можна написати запит на [email protected]