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

Версія за 15:23, 30 серпня 2024

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

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

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

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

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

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

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

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

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

--header 'PartnerKey: easypay-test'

--header 'locale: ua'

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

URLS

Production - https://merchantapi.easypay.ua

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

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

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

Параметр	Характеристика	Коментарій
`PartnerKey`	унікальний ідентифікатор партнера (продавця) у системі EasyPay.
`ServiceKey`	ідентифікатор сервісу торговця у системі EasyPay.	магазину чи послуги
`SecretKey`	секретний ключ для формування підпису	відомий лише торговцю та EasyPay
`AppId`	ідентифікатор торгової точки партнера	параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)
`PageId`	ідентифікатор сесії	параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID

Параметри PartnerKey, SeviceKey, SecretKey передаються партнеру після реєстрації у системі EasyPay відповідальним менеджером.

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

PartnerKey = easypay-test

ServiceKey = MERCHANT-TEST

SecretKey = test

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

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

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

<body>

POST /api/system/createApp

<body>

POST /api/system/createApp

<body>

POST /api/system/createApp

<body>

POST /api/system/createApp

<body>

POST /api/system/createApp

<body>

POST /api/system/createApp

<body>

POST /api/system/createApp

</body>

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

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

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

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

Техпідримка

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

Інтеграція з Apple Pay

Вимоги

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

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

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

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

Оплата з програми

Вимоги

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

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

Зареєструйте 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).

Отримайте від EasyPay сформований CSR-файл, який буде необхідний для подальших кроків.
Сформуйте 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

Щоб інтегрувати 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"
}

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

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

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

QR MasterPass

Для мерчантів, які мають пряму інтеграцію з MasterPass

Опис:

Оплата з гаманця MasterPass із використанням QR-коду.

{
  "instrumentType": "QrMasterpass",
  "commission": 0.0,
  "amountMin": 1.00,
  "amountMax": 14999.00,
  "userPaymentInstruments": [
    {
      "instrumentId": 8499910,
      "instrumentType": "QrMasterpass",
      "instrumentValue": "00020101021252040000530398054034005802UA5909EasyPayUa6004Kiev64190002UK0109EasyPayUa80850017ua.mastercard.www010200020840703434032003434180702054456177041211109354874205020181500017ua.mastercard.www011720191111093548742020499996223030443590603391070410036304AF79",
      "alias": null,
      "commission": 0.0,
      "loyaltyCommission": null,
      "actionsKeys": null,
      "priorityIndex": 0,
      "additionalParams": {
        "OrderId": "4825209b-1caa-472e-b530-dc3e8efd541c"
      }
    }
  ]
}

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

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

Sign = base64(sha256(secretKey+requestBody))

*requestBody - текст запиту у форматі json , ідентичний до EasyPay

Приклад на C#

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

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

Приклад на PHP

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

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

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

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

</body>

Цей блок може використовуватися для спеціальних повідомлень або інформаційних нотаток.

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

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

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

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

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

- CreateApp (п. 2.1)

- CreatePage (п. 2.2)

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

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

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

@@ Рядок 157: / Рядок 157: @@
      <span style="margin-left: 5px; font-weight: bold; font-size: 16px;">/api/system/createApp</span>
 </p>
+<body>
+<!-- Інформаційний блок -->
+<p style="border: 1px solid #9ACD32; background-color: rgba(144, 238, 144, 0.5); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; position: relative; padding-left: 80px;">
+    <span style="position: absolute; top: 10px; left: 10px; background-color: #006400; color: white; padding: 4px 12px; border-radius: 12px; font-size: 14px; font-weight: bold; white-space: nowrap;">
+        POST
+    </span>
+    <span style="margin-left: 70px; font-weight: bold; font-size: 16px;">/api/system/createApp</span>
+</p>
+</body>

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

Версія за 15:23, 30 серпня 2024

Зміст

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

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

URLS

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

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

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

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

Техпідримка

Інтеграція з Apple Pay

Вимоги

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

Оплата з програми

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

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

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

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

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

QR MasterPass

Опис:

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

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

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

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

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

Оплата VISA MasterCarD

Мобільні гроші КиївстарLifecellVodafone

Картки лояльності Fishka

Оплата ApplePay GPAY