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

Матеріал з apidocs
Перейти до: навігація, пошук
← Попереднє редагуванняНаступне редагування →
ВізуальнийВікірозмітка
Немає опису редагування
Немає опису редагування
Рядок 96: Рядок 96:
<p style="border: 1px solid #87CEEB; background-color: rrgba(255, 255, 0, 0.3); padding: 10px; border-radius: 4px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; position: relative; padding-left: 40px;">
<p style="border: 1px solid #87CEEB; background-color: rrgba(255, 255, 0, 0.3); padding: 10px; border-radius: 4px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; position: relative; padding-left: 40px;">
     <span style="position: absolute; top: 10px; left: 10px; font-size: 24px; color: #00008B;">ℹ️</span>
     <span style="position: absolute; top: 10px; left: 10px; font-size: 24px; color: #00008B;">ℹ️</span>
     На даний момент відсутня можливість тестування з використанням фейкових оплат / тестових карток. Платежі тільки реальні, їх можна відмінити в день оплати методом cancelOrder (п. 2.6).  
     На даний момент відсутня можливість тестування з використанням фейкових оплат / тестових карток. Платежі тільки реальні, їх можна відмінити в день оплати методом cancelOrder (п. 2.6).
</p>
</p>


Рядок 156: Рядок 156:
   "error": null
   "error": null
}
}
</syntaxhighlight>


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

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

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


GET /api/system/createApp



POST /api/system/createApp


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


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

POST /api/system/createApp

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


response
headers


body
{
  "logoPath": "https://cdn.easypay.ua/logo/",
  "hintImagesPath": "https://cdn.easypay.ua/hint_images/",
  "apiVersion": "1.0",
  "appId": "a5806a5f-dbb8-496a-a23f-aab6d2fcbce1",
  "pageId": "f3f2b678-a3c4-45ba-a865-a136fe4a62bd",
  "error": null
}

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

<br> <!-- Відступ між текстом і таблицею -->

<div style="overflow-x: auto; display: block; width: unset !important; height: auto !important; border: none;">
  <table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
    <!-- Перший рядок - заголовок -->
    <tr>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
    </tr>

    <!-- Другий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>PartnerKey</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">унікальний ідентифікатор партнера (продавця) у системі EasyPay.</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;"></td>
    </tr>    

    <!-- Четвертий рядок -->
    <tr>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
    </tr>

    <!-- Шостий рядок -->
    <tr>
      <td style="border: none; padding-right: 10px; text-align: left;">'''<code>PageId</code>'''</td>
      <td style="border: none; padding-right: 10px; text-align: left;">ідентифікатор сесії </td>
      <td style="border: none; text-align: left;">параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID</td>
    </tr>
  </table>
</div>

<br> <!-- Відступ між таблицею та текстом -->

<p>Параметри PartnerKey, SeviceKey, SecretKey передаються партнеру після реєстрації у системі EasyPay відповідальним менеджером.
За замовчуванням, якщо не було активності за запитами, час життя AppId - 3 місяці. З кожним запитом життя AppId автоматично продовжується.</p>

<p style="border: 1px solid #B22222; background-color: rgba(255, 204, 204, 0.5); padding: 10px; border-radius: 4px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; position: relative; padding-left: 40px;">
    <span style="position: absolute; top: 10px; left: 10px; font-size: 24px; color: #FF4500;">❗️</span>
    У разі отримання помилки '''APPID_NOT_FOUND''' у відповідь на будь-який метод, необхідно повторити запит createApp до отримання точки ІД.
За замо






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

=== '''Техпідримка''' ===
За потреби консультацій з питань реалізації API можна написати запит на '''merchant.api.support@easypay.ua'''

</div><!-- Перший рядок - заголовок --><!-- Другий рядок --><!-- Третій рядок --><!-- Четвертий рядок --><!-- П'ятий рядок --><!-- Шостий рядок -->


<h1>Інтеграція з Apple Pay</h1><hr color="#d3d3d3" size="1" noshade>
=== Вимоги ===

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

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

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

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

# Необхідно мати акаунт у [https://developer.apple.com/ Apple Developer], в який потрібно зареєструвати індивідуальний [https://developer.apple.com/help/account#/devb2e62b839?sub=devf31990e3f Merchant ID].
# Необхідно дотримуватися [https://developer.apple.com/apple-pay/marketing/ вимоги до брендування.]

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

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

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

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

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

===== Приклад відповіді ApplePay =====
<syntaxhighlight lang="json" line="1">
{
 "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))


<body style="font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 16px; line-height: 1.5; color: #333; margin: 20px;">

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

Щоб отримати платежі, ви можете використовувати 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="
                    }
               }
           ]
       }
   ]
Отримано з https://apidocs.easypay.ua/index.php?title=MerchantAPI&oldid=392