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

Матеріал з apidocs
Перейти до: навігація, пошук

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

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

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


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

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

Перед використанням методу потрібне додаткове налаштування терміналів зі сторони техпідтримки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])

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

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

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

Перед використанням методу потрібне додаткове налаштування терміналів зі сторони техпідтримки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])

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

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

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

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

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

Отримано з https://apidocs.easypay.ua/index.php?title=Основні_запити_та_відповіді&oldid=1871