Платіжний шлюз Portmone.com. API для партнерів з сертифікатом PCI DSS

Терміни та визначення

Термін	Визначення
Мерчант, Партнер	Організація, що уклала договір з Portmone.com про надання послуг з приймання платежів
Клієнт	Відвідувач Інтернет-сайту Мерчанта з метою ознайомлення з асортиментом товарів (послуг) та здійснення покупки
Картка, Платіжна картка	Платіжні картки міжнародних платіжних систем Visa, Mastercard та Національної платіжної системи ПРОСТІР
Авторизація	Процес надання прав доступу або інших повноважень Покупцеві, програмі або процесу
Рекурентні платежі	Автоматичні платежі (не потребують участі клієнта та повторного введення реквізитів картки), що здійснюються за згодою клієнта
Токен	Цифровий ідентифікатор картки, що генерується при першій операції і далі використовується для швидкої оплати. Токен може використовуватись виключно для повторення аналогічної транзакції, що й при першій оплаті
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
CVV2/CVC2	CVV2 (Card Verification Value 2) – тризначний код перевірки дійсності картки платіжної системи Visa. Платіжна система Mastercard має аналогічний код перевірки дійсності – CVC2 (Card Validation Code 2)
Банк-еквайр	Банк, що організовує точки приймання банківських карток (термінали, банкомати) та здійснює весь комплекс фінансових операцій, пов'язаних з виконанням розрахунків і платежів за банківськими картками в цих точках
Банк-емітент банківських карток	Банк, що є учасником платіжної системи та здійснює випуск (емісію) та обслуговування банківських карток
3-D Secure	3-D Secure – це протокол, який використовувався для забезпечення додаткового рівня безпеки онлайн-платежів з використанням банківськимх карток
PSP	PSP (Payment Service Provider) – компанія, яка надає Мерчантам онлайн-послуги з прийому електронних платежів за допомогою різних способів оплати. У цьому документі цей термін відоноситься до копаніїї Portmone.com
ACS	Сервер управління доступом (Access Control Server, або ACS) являє собою інструмент, що використовується банками-емітентами для автентифікації власників карток (це дозволяє клієнтам підтвердити свою особистість та пропонує більшу безпеку транзакцій для онлайн-продавців)
CSE	Шифрування на боці клієнта (Client-Side Encryption, або CSE) – це спосіб захисту даних, при якому інформація, перш ніж передаватися на сервер Мерчанта, шифрується на боці клієнта за допомогою відкритого ключа (public key), що наданий PSP. Зашифровані дані не можуть бути розшифровані на стороні Мерчанта, оскільки він не має закритого ключа (private key), що їх розшифровує
МПС	Міжнародна платіжна система

1. Вступ

API Платіжного шлюзу Portmone.com заснований на прозорому типі інтеграції з використанням "Client-Side Encryption" (CSE). Технологія CSE дозволяє зменшити навантаження PCI DSS для Мерчанта.

Дані власника картки шифруються на боці клієнта таким чином, щоб їх неможливо було прочитати, а потім передаються до хоста Portmone. Щоб розшифрувати повідомлення з боку Мерчанта, використовується унікальний клієнтський ключ.

Тип взаємодії: host-to-host.

Тип протоколу: HTTPS.

Тип повідомлень для обміну інформацією: XML-повідомлення або повідомлення у форматі JSON.

2. Попередні умови

Для початку роботи необхідно виконати наступні умови:

мати сертифікат PCI DSS;
подати заявку на реєстрацію у системі Portmone.com;
забезпечити URL-адресу для сповіщень, на яку система Portmone.com надсилатиме XML-повідомлення методом POST через параметр data або повідомлення у форматі JSON;
для використання технології CSE скрипт rsa-co.min.js має бути підключений до платіжної сторінки.

Після реєстрації у системі Portmone.com вам буде надано наступну інформацію:

ідентифікатор вашої компанії у системі Portmone.com (payee id);
логін для доступу до управління акаунтом (login);
пароль для доступу до управління акаунтом (password).

Необхідні URL для роботи

Для проведення оплати карткою або за токеном необхідно надсилати запит на URL: https://www.portmone.com.ua/r3/pm/.

URL для запитів після 3DS авторизації: https://www.portmone.com.ua/r3/pm-mpi/.

2.1. Шифрування даних платіжної картки

Для шифрування даних платіжної картки використовується скрипт rsa-co.min.js. Методи rsa-co.min.js викликаються з об'єкту PM.

Скрипт містить наступні методи:

PM.setPublicKey(publicKey) – встановлює значення відкритого ключа;

PM.encrypt(cardData) – повертає об'єкт із зашифрованими даними платіжної картки.

cardData – об'єкт з необхідними полями, які описують дані картки, наступного типу:

{
  "cardNumber":"4444333322221111",
  "mm":"03",
  "yy":"20",
  "cvv2":"111"
}

<script type="text/javascript"
    src="https://www.portmone.com.ua/r3/resources/services/js/lib/rsa-co.min.js">
</script>
<script type="text/javascript">
(function() {
    PM.setPublicKey('key_value');

  function encryptMyData() {
      var postData = {};
      var cardData = {
          cardNumber : cardNumber,
          mm : mm,
          yy : yy,
          cvv2 : cvv2
      };
      postData['encrypted-data'] = PM.encrypt(cardData);
      // AJAX call or different handling of the post data.
    }
})();
</script>

2.2. Підпис запиту

Формування поля signature (приклад на PHP):

$login = 'wdishop';
$payeeId = '1185';
$password = 'wdi451';
$shopOrderNumber = 'test123';
$billAmount='150';
$key = 'BDFC166F8AE2F5323A557DB6CA16758D';
$dt = date("YmdHis");
$strToSignature = $payeeId.$dt.bin2hex($shopOrderNumber).$billAmount;
$strToSignature = strtoupper($strToSignature).strtoupper(bin2hex($login));
$signature = strtoupper(hash_hmac('sha256', $strToSignature, $key));

Набір параметрів для формування підпису може відрізнятись для різних методів. У разі відмінностей від наведеного вище прикладу, набір параметрів, що беруть участь у генеруванні підпису, буде наведений безпосередньо в описі відповідного методу.

2.3. Асинхронний режим

Якщо у запиті оплати замовлення використовувався параметр mode зі значенням 1111, на вашу URL-адресу для сповіщень надійде повідомлення наступного вигляду:

Успішна відповідь:

{
    "transactionId": "419344443",
    "attemptId": "9m304ghzzl0k8c4cko08soww0sokcws",
    "errorCode": "0",
    "error": ""
}

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

Параметр	Опис
transactionId	Ідентифікатор транзакції у системі Portmone.com
attemptId	Ідентифікатор запиту, який ініціює оплату. Значення генерується випадковим чином, довжина – 31 символ (наприклад, 3wlk66m64q0wokcgkwog4040osw04ks)
errorCode	Код помилки (0 у разі успішного платежу)
error	Опис помилки

Після успішної оплати на URL для сповіщень надійде повідомлення зі структурою, що описана в розділі 9.3 "Повідомлення у форматі JSON".

3. Платіжні методи

3.1. Оплата карткою

3.1.1. Створення нового платежу

Опис:

Для проведення оплати необхідно надіслати запит на URL: https://www.portmone.com.ua/r3/pm/.

Доступність і обмеження:

Portmone.com не підтримує запити типу CORS. Це означає, що запит слід надсилати лише з вашого сервера.

Структура запиту:

Будь ласка, зверніться до "3.1.1 Запит створення нового платежу для оплати карткою" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
paymentType	Необхідно вказати значення "card" для цього параметру	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
billAmount	Сума платежу	Так
emailAddress	Адреса електронної пошти платника	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
description	Опис платежу (коментар до замовлення/ призначення оплати)	Так
token	Залишити порожнім	Ні
cardData	Зашифроване значення даних платіжної картки (номер картки, термін дії (місяць та рік), CVV2)	Так
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 5 "Підтвердження та скасування платежу з преавторизацією"), значення "N" – звичайна оплата без преавторизації). Значення без задання – "N")	Ні
cvvVerifyFlag	Значення без задання – "Y", для платежів без CVV2 необхідно встановлювати значення "N"	Ні
clientId	Залишити порожнім	Ні
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту"	Так
mode	Для роботи в асинхронному режимі використовується значення "1111"	Ні
attribute1	Службове поле, заповнюється на розсуд компанії	Ні
attribute2	Службове поле, заповнюється на розсуд компанії	Ні
attribute3	Службове поле, заповнюється на розсуд компанії	Ні
attribute4	Службове поле, заповнюється на розсуд компанії	Ні
lang	Мова інтерфейсу платіжної системи	Ні	uk – українська мова, en – англійська,az – азербайджанська	Ні

Структура відповіді:

Будь ласка, зверніться до "3.1.1 Відповідь на запит створення нового платежу для оплати карткою" для вивчення структури відповіді.

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

Параметр	Опис
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера
description	Коментар до замовлення/ опис призначення оплати
cardMask	Маска Картки платника
billAmount	Передана у запиті сума транзакції
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
status	Статус замовлення. Можливі значення: PAYED, PREAUTH, REJECTED, CREATED
token	Значення Токену для подальших оплат
MD	Параметр, який треба передати на acsUrl при проходженні 3D Secure перевірки
PaReq	Параметр, який треба передати на acsUrl при проходженні 3D Secure перевірки
is3DS	Ознака необхідності проходження перевірки 3D Secure ("Y" – необхідно пройти процедуру перевірки 3D Secure, "N" – 3D Secure перевірка не потрібна
acsUrl	URL банку, на який треба перенаправити клієнта для проходження 3D Secure перевірки
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
errorCode	Код помилки (0 у разі успішного платежу)
error	Опис помилки

3.1.2. Перенаправлення клієнта на ACS-сервер банку-емітента

Для проходження процедури перевірки 3D Secure необхідно перенаправити Клієнта на сторінку перевірки від банку-емітента (acsUrl), передавши на неї POST-запитом параметри перевірки (PaReq, MD) та URL для повернення після проходження 3D Secure (TermUrl).

Приклад:

var f = document.createElement("form");
f.setAttribute('method',"POST");
f.setAttribute('action',response.acsUrl);
var i = document.createElement("input");
i.setAttribute('type',"hidden");
i.setAttribute('name',"MD");
i.setAttribute('value',response.MD);
var i1 = document.createElement("input");
i1.setAttribute('type',"hidden");
i1.setAttribute('name',"TermUrl");
i1.setAttribute('value',TermUrl);
var i2 = document.createElement("input");
i2.setAttribute('type',"hidden");
i2.setAttribute('name',"PaReq");
i2.setAttribute('value',response.PaReq);
f.appendChild(i);
f.appendChild(i1);
f.appendChild(i2);
document.body.appendChild(f);
f.submit();

де acsUrl, MD, PaReq – параметри, отримані у відповіді від Portmone.com, TermUrl – URL партнера, на який мають повернутись параметри відповіді від банку після проходження перевірки 3D Secure.

Після вводу коду на сторінці банку Клієнт буде повернений назад на TermUrl, що вказаний у запиті, і на нього банком будуть передані параметри MD та PaRes, значення яких необхідно надіслати у Portmone.com для завершення оплати (див. розділ "3.1.3. Завершення оплати").

3.1.3. Завершення оплати

Опис:

Для завершення оплати необхідно надіслати запит на URL: https://www.portmone.com.ua/r3/pm-mpi/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "3.1.3 Запит завершення оплати" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
id	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com	Так
PaRes	Значення PaRes, отримане від банку на ваш URL	Так
MD	Значення MD, отримане від банку на ваш URL	Так

Структура відповіді:

Будь ласка, зверніться до "3.1.3 Успішна відповідь на запит завершення оплати" для вивчення структури відповіді. Опис параметрів відповіді:

Параметр	Опис
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера
description	Коментар до замовлення/ опис призначення оплати
cardMask	Маска Картки платника
billAmount	Передана у запиті сума транзакції
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
status	Статус замовлення
receiptUrl	Посилання для отримання квитанції
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
errorCode	Код помилки (0 у разі успішного платежу)
error	Опис помилки
is3DS	Ознака необхідності проходження перевірки 3D Secure ("Y" – необхідно пройти процедуру перевірки 3D Secure, "N" – 3D Secure перевірка не потрібна

3.2. Отримання токену для оплати

Опис:

Цей метод дозволяє отримати значення Токену та маски картки Клієнта. Після проведення цього методу оплати ви отримаєте значення Токену та маску Платіжної картки Клієнта, яку можете пропонувати Клієнтові в якості способу оплати на своєму ресурсі. У процесі виконання операції зі створення Токена, Portmone.com проведе авторизацію на 1 грн за карткою Клієнта, з наступним поверненням цієї суми на картку Клієнта.

Запит необхідно виконати на адресу: https://www.portmone.com.ua/r3/pm/.

Доступність і обмеження:

Поле description, що передається при виконанні цього методу, є ключовим для подальших оплат за Токеном. При зміні цього параметру у подальших оплатах за Токеном Клієнт буде отримувати повідомлення про помилку.

Структура запиту:

Будь ласка, зверніться до "3.2 Запит createToken" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
paymentType	Для створення Токену необхідно вказати значення "createToken" для цього параметру	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
billAmount	Сума платежу	Так
emailAddress	Адреса електронної пошти платника	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу. Залишити порожнім	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
description	Опис платежу (коментар до замовлення/ призначення оплати)	Обов’язковий, ідентифікує Токен у подальших оплатах
token	Залишити порожнім	Ні
cardData	Зашифроване значення даних платіжної картки (номер картки, термін дії (місяць та рік), CVV2)	Так
preauthFlag	Ознака преавторизації платежу.Залишити порожнім	Ні
cvvVerifyFlag	Значення без задання – "Y", для платежів без CVV2 необхідно встановлювати значення "N"	Ні
clientId	Залишити порожнім	Так
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту"	Так
attribute1	Службове поле, заповнюється на розсуд компанії	Ні
attribute2	Службове поле, заповнюється на розсуд компанії	Ні
attribute3	Службове поле, заповнюється на розсуд компанії	Ні
attribute4	Службове поле, заповнюється на розсуд компанії	Ні

Структура відповіді:

Будь ласка, зверніться до "3.2 Відповідь на запит createToken" для вивчення структури відповіді.

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

Параметр	Опис
notificationType	Результат запиту. У випадкузначення success - успішний, при іншому занченні - неуспішний
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера
description	Коментар до замовлення/ опис призначення оплати
cardMask	Маска Картки платника
billAmount	Передана у запиті сума транзакції
status	Статус замовлення
token	Значення Токену для подальших оплат
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
errorCode	Код помилки (0 у разі успішного платежу)
error	Опис помилки

3.3. Проведення оплати за токеном

Опис:

Для проведення оплати за Токеном необхідно надіслати запит на URL: https://www.portmone.com.ua/r3/pm/.

Доступність і обмеження:

Значення поля description має бути таким самим, що й при першій оплаті, за якою був отриманий Токен (див. розділ 3.2 "Отримання токену для оплати").

Структура запиту:

Будь ласка, зверніться до "3.3 Запит проведення оплати за Токеном" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
paymentType	Необхідно вказати значення "token" для цього параметру	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
billAmount	Сума платежу	Так
emailAddress	Адреса електронної пошти платника	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
description	Опис платежу (коментар до замовлення/ призначення оплати)	Так
token	Необхідно встановити значення Токену	Так
cardData	Зашифроване значення CVV2	Так
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 5 "Підтвердження та скасування платежу з преавторизацією"), значення "N" – звичайна оплата без преавторизації. Значення без задання – "N")	Ні
cvvVerifyFlag	Значення без задання – "Y", для платежів без CVV2 необхідно встановлювати значення "N"	Ні
clientId	Залишити порожнім	Так
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту"	Так
mode	Для роботи в асинхронному режимі використовується значення "1111"	Ні
attribute1	Службове поле, заповнюється на розсуд компанії	Ні
attribute2	Службове поле, заповнюється на розсуд компанії	Ні
attribute3	Службове поле, заповнюється на розсуд компанії	Ні
attribute4	Службове поле, заповнюється на розсуд компанії	Ні

Структура відповіді:

Будь ласка, зверніться до "3.3 Проведення оплати за Токеном. Приклад успішної відповіді" для вивчення структури відповіді.

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

Параметр	Опис
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера
description	Коментар до замовлення/ опис призначення оплати
authCode	Код авторизації банку
receiptUrl	Посилання для отримання квитанції
token	Значення Токену
mpiFlag	Повертає "N"
cardMask	Маска Картки платника
billAmount	Передана у запиті сума транзакції
status	PAYED – успішна транзакція, PREAUTH – успішна транзакція з преавторизацією
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
errorCode	Код помилки (0 у разі успішного платежу)

3.4. Проведення оплати за токеном без CVV2 (рекурентний платіж)

Опис:

Для проведення оплати за Токеном без CVV2 необхідно надіслати запит на наступний URL: https://www.portmone.com.ua/r3/recurrent/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "3.4 Запит рекурентного платежу" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
paymentType	Необхідно вказати значення "recurrent" для цього параметру	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
billAmount	Сума платежу	Так
emailAddress	Адреса електронної пошти платника	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
description	Опис платежу (має бути таким самим, що й при першій оплаті, за якою був отриманий Токен)	Так
token	Необхідно встановити значення Токену	Так
cardData	Залишити порожнім	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 5 "Підтвердження та скасування платежу з преавторизацією"), значення "N" – звичайна оплата без преавторизації. Значення без задання – "N")	Ні
cvvVerifyFlag	Значення без задання – "Y", для платежів без CVV2 необхідно встановлювати значення "N"	Так
clientId	Залишити порожнім	Так
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту"	Так
mode	Для роботи в асинхронному режимі використовується значення "1111"	Ні
attribute1	Службове поле, заповнюється на розсуд компанії	Ні
attribute2	Службове поле, заповнюється на розсуд компанії	Ні
attribute3	Службове поле, заповнюється на розсуд компанії	Ні
attribute4	Службове поле, заповнюється на розсуд компанії	Ні

4. Оплата через систему Приват24

4.1. Оплата карткою

Опис:

Щоб здійснити транзакцію через систему Приват24, необхідно надіслати запит на наступний URL: https://www.portmone.com.ua/r3/secure/gate/liq-pay.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "4.1 Запит оплати карткою" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
payee_Id	Ідентифікатор Партнера	Так
shop_order_number	Номер замовлення (рахунку) у системі Партнера	Ні
bill_amount	Сума платежу. Валюта – гривня (UAH)	Так
description	Коментар до замовлення/ опис призначення оплати	Так
lang	Мова інтерфейсу системи Приват24. Можливі значення: ru – російська, en – англійська, uk – українська мова	Так
encoding	Кодування	Так
success_url	Адреса Мерчанта, на яку буде спрямовано клієнта після успішної оплати	Так
failure_url	Адреса Мерчанта, на яку буде спрямовано клієнта у разі скасування оплати	Так

4.2. Отримання токену для оплати

Опис:

Для отримання Токену через систему Приват24 необхідно надіслати запит на наступний URL: https://www.portmone.com.ua/r3/secure/gate/liq-pay.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "4.2 Запит на створення токену" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
payee_Id	Ідентифікатор Партнера	Так
shop_order_number	Номер замовлення (рахунку) у системі Партнера	Ні
bill_amount	Сума платежу. Валюта – гривня (UAH). Необхідно встановити значення "1"	Так
description	Коментар до замовлення/ опис призначення оплати	Так
success_url	Адреса Мерчанта, на яку буде спрямовано клієнта після успішної оплати	Так
failure_url	Адреса Мерчанта, на яку буде спрямовано клієнта у разі скасування оплати	Так
revert	"Y" – повернення коштів	Так
lang	Мова інтерфейсу системи Приват24. Можливі значення: ru – російська, en – англійська, uk – українська мова	Так
encoding	Кодування	Так

4.3. Проведення оплати за токеном

Опис:

Для проведення оплати за Токеном необхідно надіслати запит на URL: https://www.portmone.com.ua/r3/pm/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "4.3 Запит проведення оплати за Токеном" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
paymentType	Необхідно вказати значення "token" для цього параметру	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
billAmount	Сума платежу	Так
emailAddress	Адреса електронної пошти платника	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
description	Опис платежу (має бути таким самим, що й при першій оплаті, за якою був отриманий Токен)	Так
token	Необхідно встановити значення Токену	Так
cardData	Зашифроване значення CVV2	Так
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 5 "Підтвердження та скасування платежу з преавторизацією"), значення "N" – звичайна оплата без преавторизації. Значення без задання – "N")	Ні
cvvVerifyFlag	Значення без задання – "Y", для платежів без CVV2 необхідно встановлювати значення "N"	Ні
clientId	Залишити порожнім	Так
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту"	Так
mode	Для роботи в асинхронному режимі використовується значення "1111"	Ні
attribute1	Службове поле, заповнюється на розсуд компанії	Ні
attribute2	Службове поле, заповнюється на розсуд компанії	Ні
attribute3	Службове поле, заповнюється на розсуд компанії	Ні
attribute4	Службове поле, заповнюється на розсуд компанії	Ні

4.4. Проведення оплати за токеном без CVV2 (рекурентний платіж)

Опис:

Для проведення оплати за Токеном без CVV2 необхідно надіслати запит на наступний URL: https://www.portmone.com.ua/r3/recurrent/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "3.4 Запит рекурентного платежу" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
paymentType	Необхідно вказати значення "recurrent" для цього параметру	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
billAmount	Сума платежу	Так
emailAddress	Адреса електронної пошти платника	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
description	Опис платежу (має бути таким самим, що й при першій оплаті, за якою був отриманий Токен)	Так
token	Необхідно встановити значення Токену	Так
cardData	Залишити порожнім	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 5 "Підтвердження та скасування платежу з преавторизацією"), значення "N" – звичайна оплата без преавторизації. Значення без задання – "N")	Ні
cvvVerifyFlag	Значення без задання – "Y", для платежів без CVV2 необхідно встановлювати значення "N"	Так
clientId	Залишити порожнім	Так
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту"	Так
mode	Для роботи в асинхронному режимі використовується значення "1111"	Ні
attribute1	Службове поле, заповнюється на розсуд компанії	Ні
attribute2	Службове поле, заповнюється на розсуд компанії	Ні
attribute3	Службове поле, заповнюється на розсуд компанії	Ні
attribute4	Службове поле, заповнюється на розсуд компанії	Ні

5. Підтвердження та скасування платежу з преавторизацією

5.1. Підтвердження платежу, що проведений з преавторизацією

Опис:

Для підтвердження платежу з преавторизацією необхідно виконати запит на адресу: https://www.portmone.com.ua/gateway/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "5.1 Запит confirmPreauth" для вивчення структури запиту.

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

Параметр	Опис
login	Логін Партнера для доступу до управління акаунтом
password	Пароль Партнера
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера. До 120 символів
token	Необхідно встановити значення Токену
postauthAmount	Сума оплати. Не може бути більше за суму, на яку проводилась преавторизація
id	ID запиту з боку Партнера до системи Portmone.com

Структура відповіді:

Будь ласка, зверніться до "5.1 Відповідь на запит confirmPreauth" для вивчення структури відповіді.

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

Параметр	Опис
shop_bill_id	Ідентифікатор замовлення у системі Portmone.com
shop_order_number	Номер замовлення (рахунку) у системі Партнера. До 120 символів
description	Опис замовлення
bill_date	Дата рахунку
pay_date	Дата оплати
pay_order_date	Дата банківського меморіального ордеру
bill_amount	Сума рахунку
auth_code	Код авторизації банку (проставляється якщо замовлення оплачене)
status	Статус замовлення
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
error_code	Код помилки
error_message	Повідомлення про помилку

5.2. Скасування платежу з преавторизацією

Опис:

Цей метод використовується для скасування платежу з преавторизацією (тобто, для переведення транзакції із статусу "PREAUTH" у статус "REJECTED").

URL для запиту: https://www.portmone.com.ua/gateway/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "5.2 Запит rejectPreauth" для вивчення структури запиту.

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

Параметр	Опис
method	Обов’язковий параметр для виклику процедури скасування платежу з преавторизацією. Значення: rejectPreauth
login	Логін Партнера для доступу до управління акаунтом
password	Пароль Партнера
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера
id	ID запиту з боку Партнера до системи Portmone.com

Структура відповіді:

Будь ласка, зверніться до "5.2 Успішна відповідь на запит rejectPreauth" для вивчення структури відповіді.

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

Параметр	Опис
description	Опис замовлення
status	Статус замовлення
attribute1-4	Службові поля, заповнюються на розсуд компанії
commission	Значення поверненої комісії з платежу
shopBillId	Ідентифікатор замовлення у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера
billAmount	Сума рахунку
errorCode	Код помилки
errorMessage	Повідомлення про помилку
authCode	Код авторизації банку
cardMask	Маска Картки платника
token	Значення Токену

6. Отримання платіжного токену після оплати

6.1. getToken

Опис:

Цей метод використовується для отримання Токену за номером замовлення (shopOrderNumber).

URL для запиту: https://www.portmone.com.ua/r3/recurrent/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "6.1 Запит getToken (приклад на PHP)" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
method	Для отримання Токену необхідно вказати значення "getToken" для цього параметру	Так
login	Логін Партнера для доступу до управління акаунтом	Так
password	Пароль Партнера	Так
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера. До 120 символів	Так
id	ID запиту з боку Партнера до системи Portmone.com	Так

Структура відповіді:

Будь ласка, зверніться до "6.1 Відповідь на запит getToken (tokenType: CARD)" та до "6.1 Відповідь на запит getToken (tokenType: PRIVAT24)" для вивчення структури відповіді.

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

Параметр	Опис
cardMask	Маска Картки платника
billAmount	Передана у запиті сума транзакції
billCurrency	Валюта проведення платежу
token	Значення Токену для подальших оплат
tokenType	CARD – при оплаті карткою, PRIVAT24 – при оплаті через систему Приват24
id	ID запиту з боку Партнера до системи Portmone.com

6.2. getTokens

Опис:

Цей метод використовується для отримання усіх Токенів за описом платежу (description).

URL для запиту: https://www.portmone.com.ua/r3/api/gateway/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "6.2 Запит getTokens (приклад на PHP)" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
method	Необхідно вказати значення "getTokens" для цього параметру	Так
login	Логін Партнера для доступу до управління акаунтом	Так
password	Пароль Партнера	Так
description	Опис платежу (коментар до замовлення/ призначення оплати)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту" та використовуйте параметри, наведені нижче у прикладі підпису	Так
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
id	ID запиту з боку Партнера до системи Portmone.com	Так

Приклад підпису [PHP]:

$strToSignature = $payeeId.$dt.bin2hex($clientId);
$strToSignature = strtoupper($strToSignature).strtoupper(bin2hex($login));
$signature = strtoupper(hash_hmac('sha256', $strToSignature, $key));

Структура відповіді:

Будь ласка, зверніться до "6.2 Відповідь на запит getTokens" для вивчення структури відповіді.

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

Параметр	Опис
cardMask	Маска Картки платника
billAmount	Сума платежу
billCurrency	Валюта проведення платежу
token	Значення Токену
tokenType	CARD – при оплаті карткою, PRIVAT24 – при оплаті через систему Приват24
id	ID запиту з боку Партнера до системи Portmone.com

6.3. Отримання даних МПС за токеном Portmone

Опис:

Необхідно надіслати запит на наступний URL: https://www.portmone.com.ua/r3/api/gateway.

Доступність і обмеження:

Доступно після проведення оплати картою.

Структура запиту JSON:

{
   "method":"getDataTokenIPS",
   "params":{
       "data":{
           "login":${MERCHANT_LOGIN},
           "password":${MERCHANT_PASSWORD},
           "tokenType":"PORTMONE",
           "tokenReference":${TOKEN_REFERENCE}
       }
   },
   "id":"1"
}

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

Параметр	Опис
MERCHANT_LOGIN	Логін мерчанта у системі Portmone
MERCHANT_PASSWORD	Пароль мерчанта у системі Portmone
TOKEN_REFERENCE	Токен карти, який повертає система Portmone

Структура та приклад відповіді (Mastercard):

{
    "result": {
        "token_type": "M4M",
        "token_info": {
            "tokenUniqueReference": "DM4MMC0000****ed8d7249e",
            "panUniqueReference": "FM4MMC000012971373*****6a75a3cf",
            "productConfig": {
                "termsAndConditionsUrl": "",
                "issuerName": ",
                "cardBackgroundCombinedAssetId": "954e89****8655a",
                "iconAssetId": "7fcf53be****cf1fbfe",
                "foregroundColor": "ffffff",
                "issuerLogoAssetId": "cd90eb72****5cc1",
                "shortDescription": "",
                "customerServiceEmail": "",
                "customerServicePhoneNumber": "",
                "customerServiceUrl": "",
                "isCoBranded": "false",
                "brandLogoAssetId": "3789637f****c509"
            },
            "tokenInfo": {
                "tokenPanSuffix": "4444",
                "accountPanSuffix": "4444",
                "tokenExpiry": "0823",
                "accountPanExpiry": "",
                "productCategory": "DEBIT",
                "dsrpCapable": true,
                "tokenAssuranceLevel": ""
            }
        }
    },
    "id": "1"
}

Опис ключових параметрів відповіді:

Параметр	Опис
TOKEN_TYPE	Тип токену в залежності від МПС
id	Унікальний ідентифікатор відповіді

Структура та приклад відповіді (Visa):

{
 "result": {
   "token_type": "VTS",
   "token_info": {
     "vPanEnrollmentID": "724bfc****38701",
     "paymentInstrument": {
       "expirationDate": {
         "month": "11",
         "year": "2023"
       },
       "last4": "1111",
       "cvv2PrintedInd": "Y",
       "expDatePrintedInd": "Y",
       "enabledServices": {
         "merchantPresentedQR": "N"
       }
     },
     "cardMetaData": {
       "backgroundColor": "0xffff00",
       "foregroundColor": "0x000000",
       "labelColor": "0x000000",
       "contactWebsite": "https://www.aval.ua",
       "contactEmail": "[email protected]",
       "contactNumber": "+380444908888",
       "contactName": "Raiffeisen Bank Aval",
       "privacyPolicyURL": "https://www.aval.ua/storage/files/politika-konfidencijnosti-04042019_1554448866.pdf",
       "termsAndConditionsURL": "https://aval.ua/storage/files/wallet-pi.pdf",
       "shortDescription": "Visa Classic",
       "cardData": [
         {
           "guid": "8407fa4e5****d705f6cb07",
           "contentType": "cardSymbol",
           "content": [
             {
               "mimeType": "image/png",
               "width": "100",
               "height": "100"
             }
           ]
         },
         {
           "guid": "09e037d****c17995ddf6",
           "contentType": "digitalCardArt",
           "content": [
             {
               "mimeType": "image/png",
               "width": "1536",
               "height": "969"
             }
           ]
         }
       ],
       "issuerFlags": {
         "deviceBinding": false,
         "cardholderVerification": false,
         "trustedBeneficiaryEnrollment": false,
         "delegatedAuthenticationSupported": true
       }
     },
     "vProvisionedTokenID": "ebc77cd5****bcc8885e01",
     "tokenInfo": {
       "tokenRequestorID": "1111111111",
       "tokenStatus": "ACTIVE",
       "last4": "",
       "expirationDate": {
         "month": "",
         "year": ""
       }
     }
   }
 },
 "id": "1"
}

Опис ключових параметрів відповіді:

Параметр	Опис
TOKEN_TYPE	Тип токену в залежності від МПС
id	Унікальний ідентифікатор відповіді
tokenInfo, cardMetaData, cardData	Мета-дані карти

6.4. Отримання ассету за унікальним ідентифікатором МПС

Опис:

Необхідно надіслати запит на наступний URL: https://www.portmone.com.ua/r3/api/gateway.

Доступність і обмеження:

Доступно після отримання ідентифікатору МПС методом getDataTokenIPS згідно п. 4.5. Для отримання кожного виду ассету необхідно зробити унікальний запит з відповідним ідентифікатором.

Структура і приклад запиту JSON:

{
    "method":"getMetaDataTokenIPS",
    "params":{
        "data":{
            "login":${MERCHANT_LOGIN},
            "password":${MERCHANT_PASSWORD},
            "tokenType":${TOKEN_TYPE},
            "metaDataId":${ASSET_ID}
        }
    },
    "id":"1"
}

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

Параметр	Опис
MERCHANT_LOGIN	Логін мерчанта у системі Portmone
MERCHANT_PASSWORD	Пароль мерчанта у системі Portmone
TOKEN_TYPE	Тип токену, отриманий методом getDataTokenIPS згідно п. 4.5
ASSET_ID:	Ідентифікатор ассету, отриманий методом getDataTokenIPS згідно п. 4.5 (AssetId\guid)

Структура та приклад відповіді:

{
 "result": {
   "mediaContents": [
     {
       "data": "",   //Base64 encoded content
       "width": 1536,
       "type": "image\/png",
       "height": 969
     }
   ]
 },
 "id": "1"
}

7. Переказ коштів з рахунку на картку та з рахунку на токен картки

Опис:

Дозволяє здійснювати переказ коштів з розрахункового рахунку на Картку або на Токен Картки. Для цього Мерчанту потрібно підписати договір з банком, після чого банк надає Логін і Пароль для терміналу.

Важливо! При використанні даного сервісу мерчанти стають податковими агентами і зобов'язані сплачувати податки (ПДФО, ЄСВ, ВЗ). Виключенням являються компанії,які мають ліцензії на здійснення особливого виду діяльності такі як: МФО (мікрокредитні організації), СК (страхові компанії).

7.1 Переказ коштів з рахунку на картку

Опис:

Для здійснення переказу коштів з рахунку на картку необхідно виконати запит на наступний URL: https://www.portmone.com.ua/r3/pm/.

Доступність і обмеження:

Метод працює тільки у синхронному режимі (mode = 1101).

Структура запиту:

Будь ласка, зверніться до "7.1 Запит на переказ коштів з рахунку на картку" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
paymentType	Необхідно вказати значення "a2c" для цього параметру	Так
description	Опис платежу (коментар до замовлення/ призначення оплати)	Так
attribute1	Службове поле. Залишити порожнім	Ні
attribute2	Передається інформація для перказу коштів	за необхідністю
attribute3	Службове поле, заповнюється на розсуд компанії	Ні
attribute4	Службове поле, заповнюється на розсуд компанії	Ні
billAmount	Сума платежу	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
cvvVerifyFlag	Значення без задання – "Y", для платежів без CVV2 необхідно встановлювати значення "N"	Ні
token	Залишити порожнім	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні
cardData	Зашифроване значення даних платіжної картки (номер картки, термін дії (місяць та рік), CVV2)	Ні
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту"	Так
mode	Для роботи в синхронному режимі використовується значення "1101"	Так

У разі сплати податків в attribute2 необхідно передавати такі параметри:

"attribute2":""client_id":"Іванов Іван", "taxes":{"income": 20, "social": 10, "military": 5},"identification":{"general":{"tax_id":"1234567890"}}",

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

Параметр	Опис	Обов’язковий
client_id	ПІБ отримувача коштів	Так
income	Сума ПДФО в копійках	Так
social	Сума ЄСВ в копійках	Так
military	Сума ВЗ в копійках	Так
tax_id	ІПН отримувача коштів	Так

Важливо! У випадку нарахування кешбеку (бонусів) не потрібно передавати параметр social.

Структура відповіді:

Будь ласка, зверніться до "7.1 Відповідь на запит переказу коштів з рахунку на картку" для вивчення структури відповіді.

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

Параметр	Опис
status	Статус замовлення. Можливі значення: REJECTED, PAYED
errorCode	Код помилки (0 у разі успішного платежу)
error	Опис помилки
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
billAmount	Передана у запиті сума транзакції
billNumber	Номер замовлення (рахунку) у системі Партнера
attribute1	Службове поле. Залишити порожнімї
attribute2	Передається інформація для перказу коштів	за необхідністю
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
payeeExportFlag	Статус проходження операції переказу коштів у банка-еквайра (Y – успішно, E – помилка, N або порожнє значення – не надіслано)
receiptLink	Посилання для отримання квитанції
billCurrency	Валюта проведення платежу
transactionId	Ідентифікатор транзакції в системі банка-еквайра

Важливо! Якщо у відповіді status = PAYED, але payeeExportFlag має значення, відмінне від Y, необхідно надіслати до системи Portmone.com запит для перевірки статусу транзакції (див. розділ 9.1.2 "Запит у форматі JSON"). Якщо у відповіді status = PAYED та payee_export_flag = Y – транзакіця успішна.

7.2 Переказ коштів з рахунку на токен картки

Опис:

Для отримання токену картки зробіть запит згідно п. 3.2 документації

Важливо! При запиті отримання токену та запиті на переказ параметр description не заповнювати.

Для здійснення переказу коштів з рахунку на токен картки необхідно виконати запит на наступний URL: https://www.portmone.com.ua/r3/pm/.

Доступність і обмеження:

Метод працює тільки у синхронному режимі (mode = 1101).

Структура запиту:

Будь ласка, зверніться до "7.2 Запит на переказ коштів з рахунку на токен картки" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
paymentType	Необхідно вказати значення "a2t_1" для цього параметру	Так
description	Залишити порожнім	Так
attribute1	Службове поле. Залишити порожнім	Так
attribute2	Передається інформація для перказу коштів	за необхідністю
attribute3	Службове поле. Залишити порожнім	Так
attribute4	Службове поле, заповнюється на розсуд компанії	Ні
billAmount	Сума платежу	Так
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
cvvVerifyFlag	Значення без задання – "Y", для платежів без CVV2 необхідно встановлювати значення "N"	Ні
token	токен картки отримувача коштів	Так
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
cardData	Зашифроване значення даних платіжної картки (номер картки, термін дії (місяць та рік), CVV2)	Ні
dt	Час створення запиту. Використовується для перевірки підпису. Передається у форматі: yyyymmddhhmmss (наприклад, 20181208130724)	Так
signature	Підпис запиту. Формування підпису див. у розділі 2.2 "Підпис запиту"	Так
mode	Для роботи в синхронному режимі використовується значення "1101"	Так

У разі сплати податків в attribute2 необхідно передавати такі параметри:

"attribute2":""client_id":"Іванов Іван", "taxes":{"income": 20, "social": 10, "military": 5},"identification":{"general":{"tax_id":"1234567890"}}",

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

Параметр	Опис	Обов’язковий
client_id	ПІБ отримувача коштів	Так
income	Сума ПДФО в копійках	Так
social	Сума ЄСВ в копійках	Так
military	Сума ВЗ в копійках	Так
tax_id	ІПН отримувача коштів	Так

Важливо! У випадку нарахування кешбеку (бонусів) не потрібно передавати параметр social.

Структура відповіді:

Будь ласка, зверніться до "7.2 Відповідь на запит переказу коштів з рахунку на токен картки" для вивчення структури відповіді.

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

Параметр	Опис
status	Статус замовлення. Можливі значення: REJECTED, PAYED
errorCode	Код помилки (0 у разі успішного платежу)
error	Опис помилки
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
billAmount	Передана у запиті сума транзакції
billNumber	Номер замовлення (рахунку) у системі Партнера
attribute1	Службове поле. Залишити порожнім
attribute2	Передається інформація для перказу коштів	за необхідністю
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
payeeExportFlag	Статус проходження операції переказу коштів у банка-еквайра (Y – успішно, E – помилка, N або порожнє значення – не надіслано)
receiptLink	Посилання для отримання квитанції
billCurrency	Валюта проведення платежу
transactionId	Ідентифікатор транзакції в системі банка-еквайра

Важливо! Якщо у відповіді status = PAYED, але payeeExportFlag має значення, відмінне від Y, необхідно надіслати до системи Portmone.com запит для перевірки статусу транзакції (див. розділ 9.1.2 "Запит у форматі JSON"). Якщо у відповіді status = PAYED та payee_export_flag = Y – транзакіця успішна.

8. Повернення коштів

8.1 POST запит

Опис:

URL для запиту: https://www.portmone.com.ua/gateway/.

Формат запиту: HTTPS POST

Доступність і обмеження:

Метод доступний для транзакцій зі статусом "PAYED" протягом 31 дня після здійснення оплати.

Структура запиту:

Будь ласка, зверніться до "8.1 Запит повернення коштів. POST запит" для вивчення структури запиту.

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

Параметр	Опис	Обов’язковий
method	Обов’язковий параметр для виклику процедури повернення. Значення: return	Так
login	Логін Партнера	Так
password	Пароль Партнера	Так
shop_bill_id	Номер замовлення у системі Portmone.com (повинен бути отриманий за допомогою методу *result*, що описаний у розділі 9.1 "Запит результатів авторизації")	Так
return_amount	Сума повернення	Так
attribute1	Додатковий необов’язковий параметр	Ні
encoding	Кодування	Так
lang	Мова повідомлень про помилки	Так

Структура відповіді:

Будь ласка, зверніться до "8.1 Успішна відповідь для процедури повернення коштів" для вивчення структури відповіді.

У разі виникнення помилки під час виклику метода (наприклад, некоректному логіні і т.д.), секція <order> буде складатись тільки з двух тегів – <error_code> та <error_message> (див. "8.1 Неуспішна відповідь для процедури повернення коштів").

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

Параметр	Опис
method	Обов’язковий параметр для виклику процедури повернення. Значення: return
login	Логін Партнера
password	Пароль Партнера
shop_bill_id	Номер замовлення у системі Portmone.com
return_amount	Сума повернення
attribute1	Додатковий необов’язковий параметр
encoding	Кодування
lang	Мова повідомлень про помилки
shop_order_number	Номер замовлення (рахунку) у системі Партнера. До 120 символів
description	Опис замовлення
bill_date	Дата рахунку
pay_date	Дата оплати
bill_amount	Сума рахунку для повернення
auth_code	Код авторизації банку
status	Статус замовлення
error_code	Код помилки (0 у разі успішного платежу)
error_message	Повідомлення про помилку

8.2. Запит у форматі JSON

Опис:

Метод використовується у разі виникнення необхідності повернення коштів Клієнту. Повернення грошових коштів здійснюється після закінчення операційного дня. Цей метод ініціює нову транзакцію в Portmone.com, яка повертає гроші клієнту, а ідентифікатор цієї транзакції повертається як shopBillId зі статусом RETURN.

URL для запиту: https://www.portmone.com.ua/gateway/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "8.2 Запит повернення коштів у форматі JSON" для вивчення структури запиту.

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

Параметр	Опис
login	Логін Партнера для доступу до управління акаунтом
password	Пароль Партнера
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера. До 120 символів
returnAmount	Сума повернення
message	Коментар до повернення
id	ID запиту з боку Партнера до системи Portmone.com

Структура відповіді:

Будь ласка, зверніться до "8.2 Формат відповіді" для вивчення структури відповіді.

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

Параметр	Опис
description	Опис замовлення
status	Статус замовлення
attribute1-4	Службові поля, заповнюються на розсуд компанії
commission	Значення поверненої комісії з платежу
shopBillId	Ідентифікатор замовлення у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера. До 120 символів
billAmount	Сума рахунку
error_code	Код помилки
error_message	Повідомлення про помилку
auth_code	Код авторизації банку (проставляється якщо замовлення оплачене)
token	Значення Токену
cardMask	Маска Картки платника

9. Отримання результатів авторизації

Партнери можуть отримувати результати авторизації наступними способами:

1) при поверненні клієнта на сайт Мерчанта після оплати;

2) XML-запитом до системи Portmone.com;

3) повідомлення серверу Партнера про результат авторзації:

передача XML-повідомлення про результат авторизації (XML-нотифікация про оплату);
передача XML-повідомлення про платіжне доручення (XML-нотифікація про фінансове покриття транзакцій);
передача повідомлення про успішну оплату у форматі JSON.

9.1. Запит результатів авторизації

9.1.1. POST запит

Опис:

Для отримання статусу оплати необхідно виконати запит на URL: https://www.portmone.com.ua/gateway/.

Доступність і обмеження:

Максимальний період запиту не повинен перевищувати 31 день.

Структура запиту:

Будь ласка, зверніться до "9.1.1 Запит результатів авторизації методом POST" для вивчення структури запиту.

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

Параметр	Опис
method	Обов’язковий параметр для виклику процедури генерації звіту. Значення: result
payee_id	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
login	Логін Партнера для доступу до управління акаунтом
password	Пароль Партнера
shop_order_number	Номер замовлення в системі Партнера. Якщо не вказувати це значення – будуть обиратись замовлення без прив’язки до номера
status	Ознака статусу замовленнь, які потрібно включити до звіту. Може приймати значення: - PAYED – оплачене, - CREATED – створене, - REJECTED – скасоване. За попередньою опцією обираються замовлення з усіма типами статусів
start_date	Дата початку звіту. Формат дд.мм.рррр. За попередньою опцією – поточна дата минулого місяця
end_date	Дата закінчення звіту. Формат дд.мм.рррр. За попередньою опцією – поточна дата

Структура відповіді:

Будь ласка, зверніться до "9.1.1 Відповідь на запит результатів авторизації методом POST" для вивчення структури відповіді.

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

Параметр	Опис
shop_bill_id	Ідентифікатор замовлення у системі Portmone.com
shop_order_number	Номер замовлення (рахунку), що сплачується, у системі Партнера
description	Опис замовлення
bill_date	Дата рахунку
pay_date	Дата оплати
bill_amount	Сума рахунку
auth_code	Код авторизації банку (проставляється якщо замовлення оплачене)
status	Статус замовлення
error_code	Код помилки
error_message	Повідомлення про помилку

9.1.2. Запит у форматі JSON

Опис:

Для отримання статусу платежу або переліку транзакцій по компанії необхідно виконати запит на адресу: https://www.portmone.com.ua/gateway/.

Доступність і обмеження:

Немає обмежень.

Структура запиту:

Будь ласка, зверніться до "9.1.2 Запит результатів авторизації у форматі JSON" для вивчення структури запиту.

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

Параметр	Опис
method	Обов’язковий параметр для виклику процедури генерації звіту. Значення: result
login	Логін Партнера для доступу до управління акаунтом
password	Пароль Партнера
payeeId	Ідентифікатор Партнера. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
shopOrderNumber	Номер замовлення в системі Партнера. Якщо не вказувати це значення – будуть обиратись замовлення без прив’язки до номера
status	Ознака статусу замовленнь, які потрібно включити до звіту. Може приймати значення: - PAYED – оплачене, - CREATED – створене, - REJECTED – скасоване. За попередньою опцією обираються замовлення з усіма типами статусів
start_date	Дата початку звіту. Формат дд.мм.рррр. За попередньою опцією – поточна дата минулого місяця
end_date	Дата закінчення звіту. Формат дд.мм.рррр. За попередньою опцією – поточна дата
id	ID запиту з боку Партнера до системи Portmone.com

Структура відповіді:

Будь ласка, зверніться до "9.1.2 Приклад успішної відповіді на запит у форматі JSON " для вивчення структури відповіді.

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

Параметр	Опис
description	Опис замовлення
status	Статус замовлення
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
commission	Значення поверненої комісії з платежу
pay_date	Дата оплати
payee_export_date	Дата відправки суми/повідомлення про сплату постачальникові
payee_export_flag	Статус надсилання постачальникові (Y – успішно, E – помилка, N або порожнє значення – не надіслано)
pay_order_date	Дата банківського меморіального ордеру
chargeback	Чи був поданий за транзакцією чарджбек
shopBillId	Ідентифікатор замовлення у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера
billAmount	Сума рахунку
errorCode	Код помилки
errorMessage	Повідомлення про помилку
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
cardMask	Маска Картки платника
token	Значення Токену для подальших оплат

9.2. XML-нотифікація

Повідомлення про успішну оплату – BILLS

Опис:

Для обміну інформацією використовується система XML-повідомлень, що передаються з використанням протоколу HTTPS. Ініціатором обміну завжди є система Portmone.com. Компанія повинна забезпечити URL-адресу, на яку система Portmone.com надсилатиме XML-повідомлення методом POST через параметр data.

Приклад:

data=<?xml version="1.0" encoding="UTF-8"?><BILLS> …..

Повідомлення BILLS надсилається Portmone.com до компанії у випадку успішного виконання оплати. Воно призначене для отримання інформації про прийнятий платіж, не чекаючи надходження коштів на розрахунковий рахунок компанії. Повідомлення містить інформацію про один сплачений рахунок.

Структура повідомлення:

Будь ласка, зверніться до "9.2 Повідомлення про успішну оплату – BILLS" для вивчення структури повідомлення.

Опис полів повідомлення:

Назва поля	Тип	Опис
PAYEE\NAME	CHAR(100)	Назва компанії отримувача коштів
PAYEE\CODE	NUMBER(15,0)	Код компанії (надається компанії системою Portmone.com)
BANK\NAME	CHAR(100)	Назва банку відправника
BANK\CODE	CHAR(6)	МФО банку відправника
BANK\ACCOUNT	CHAR(20)	Рахунок банку відправника
BILL_ID	NUMBER(15,0)	Унікальний ID рахунку у системі Portmone. Компанія повинна перевіряти унікальність `BILL_ID`. Та не дозволяти реєструвати два повідомлення з однаковими `BILL_ID`
BILL_NUMBER	CHAR(120)	Номер рахунку
BILL_DATE	CHAR(10)	Дата рахунку. Формат: YYYY-MM-DD
BILL_PERIOD	CHAR(4)	Період, за який виставляється рахунок. Формат: MMYY (місяць та рік)
PAY_DATE	CHAR(10)	Дата оплати. Формат: YYYY-MM-DD
PAYED_AMOUNT	NUMBER(15,2)	Сума оплати. Розділювач крапка (".")
PAYED_COMMISSION	NUMBER(15,2)	Сума комісії, що буде утримана банком. Через неможливість визначити, як банк проведе округлення, завжди дорівнює 0
PAYED_DEBT	NUMBER(15,2)	В тому числі оплата боргу. Розділювач крапка (".")
AUTH_CODE	CHAR(6)	Код авторизації платіжної картки
CONTRACT_NUMBER	CHAR(20)	Параметр, за яким компанія та система Portmone.com домовились ідентифікувати клієнта
ATTRIBUTE1	CHAR(20)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається
ATTRIBUTE2	CHAR(20)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається
ATTRIBUTE3	CHAR(20)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається
ATTRIBUTE4	CHAR(20)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається

Приклади:

Дивіться "9.2 Приклад повідомлення BILLS".

Повідомлення про банківський платіж – PAY_ORDERS

Опис:

Приклад:

data=<?xml version="1.0" encoding="UTF-8"?><PAY_ORDERS> …..

Повідомлення PAY_ORDERS надсилається системою Portmone.com до компанії та містить інформацію про банківські платежі. Це повідомлення використовується для звірення повідомлень BILLS з грошовими коштами, що перераховуються на розрахунковий рахунок компанії банком. Повідомлення містить інформацію про один банківський платіж.

Структура повідомлення:

Будь ласка, зверніться до "9.2 Повідомлення про банківський платіж – PAY_ORDERS" для вивчення структури повідомлення.

Опис полів повідомлення:

Назва поля	Тип	Опис
PAY_ORDER_ID	NUMBER(15,0)	ID платіжного доручення. Компанія повинна перевіряти унікальність `PAY_ORDER_ID`. Та не дозволяти реєструвати два повідомлення з однаковими `PAY_ORDER_ID`
PAY_ORDER_DATE	CHAR(10)	Дата платіжного доручення. Формат: YYYY-MM-DD
PAY_ORDER_NUMBER	CHAR(20)	Номер платіжного доручення
PAY_ORDER_AMOUNT	NUMBER(15,2)	Сума платіжного доручення. Розділювач крапка (".")
PAYEE\NAME	CHAR(100)	Назва компанії-отримувача коштів
PAYEE\CODE	NUMBER(15,0)	Код компанії (надається компанії системою Portmone.com)
BANK\NAME	CHAR(100)	Назва банку відправника
BANK\CODE	CHAR(6)	МФО банку відправника
BANK\ACCOUNT	CHAR(20)	Рахунок банку відправника
BILL_ID	NUMBER(15,0)	Унікальний ID рахунку у системі Portmone. Компанія повинна перевіряти унікальність `BILL_ID`. Та не дозволяти реєструвати два повідомлення з однаковими `BILL_ID`
BILL_NUMBER	CHAR(120)	Номер рахунку
BILL_DATE	CHAR(10)	Дата рахунку. Формат: YYYY-MM-DD
BILL_PERIOD	CHAR(4)	Період, за який виставляється рахунок. Формат: MMYY (місяць та рік)
PAY_DATE	CHAR(10)	Дата оплати. Формат: YYYY-MM-DD
PAYED_AMOUNT	NUMBER(15,2)	Сума оплати. Розділювач крапка (".")
PAYED_COMMISSION	NUMBER(15,2)	Сума комісії, що буде утримана банком
PAYED_DEBT	NUMBER(15,2)	В тому числі оплата боргу. Розділювач крапка (".")
AUTH_CODE	CHAR(6)	Код авторизації платіжної картки
CONTRACT_NUMBER	CHAR(20)	Параметр, за яким компанія та система Portmone.com домовились ідентифікувати клієнта
ATTRIBUTE1	CHAR(20)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається
ATTRIBUTE2	CHAR(20)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається
ATTRIBUTE3	CHAR(20)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається
ATTRIBUTE4	CHAR(20)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається

Приклади:

Дивіться "9.2 Приклад повідомлення PAY_ORDERS".

Підтвердження прийому інформації про оплату – повідомлення RESULT

Опис:

Повідомлення RESULT компанія надсилає до системи Portmone.com у відповідь на повідомлення PAY_ORDERS та BILLS.

Структура повідомлення:

Будь ласка, зверніться до "9.2 Підтвердження прийому інформації про оплату – повідомлення RESULT" для вивчення структури повідомлення.

Опис полів повідомлення:

Назва поля	Тип	Опис
ERROR_CODE	NUMBER(15,0)	Код помилки (0 у разі успішної обробки повідомлення)
REASON	CHAR(250)	Опис помилки

Приклади:

Дивіться "9.2 Приклад повідомлення RESULT".

9.3. Повідомлення у форматі JSON

Повідомлення про успішну оплату у форматі JSON

Опис:

Повідомлення надсилається Portmone.com до компанії у випадку успішного виконання оплати. Компанія повинна забезпечити URL-адресу, на яку система Portmone.com надсилатиме повідомлення у форматі JSON.

Структура повідомлення:

Будь ласка, зверніться до "9.3 Повідомлення про успішну оплату у форматі JSON" для вивченя структури повідомлення.

Опис параметрів повідомлення:

Параметр	Опис
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Партнера
description	Коментар до замовлення/ опис призначення оплати
cardMask	Маска Картки платника
billAmount	Передана у запиті сума транзакції
status	Статус замовлення. Можливі значення: PAYED, PREAUTH, REJECTED, CREATED
token	Значення Токену для подальших оплат
tokenType	Тип Токену. Можливі значення: - CARD – при оплаті карткою, - PRIVAT24 – при оплаті через систему Приват24
MD	Параметр, який треба передати на acsUrl при проходженні 3D Secure перевірки
PaReq	Параметр, який треба передати на acsUrl при проходженні 3D Secure перевірки
is3DS	Ознака необхідності проходження перевірки 3D Secure ("Y" – необхідно пройти процедуру перевірки 3D Secure, "N" – 3D Secure перевірка не потрібна)
acsUrl	URL банку, на який треба перенаправити клієнта для проходження 3D Secure перевірки
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
errorCode	Код помилки (0 у разі успішного платежу)
error	Опис помилки

Підтвердження прийому інформації про оплату у форматі JSON

Опис:

Це повідомлення надсилається компанією до системи Portmone.com у відповідь на повідомлення про успішну оплату у форматі JSON.

Структура повідомлення:

Будь ласка, зверніться до "9.3 Підтвердження прийому інформації про оплату у форматі JSON" для вивчення структури повідомлення.

Опис параметрів повідомлення:

Параметр	Опис
errorCode	Код помилки (0 у разі успішної обробки повідомлення)
reason	Опис помилки. Встановіть значення "OK" у разі успішної обробки повідомлення
responseId	Значення генерується випадковим чином. Довжина – до 31 символу

10. Коди помилок

Код помилки	Повідомлення про помилку	Логіка повторного виконання операцій
0	Success	Мерчант може повторити операцію
1	Declined by bank	Мерчант може повторити операцію
2	Transaction is prohibited by acquiring bank	Мерчант може повторити операцію
3	Transaction is prohibited by issuing bank	Мерчант повинен оновити Токен
4	Technical/communication problem	Мерчант може повторити операцію. Якщо текст помилки "Токен переданий для оплати заблокований в системі Portmone.com", тоді потрбіно оновити Токен
5	Transaction has exceeded the limit by your bank	Мерчант може повторити операцію
6	Not sufficient funds	Мерчант може повторити операцію
7	Invalid CVV or card expiry date	Мерчант повинен оновити Токен
8	Invalid OTP code	n/a
9	Invalid 3DS data	n/a
10	Duplicate transactions	Мерчант може повторити операцію
11	Format error	Мерчант може повторити операцію
12	Portmone verification	Мерчант може повторити операцію
13	System error. Please try again.	Мерчант може повторити операцію
14	Wrong signature	Мерчант може повторити операцію
15	Query time exceeded	Мерчант може повторити операцію
16	Invalid request data	Мерчант може повторити операцію
17	Transaction has exceeded system limits	Клієнту необхідно звернутись до служби підтримки Portmone.com. Може повторити оплату
18	Fraud	Мерчант повинен оновити Токен
19	Order not found	n/a

Validation error codes

Код помилки	Повідомлення про помилку	Логіка повторного виконання операцій
511	Invalid card number	Оновіть номер картки та повторіть спробу
512	Invalid bill amount	Оновіть суму та повторіть спробу
513	Invalid month	Оновіть значення місяця та повторіть спробу
514	Invalid year	Оновіть значення року та повторіть спробу
515	Invalid CVV2	Оновіть значення CVV2 та повторіть спробу
516	Decryption error	Оновіть значення `cardData` та повторіть спробу

11. Тестовий режим роботи

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

Для того, щоб увімкнути чи вимкнути тестовий режим платіжного шлюзу, необхідно направити відповідного листа з зареєстрованої адреси електронної пошти менеджерам Portmone.com по співпраці з Інтернет-магазинами на адресу [email protected].

Система Portmone.com надає партнерам два варіанти тестування:

1. Тест успішної оплати

Для отримання успішної відповіді на стандартній сторінці оплати Portmone.com необхідно ввести такі реквізити платіжної картки:

   Номер картки: 4444333322221111
   Термін дії: Будь-яка дата не раніше поточного дня
   CVV2-код: Будь-який

2. Тест неуспішної оплати

Для отримання помилки на стандартній сторінці оплати Portmone.com необхідно ввести такі реквізити платіжної картки:

   Номер картки: 4111111111111111
   Термін дії: Будь-яка дата не раніше поточного дня
   CVV2-код: Будь-який

Важливо! Перед запуском в роботу системи приймання платежів переконайтеся, що тестовий режим відключений!

Якщо вам потрібно отримати колбек з кодами помилок від 1 до 10 (див. розділ 10 "Коди помилок"), використовуйте наступні дані:

URL: https://www.portmone.com.ua/r3/pm-uat/.
Значення параметру cardNumber:

cardNumber	Код помилки
5100081112223332	1
5101180000000007	2
5100290029002909	3
5100705000000002	4
4111111111111111	5
4000160000000004	6
4002690000000008	7
4607000000000009	8
4017340000000003	9
4035501000000008	10

Приклади

До розділу 3 "Платіжні методи"

3.1.1 Запит створення нового платежу для оплати карткою

{
    "paymentType": "card",
    "description": "testPayment",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "billAmount": "1",
    "payeeId": "15553",
    "shopOrderNumber": "1334946951",
    "cvvVerifyFlag": "Y",
    "token": "",
    "billCurrency": "",
    "preauthFlag": "",
    "shopSiteId": "",
    "lang":"uk",
    "dt": "20181011170545",
    "cardData": "b512d42452e089436045baad776e8399b9169c7213ce4f02044eee60a0118a1e6df6b2f2a385a73bd1336a4b8d88db5236c2bc85eb059edb950dc32ea6f9c5b5e3abadc6d83a3294c6b2dd76c132df91a9c57e8e87ca8b7c59e7e8e76eae949667d6e4b66426795cc9878d44accbc5ed5e19d05e33895bce31c7db447bd325d69648d89259ad4700536c046b32e2d156ece33df29570cf962745bc1ae22bff02eabef1e4531e9830dcc6c5aa27b887f4fdc5b2bf537f7de46e2711cd9a55834021cc6774630c6d620d0daea796ba2cd58e97e1ff151668f8505cd102436fc94f412c997360bdb235e66acff6f62bc99b908a8e06bdb06b41f2859185c5e37865",
    "mode": "1111",
    "signature": "BA167AC7ADD29EAF99B254720002C109F4E76DDC3ECF7FACDD1983E216EE7FBF"
}

3.1.1 Відповідь на запит створення нового платежу для оплати карткою

Приклад успішної відповіді:

{
    "notificationType": "success",
    "shopBillId": "419339918",
    "shopOrderNumber": "659560339",
    "description": null,
    "cardMask": "414951******9158",
    "billAmount": "1",
    "status": "PAYED",
    "token": "18343139333339393138096FEA6055F55A699A090EF5611C3A838713A4694A653254778FAC93FCE5996C44FEAA2B649239CC0740222ABB7838D9913",
    "authCode": "313277",
    "is3DS": "N",
    "receiptUrl": "",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "errorCode": "0",
    "error": ""
}

Приклад відповіді, якщо необхідна перевірка 3D Secure:

{
    "notificationType":"success",
    "shopBillId": "419339918",
    "shopOrderNumber": "659560339",
    "description": null,
    "cardMask": "414951******9158",
    "billAmount": "1",
    "status": "CREATED",
    "token": "",
    "MD": "156885793",
    "PaReq": "eJxVUmFvgjAQ/SuG76Mtgi3mrMHhNpMhZmPJvjJolGQULCBsv36tots+kNy7e3n3+g5YDuXn5CRUU1RyYREbWxMhsyov5H5hvSUPd8xackgOSojwVWSdEhwi0TTpXkyKfGHt0hdxJN7Ud+jMpZRQSmeEUc/ViDDsT13qOxaHXaB5HMZNXC+yHUBXqCVVdkhlyyHNjqvNlrvE9T0MaIRQCrUJ+cyhjsc8QBcIMi0F38UvSRRv1/Z9HNnx8zugcxuyqpOt+uIMu4CuADr1yQ9tWzdzhPq+t+tKtWUlhZ1Vpd2lgAwB0K+hXWeqRgsORc6jMOj1N8Thuo+S9RC/Yhx977+3yXoByDAgT1vBHUwYwYRMyGzu0rlHAZ37kJbGiQnAvO4CoDY7gnFiBn8boFNX+ihf3Gd6dEMghlob1wyd5K0G9Gv4/snkmbU6KvyAsStl9MGy1amd5sfaDx/ZYxUEwTnlM8koFjok4uOLpAGAjAwaD4jG4+vq30/xA8mWvMM=",
    "is3DS": "Y",
    "acsUrl": "https://acs.upc.ua/acs/pa/0/0F004nnMb8cBvt3dqp9DG8GoAAA0/",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "errorCode": "0",
    "error": ""
}

Приклад відповіді, якщо сталася помилка:

{
    "shopBillId":"4001212321",
    "shopOrderNumber":"654565465",
    "description":"Test",
    "cardMask":"516874******5179",
    "billAmount":"1.01",
    "status":"REJECTED",
    "token":"",
    "tokenType":"",
    "acsUrl":"",
    "MD":"",
    "PaReq":"",
    "is3DS":"",
    "attribute1":"some",
    "attribute2":"some",
    "attribute3":"some",
    "attribute4":"some",
    "errorCode":"1",
    "error":"Declined by bank"
}

3.1.3 Запит завершення оплати

{
    "PaRes": "eJzNWVnPo0iy/Sulmkerm91Ay/WNSPbVgNnfMGB2sA0Ym19/sV1b95TuLFcaXUvImUFmEJkRcU4G7P5+b5tPt+w6lH335TPyO/z5U9YlfVp2",
    "id": "419339918",
    "MD": "156885793"
}

3.1.3 Успішна відповідь на запит завершення оплати

{
    "notificationType":"success",
    "shopBillId":"354033144",
    "shopOrderNumber":"5464654654564",
    "description":"testPayment",
    "cardMask":"535557******3083",
    "billAmount":"1",
    "authCode":"211234",
    "status":"PAYED",
    "token":"183335343033333134341287B427D11C7A9D8184196F4C4827B01C81A8E197D87AE06F66E37D1A0A375976818813EDD8E9A1BBB031CAAF32ED3878D51D58DCFC540BC878E91E835C585574B",
    "receiptUrl":"https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/3534278394690908a0fc44e7a7c5cdd7282277e1b20df78d8c515a4c71dd405f88577d27c8e5c59c25acc6b345ec45c01feb5d6da00a9a541be3742dc8a66b85",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "is3DS":"N",
    "errorCode":"0" ,
    "error": ""
}

3.2 Запит createToken

{
    "paymentType":"createToken",
    "description":"123456",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "billAmount":"1",
    "payeeId":"1185",
    "shopOrderNumber":"5464654654564",
    "cvvVerifyFlag":"Y",
    "token":"",
    "emailAddress":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "clientId":"",
    "cardData":
    {
"0165479628fced26f2b51d180d444b0d957cff1ae664ab85ca44e186b9b381928a6356f0dbd5098f307b52b066d8ca9ad394edc34e63f19d14e74536f0548cc39d272f71fb630b991337f44253f966b9f6a6ddb3fc834a54e3acffb0a062397c268e212be36cc47cb9111f1f2bdeae638a3942e927c1aca42e5e47f05ed5779a94863bd86ea07a13b0f8f321b60ddb0b7290a3b8dc3f59867b70c92a8b2995c156ce0aa96c10706a99fdeeb0dabbdad7ade5e6240a9f8afc559c9132ae8d01f5d96ed6f2cd75c28a7635a4f17adab6a11340eb5adfd30c169b2911057455ca8d5c4b63a75b44c771820b01ed7a015bbeb8464b677dc86333beb66805292b9db4"
    },
    "dt":"20180304152848",
    "signature":"FEDA7987CF16A1F69987471CC53BCF14102151F30DF3F34A5985F58422F0C40B"
}

3.2 Відповідь на запит createToken

{
    "notificationType":"success",
    "shopBillId":"453139862",
    "shopOrderNumber":"593309194",
    "description":"testPayment",
    "cardMask":"414951******9158",
    "billAmount":"1",
    "status":"PAYED",
    "token":"183435333133393836321281633D3D7E4EE2FC1BC6E08FA9C015361CB699712297DEFDDB622851153A1A624AE765D1742F233FF1AF180C9488160851954AA1A3357D9BF5B8E15F54E9F9DD7",
    "authCode":"931641",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "errorCode":"0",
    "error": ""
}

3.3 Запит проведення оплати за Токеном

{
    "paymentType":"token",
    "description":"123456",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "billAmount":"1",
    "payeeId":"1185",
    "shopOrderNumber":"5464654654564",
    "cvvVerifyFlag":"Y",
    "token":"183335343035383237341281591F85EAD4BD7FD82029943ED8482A14C77F3B931991CDC93CB62622781506765EFEE22BCDBA55FC9C0C1EB1483D01A681A1AAB733689C45D7D2931F0F81B27",
    "emailAddress":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "cardData":
    {
"2a30d5839547765061ea534ca9083f54c5c0c135afa5c51360832d13bf901fca557d3eb2819ef3a39b03aafa06b48190e5623d17ab7f1a578f1d2463f09f6e1b9ff6ee320d466fc85f8ba9d87606967f1dd54287b08a21adfa9cd1bd057805467813926f11a07b51531bd79d68a2ca0744c6ae689bddfbfac1c546aef7f39cff29df0d565f5b8ebad1fc3a84804f3cd65b70b9c9cc87400014036d9f90043d7d3ea87d6bffffe2f7536fbf033ea0f982f4a47a6fbabf91ffdf6ff72d2ec28d4f2a17d0418876fb68b1ce2143e4b66aa6215d9b5cc24b7a8560815403975c4289fd519c8b0d289c77ca574fd20c3f190f4c3c6cac10c0b76dbedbce81d8d23fc3"
    },
    "dt":"20180304152848",
    "signature":"FEDA7987CF16A1F69987471CC53BCF14102151F30DF3F34A5985F58422F0C40B",
    "mode":"1101"
}

3.3 Проведення оплати за Токеном. Приклад успішної відповіді

{
    "shopBillId":"354033144",
    "shopOrderNumber":"5464654654564",
    "description":"testPayment",
    "cardMask":"535557******3083",
    "billAmount":"1",
    "authCode":"211234",
    "status":"PAYED",
    "token":"183335343033333134341287B427D11C7A9D8184196F4C4827B01C81A8E197D87AE06F66E37D1A0A375976818813EDD8E9A1BBB031CAAF32ED3878D51D58DCFC540BC878E91E835C585574B",
    "receiptUrl":"https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/3534278394690908a0fc44e7a7c5cdd7282277e1b20df78d8c515a4c71dd405f88577d27c8e5c59c25acc6b345ec45c01feb5d6da00a9a541be3742dc8a66b85",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "mpiFlag":"N",
    "errorCode":"0"
}

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

{
    "paymentType":"recurrent",
    "description":"123456",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "billAmount":"1",
    "payeeId":"1185",
    "shopOrderNumber":"5464654654564",
    "cvvVerifyFlag":"N",
    "token":"183335343035383237341281591F85EAD4BD7FD82029943ED8482A14C77F3B931991CDC93CB62622781506765EFEE22BCDBA55FC9C0C1EB1483D01A681A1AAB733689C45D7D2931F0F81B27",
    "emailAddress":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "cardData": "",
    "dt":"20180304152848",
    "signature":"FEDA7987CF16A1F69987471CC53BCF14102151F30DF3F34A5985F58422F0C40B",
    "mode":""
}

До розділу 4 "Оплата через систему Privat24"

4.1 Запит оплати карткою

<form action="https://www.portmone.com.ua/r3/secure/gate/liq-pay" method="post">
    <input type="hidden" name="payee_id" value="1185">
    <input type="hidden" name="shop_order_number" value="SHP-121113555111654">
    <input type="hidden" name="bill_amount" value="2">
    <input type="hidden" name="description" value="test">
    <input type="hidden" name="success_url"
value="https://www.portmone.com.ua/r3/uk/ecommerce/test/success/">
    <input type="hidden" name="failure_url"
value="https://www.portmone.com.ua/r3/uk/ecommerce/test/failure/">
    <input type="hidden" name="lang" value="uk">
    <input type="hidden" name="encoding" value="UTF-8">
</form>

4.2 Запит на створення токену

<form action="https://www.portmone.com.ua/r3/secure/gate/liq-pay" method="post">
    <input type="hidden" name="payee_id" value="1185">
    <input type="hidden" name="shop_order_number" value="SHP-121113555111654">
    <input type="hidden" name="bill_amount" value="1">
    <input type="hidden" name="description" value="test">
    <input type="hidden" name="success_url"
value="https://www.portmone.com.ua/r3/uk/ecommerce/test/success/">
    <input type="hidden" name="failure_url"
value="https://www.portmone.com.ua/r3/uk/ecommerce/test/failure/">
    <input type="hidden" name="revert" value="Y">
    <input type="hidden" name="lang" value="uk">
    <input type="hidden" name="encoding" value="UTF-8">
</form>

4.3 Запит проведення оплати за Токеном

{
    "paymentType":"token",
    "description":"123456",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "billAmount":"1",
    "payeeId":"1185",
    "shopOrderNumber":"5464654654564",
    "cvvVerifyFlag":"Y",
    "token":"183335343035383237341281591F85EAD4BD7FD82029943ED8482A14C77F3B931991CDC93CB62622781506765EFEE22BCDBA55FC9C0C1EB1483D01A681A1AAB733689C45D7D2931F0F81B27",
    "emailAddress":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "cardData":
    {
"2a30d5839547765061ea534ca9083f54c5c0c135afa5c51360832d13bf901fca557d3eb2819ef3a39b03aafa06b48190e5623d17ab7f1a578f1d2463f09f6e1b9ff6ee320d466fc85f8ba9d87606967f1dd54287b08a21adfa9cd1bd057805467813926f11a07b51531bd79d68a2ca0744c6ae689bddfbfac1c546aef7f39cff29df0d565f5b8ebad1fc3a84804f3cd65b70b9c9cc87400014036d9f90043d7d3ea87d6bffffe2f7536fbf033ea0f982f4a47a6fbabf91ffdf6ff72d2ec28d4f2a17d0418876fb68b1ce2143e4b66aa6215d9b5cc24b7a8560815403975c4289fd519c8b0d289c77ca574fd20c3f190f4c3c6cac10c0b76dbedbce81d8d23fc3"
    },
    "dt":"20180304152848",
    "signature":"FEDA7987CF16A1F69987471CC53BCF14102151F30DF3F34A5985F58422F0C40B",
    "mode":"1111"
}

До розділу 5 "Підтвердження та скасування платежу з преавторизацією"

5.1 Запит confirmPreauth

{
    "method":"confirmPreauth",
    "params":
    {
        "data":
        {
            "login": "SHP_333",
            "password": "22222222",
            "payeeId":"3048",
            "shopOrderNumber":"test_1SAB1",
            "postauthAmount":"1"
        }
    },
    "id":"1"
}

5.1 Відповідь на запит confirmPreauth

{
    "shop_bill_id":"395584061",
    "shop_order_number":"test_1SAB1",
    "description":"Order description",
    "bill_date":"31.07.2018",
    "pay_date":"31.07.2018 15:30:30",
    "pay_order_date":null,
    "bill_amount":"1",
    "auth_code":"882311",
    "status":"PAYED",
    "attribute1":null,
    "attribute2":null,
    "error_code":"0",
    "error_message":""
}

5.2 Запит rejectPreauth

{
    "method":"rejectPreauth",
    "params":
    {
        "data":
        {
            "login": "",
            "password": "",
            "payeeId":"",
            "shopOrderNumber":""
        }
    },
    "id":"1"
}

5.2 Успішна відповідь на запит rejectPreauth

[
    {
        "description":"78765432",
        "status":"REJECTED",
        "attribute1":"1",
        "attribute2":"2",
        "attribute3":"3",
        "attribute4":"4",
        "commission":"1",
        "shopBillId":"411423303",
        "shopOrderNumber":"333-000000116",
        "billAmount":"1",
        "errorCode":"0",
        "errorMessage":"",
        "authCode":"204984",
        "cardMask":"516874******5179",
        "token":"18343131343233333033096C58E59899FA962C4189B243EFB3798FBC400EC43E5EB89BEEB9D4727FEB7E7F8006F2DB3343733E517647A604C3298EE"
    }
]

До розділу 6 "Отримання платіжного токену після оплати"

6.1 Запит getToken (приклад на PHP)

$jsoncontent = '{"method": "getToken", "params": {"login": "shp_", "password": "
", "shopOrderNumber":"test_1s4s4s4"}, "id":"1"}';
$ch = curl_init();
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_URL, "https://www.portmone.com.ua/r3/recurrent/");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsoncontent);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$result = curl_exec($ch);
$curl_info = curl_getinfo($ch);
curl_close($ch);

6.1 Відповідь на запит getToken (tokenType: CARD)

{
    "result":
    {
        "cardMask":"411111******1111",
        "billAmount":"100",
        "billCurrency":"UAH",
        "token":"183139323139323737380965F710436F9AFA2B1BCC0322ABAE2A9D39863DF9B028A578451A6CF9188490331C6A9C63D0E4749A257119DE5CF4A33B4",
        "tokenType":"CARD"
    },
    "id":"1"
}

6.1 Відповідь на запит getToken (tokenType: PRIVAT24)

{
    "result":
    {
        "cardMask":"516874*79",
        "billAmount":"1.01",
        "billCurrency":"UAH",
        "token":"18333837353838353131096F85F1E5B0E1E4619D8BE4DE5B6B68ACAE9A3BA0486F4F2144048AD176B3BF2716D7D41731D6EC273DD501BD97CB07377",
        "tokenType":"PRIVAT24"
    },
    "id":"1"
}

6.2 Запит getTokens (приклад на PHP)

$jsoncontent = '{
"method": "getTokens",
"params":
{
"data": {
"login": "wdishop",
"password": "wdi451",
"description":"'.$description.'",
"payeeId":"'.$payeeId.'",
"dt":"'.$dt.'",
"signature":"'.$signature.'"
}
},
"id":"1"}';
$ch = curl_init();
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_URL, "https://www.portmone.com.ua/r3/api/gateway/");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsoncontent);
$result = curl_exec($ch);
$curl_info = curl_getinfo($ch);
print_r($curl_info);
print_r($result);
curl_close($ch);
$file = 'test.txt';
file_put_contents($file, $result);

6.2 Відповідь на запит getTokens

{
    "result":
    [
        {
            "token":"183337303236353831340641B61B7FA4D9F338B94439BC256FCF060A1C03A7394185AC0B6A015E9C0334EAD",
            "cardMask":"411111******1111",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"18333834333834313435096EFADEC52B8BE117819FD0C9731B116E3A4ACE1D2AA4BC513DC9FC9F4888F37190A843EAF9C082F1E6B3DAB46983105E7",
            "cardMask":"418837******4707",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"183337333430383238380960405F352CF119FC1A46009328B2981340618B236208A7464071C52D13A63C12EF6FB256D9BBFE04AACFE01896776C3C2",
            "cardMask":"487411******0840",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"1833373536353135333306425DC368C39A4878A915B5D26429D9783705BDC420373BE0CED15FE9EC2B6C2EF",
            "cardMask":"410232******5594",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"18333730353836333830064056BCF6795D8109FFB3C0B9EAA2293E83B9A3113CBFC80FE330FE00F106C6E23",
            "cardMask":"535557******3083",
            "billAmount":"",
            "billCurrency":"",
            "tokenType":"CARD"
        },
        {
            "token":"18333834363634323837128E83990641E033F70060C770993546C253A2329D9A6ABB3F8864684EC56824470F402D1C4AE118D15589CB784AE4D203EC1B5D5A0977D51DB710E2D9EF769A021",
            "cardMask":"516874*79",
            "billAmount":"1.02",
            "tokenType":"PRIVAT24",
            "billCurrency":"UAH"
        }
    ],
    "id":"1"
}

До розділу 7 "Переказ коштів з рахунку на картку та з рахунку на токен картки"

7.1 Запит на переказ коштів з рахунку на картку

{
    "paymentType":"a2c",
    "description":"5168742215175179",
    "attribute1":"",
    "attribute2":"552aa24c46c807a05bb0fc32477c19f0",
    "attribute3":"3",
    "attribute4":"4",
    "billAmount":"1.33",
    "payeeId":"17553",
    "shopOrderNumber":"SHP-27810-20190913045941",
    "cvvVerifyFlag":"N",
    "token":"",
    "billCurrency":"UAH",
    "preauthFlag":"N",
    "shopSiteId":"",
    "cardData":"",
    "dt":"20190913165941",
    "signature":"7B82D64E6CC226E3A5036F6020E77BD71F517C5D49F5FF80EA24289FEDBC56AE",
    "mode":"1101"
}

7.1 Відповідь на запит переказу коштів з рахунку на картку

{
    "status":"PAYED",
    "errorCode":"0",
    "error":"",
    "shopBillId":"544917852",
    "billAmount":"1.33",
    "billNumber":"SHP-21251-20190913032725",
    "attribute1":"58661656",
    "attribute2":"552aa24c46c807a05bb0fc32477c19f0",
    "attribute3":"838622",
    "attribute4":"925615124384",
    "authCode":"000000",
    "payeeExportFlag":"Y",
    "receiptLink":"https:\/\/portmone2.com\/r3\/services\/receipts\/get-receipts\/shop-bill-id\/35354f5f1297395f0d47613cb8098865636cfcd1584bd40241d634ae36efde97184b631cc0a1e8ed1c3546365bd4ce3860ac7b5b0ec0748c5236b25af3b926a624",
    "billCurrency":null,
    "transactionId":"ZEM_1647320190913032726"
}

7.2 Запит на переказ коштів з рахунку на токен картки

{
   "description":"test",
   "paymentType":"a2t_1",
   "attribute1":"",
   "attribute2":"\"client_id\":\"Іванов Іван\", \"taxes\":{\"income\": 20, \"social\": 10, \"military\": 5},\"identification\":{\"general\":{\"tax_id\":\"1234567890\"}}",
   "attribute3":"3",
   "attribute4":"4",
   "billAmount":"1",
   "payeeId":"18875",
   "shopOrderNumber":"SHP-1445284353-20201020025708",
   "cvvVerifyFlag":"Y",
   "billCurrency":"UAH",
   "mode":"1101",
   "cardData":"",
   "dt":"20201020145708",
   "signature":"193955BF02ED0B08D42F8819D4127EB48056B3109AB68DE074A4568BD55AAECB",
   "token":"18373333393634343931096442C3FD3DA5C78E03FF93B95339EDA2AA690C6E1FD63C113A431349F33C152E44EA98082AEEF72122638264BF65F9A38"
}

7.2 Відповідь на запит переказу коштів з рахунку на токен картки

{
    "status": "PAYED",
    "errorCode": "0",
    "error": "",
    "shopBillId": "866480371",
    "billAmount": "1",
    "shopOrderNumber": "464354715",
    "attribute1": "70456009",
    "attribute2": "\"client_id\":\"Иванов Иван\", \"taxes\":{\"income\": 20, \"social\": 10, \"military\": 5},\"identification\":{\"general\":{\"tax_id\":\"1234567890\"}}",
    "attribute3": null,
    "attribute4": "4",
    "authCode": "000000",
    "payeeExportFlag": "N",
    "receiptLink": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/3535cc3cd0f108cbcbce4967d6501411807b39b0e068fb26a93147adfcc15cf7d5c78d9ab343063e01b82dc7ecb14809772100682ef57b2782095b38c27a03e0ab",
    "billCurrency": "UAH",
    "transactionId": null
}

До розділу 8 "Повернення коштів"

8.1 Запит повернення коштів. POST запит

<form action="https://www.portmone.com.ua/gateway/" method="post">
    <input type="hidden" name="method" value="return" />
    <input type="hidden" name="login" value="shp_login" />
    <input type="hidden" name="password" value="******" />
    <input type="hidden" name="shop_bill_id" value="87834981" />
    <input type="hidden" name="return_amount" value="99.00" />
    <input type="hidden" name="encoding" value="utf-8"/>
    <input type="hidden" name="lang" value="uk"/>
</form>

8.1 Успішна відповідь для процедури повернення коштів

<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
    <request>
        <method>return</method>
        <login>shp_login</login>
        <password>******</password>
        <shop_bill_id>87834981</shop_bill_id>
        <return_amount>99.00</return_amount>
        <encoding>utf-8</encoding>
        <lang>uk</lang>
    </request>
    <order>
        <shop_bill_id>87834981</shop_bill_id>
        <shop_order_number>TEST001</shop_order_number>
        <description>TEST PAYMENT</description>
        <bill_date>15.07.2018</bill_date>
        <pay_date>15.07.2018 22:21:51</pay_date>
        <bill_amount>-99.00</bill_amount>
        <auth_code>123456</auth_code>
        <status>RETURN</status>
        <error_code>0</error_code>
        <error_message></error_message>
    </order>
</portmoneresult>

8.1 Неуспішна відповідь для процедури повернення коштів

<order>
    <error_code>5</error_code>
    <error_message><![CDATA[Account payment confirmation error [SHOP_BILL_ID =
    87834981]ORA-20001: Determining payment terminal details error.
    [pay_terminal_id=]]]></error_message>
</order>

8.2 Запит повернення коштів у формаіті JSON

{
    "method":"return",
    "params":
    {
        "data":
        {
            "login": "SHP_333",
            "password": "22222222",
            "payeeId":"3048",
            "shopOrderNumber":"test_1SAB",
            "returnAmount":"",
            "message":"test return"
        }
    },
    "id":"1"
}

8.2 Формат відповіді

[
    {
        "description":"78765432",
        "status":"RETURN",
        "attribute1":"",
        "attribute2":"",
        "attribute3":"",
        "attribute4":"",
        "commission":"0",
        "shopBillId":"410343513",
        "shopOrderNumber":"SHP-29174",
        "billAmount":"-1",
        "errorCode":"0",
        "errorMessage":"test return",
        "authCode":"511965",
        "token":"",
        "cardMask":""
    }
]

До розділу 9 "Отримання результатів авторизації"

9.1.1 Запит результатів авторизації методом POST

<form action="https://www.portmone.com.ua/gateway/" method="post">
    <input type="hidden" name="method" value="result" />
    <input type="hidden" name="payee_id" value="1085" />
    <input type="hidden" name="login" value="WDISHOP" />
    <input type="hidden" name="password" value="1111111" />
    <input type="hidden" name="shop_order_number" value="TEST001" />
    <input type="hidden" name="status" value="PAYED"/>
    <input type="hidden" name="start_date" value="05.07.2018"/>
    <input type="hidden" name="end_date" value="05.07.2018"/>
</form>

9.1.1 Відповідь на запит результатів авторизації методом POST

<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
    <request>
        <payee_id>1185</payee_id>
        <shop_order_number>123456</shop_order_number>
        <status>PAYED</status>
        <start_date>05.07.2018</start_date>
        <end_date>05.07.2018</end_date>
    </request>
    <orders type='list' >
        …
        <order>
            <shop_bill_id>387886615</shop_bill_id>
            <shop_order_number>123456</shop_order_number>
            <description>111111</description>
            <bill_date>05.07.2018</bill_date>
            <pay_date>05.07.2018 15:57:44</pay_date>
            <bill_amount>14.28</bill_amount>
            <auth_code>123456</auth_code>
            <status>PAYED</status>
            <error_code>0</error_code>
            <error_message></error_message>
        </order>
        …
    </orders>

9.1.2 Запит результатів авторизації у форматі JSON

{
    "method":"result",
    "params":
    {
        "data":
        {
            "login":"P_DIRECT_CCLOAN",
            "password": "11111111",
            "payeeId":"17553",
            "shopOrderNumber":"SHP-21251-20190913032725",
            "status":"",
            "startDate":"13.09.2019",
            "endDate":"13.09.2018"
        }
    },
    "id":"1"
}

9.1.2 Приклад успішної відповіді на запит у форматі JSON

[
    {
        "description":"516874******5179",
        "status":"PAYED",
        "attribute1":"58661656",
        "attribute2":"552aa24c46c807a05bb0fc32477c19f0",
        "attribute3":"838622",
        "attribute4":"925615124384",
        "commission":0,
        "pay_date":"13.09.2019",
        "payee_export_date":"13.09.2019",
        "payee_export_flag":"Y",
        "pay_order_date":"",
        "chargeback":"N",
        "shopBillId":"544917852",
        "shopOrderNumber":"SHP-21251-20190913032725",
        "billAmount":"1.33",
        "errorCode":"0",
        "errorMessage":"",
        "authCode":"000000",
        "cardMask":"000000",
        "token":"1835343439313738353216029F3201DB621287E7931807434FF90895A3414443A7DC4A2FF4E52D26A7A75665400524A1430772A2039748BE34A0D828E52E55255F1C827F421D416626752B7E3422BD6237D736F758CC04F8645E22D"
    }
]

9.2 Повідомлення про успішну оплату – BILLS

<?xml version="1.0" encoding="UTF-8"?>
<BILLS>
<BILL>
      <PAYEE>
          <NAME>Назва компанії</NAME>
          <CODE> Код компанії</CODE>
      </PAYEE>
      <BANK>
          <NAME> Назва банку відправника </NAME>
          <CODE> МФО банку відправника</CODE>
          <ACCOUNT> Рахунок банку відправника </ACCOUNT>
      </BANK>
      <BILL_ID>ID рахунку </BILL_ID>
      <BILL_NUMBER> Номер рахунку</BILL_NUMBER>
      <BILL_DATE> Дата рахунку</BILL_DATE>
      <BILL_PERIOD> Період рахунку</BILL_PERIOD>
      <PAY_DATE>Дата оплати</PAY_DATE>
      <PAYED_AMOUNT> Сума оплати</PAYED_AMOUNT>
      <PAYED_COMMISSION> Сума комісії, що буде утримана банком </PAYED_COMMISSION>
              <PAYED_DEBT>В тому числі оплата боргу</PAYED_DEBT>
      <AUTH_CODE> Код авторизації картки</AUTH_CODE>
      <PAYER>
          <CONTRACT_NUMBER>Опис рахунку </CONTRACT_NUMBER>
          <ATTRIBUTE1>Додатковий параметр 1</ATTRIBUTE1>
          <ATTRIBUTE2>Додатковий параметр 2</ATTRIBUTE2>
          <ATTRIBUTE3>Додатковий параметр 3</ATTRIBUTE3>
          <ATTRIBUTE4>Додатковий параметр 4</ATTRIBUTE4>
      </PAYER>
  </BILL>
</BILLS>

9.2 Приклад повідомлення BILLS

<?xml version="1.0" encoding="UTF-8"?>
    <BILLS>
<BILL>
        <PAYEE>
            <NAME>ПАТ «Березка»</NAME>
            <CODE>1001</CODE>
        </PAYEE>
        <BANK>
            <NAME>АТ "Банк "Фінанси та Кредит"</NAME>
            <CODE>300131</CODE>
            <ACCOUNT>29244020902980</ACCOUNT>
        </BANK>
        <BILL_ID>14561</BILL_ID>
        <BILL_NUMBER>3892/1</BILL_NUMBER>
        <BILL_DATE>2010-02-01</BILL_DATE>
        <BILL_PERIOD>0110</BILL_PERIOD>
        <PAY_DATE>2010-02-15</PAY_DATE>
        <PAYED_AMOUNT>120.35</PAYED_AMOUNT>
        <PAYED_COMMISSION>0</PAYED_COMMISSION>
        <PAYED_DEBT>0</PAYED_DEBT>
        <AUTH_CODE>739280</AUTH_CODE>
        <PAYER>
            <CONTRACT_NUMBER>Опис замовлення</CONTRACT_NUMBER>
            <ATTRIBUTE1>12082010</ATTRIBUTE1>
        </PAYER>
    </BILL>
</BILLS>

9.2 Повідомлення про банківський платіж – PAY_ORDERS

<?xml version="1.0" encoding="UTF-8"?>
<PAY_ORDERS>
    <PAY_ORDER>
       <PAY_ORDER_ID> ID платіжного доручення</PAY_ORDER_ID>
        <PAY_ORDER_DATE> Дата платіжного доручення</PAY_ORDER_DATE>
        <PAY_ORDER_NUMBER>Номер платіжного доручення</PAY_ORDER_NUMBER>
        <PAY_ORDER_AMOUNT>Сума платіжного доручення</PAY_ORDER_AMOUNT>
        <PAYEE>
            <NAME>Назва компанії отримувача</NAME>
            <CODE>Код компанії</CODE>
        </PAYEE>
        <BANK>
            <NAME>Назва банку</NAME>
            <CODE>МФО банку</CODE>
            <ACCOUNT>Р/р відправника</ACCOUNT>
        </BANK>
        <BILLS>
            <BILL>
                <BILL_ID>ID рахунку </BILL_ID>
                <BILL_NUMBER> Номер рахунку</BILL_NUMBER>
                <BILL_DATE> Дата рахунку</BILL_DATE>
                <BILL_PERIOD> Період рахунку</BILL_PERIOD>
                <PAY_DATE>Дата оплати</PAY_DATE>
                <PAYED_AMOUNT> Сума оплати </PAYED_AMOUNT>
                <PAYED_COMMISSION> Сума комісії, що буде
             утримана банком </PAYED_COMMISSION>
                <PAYED_DEBT>В тому числі оплата боргу</PAYED_DEBT>
                <AUTH_CODE> Код авторизації картки</AUTH_CODE>
                <PAYER>
                    <CONTRACT_NUMBER>Опис замовлення</CONTRACT_NUMBER>
                    <ATTRIBUTE1>Додатковий параметр 1</ATTRIBUTE1>
                    <ATTRIBUTE2>Додатковий параметр 2</ATTRIBUTE2>
                    <ATTRIBUTE3>Додатковий параметр 3</ATTRIBUTE3>
                    <ATTRIBUTE4>Додатковий параметр 4</ATTRIBUTE4>
                </PAYER>
            </BILL>
        </BILLS>
    </PAY_ORDER>
</PAY_ORDERS>

9.2 Приклад повідомлення PAY_ORDERS

<?xml version="1.0" encoding="UTF-8"?>
<PAY_ORDERS>
    <PAY_ORDER>
        <PAY_ORDER_ID>26792</PAY_ORDER_ID>
        <PAY_ORDER_DATE>2010-02-16</PAY_ORDER_DATE>
        <PAY_ORDER_NUMBER>120985735</PAY_ORDER_NUMBER>
        <PAY_ORDER_AMOUNT>138.85</PAY_ORDER_AMOUNT>
        <PAYEE>
            <NAME>ПАТ «Березка»</NAME>
            <CODE>1001</CODE>
        </PAYEE>
        <BANK>
            <NAME>АТ "Банк "Фінанси та Кредит"</NAME>
            <CODE>300131</CODE>
            <ACCOUNT>29244020902980</ACCOUNT>
        </BANK>
        <BILLS>
            <BILL>
                <BILL_ID>14561</BILL_ID>
                <BILL_NUMBER>3892/1</BILL_NUMBER>
                <BILL_DATE>2010-02-01</BILL_DATE>
                <BILL_PERIOD>0110</BILL_PERIOD>
                <PAY_DATE>2010-02-15</PAY_DATE>
                <PAYED_AMOUNT>120.35</PAYED_AMOUNT>
                <PAYED_COMMISSION>5.0</PAYED_COMMISSION>
                <PAYED_DEBT>0</PAYED_DEBT>
                <AUTH_CODE>739280</AUTH_CODE>
                <PAYER>
                    <CONTRACT_NUMBER>08967563</CONTRACT_NUMBER>
                    <ATTRIBUTE1>12082010</ATTRIBUTE1>
                </PAYER>
            </BILL>
            <BILL>
                <BILL_ID>14569</BILL_ID>
                <BILL_NUMBER>3892/2</BILL_NUMBER>
                <BILL_DATE>2010-02-01</BILL_DATE>
                <BILL_PERIOD>0110</BILL_PERIOD>
                <PAY_DATE>2010-02-15</PAY_DATE>
                <PAYED_AMOUNT>20.50</PAYED_AMOUNT>
                <PAYED_COMMISSION>1.0</PAYED_COMMISSION>
                <PAYED_DEBT>0</PAYED_DEBT>
                <AUTH_CODE>360157</AUTH_CODE>
                <PAYER>
                    <CONTRACT_NUMBER>08967568</CONTRACT_NUMBER>
                    <ATTRIBUTE1>12082011</ATTRIBUTE1>
                </PAYER>
            </BILL>
        </BILLS>
    </PAY_ORDER>
</PAY_ORDERS>

9.2 Підтвердження прийому інформації про оплату – повідомлення RESULT

<?xml version="1.0" encoding="UTF-8"?>
<RESULT>
      <ERROR_CODE>Код помилки</ERROR_CODE>
      <REASON>Опис помилки</REASON>
</RESULT>

9.2 Приклад повідомлення RESULT

<?xml version="1.0" encoding="UTF-8"?>
<RESULT>
      <ERROR_CODE>0</ERROR_CODE>
      <REASON>OK</REASON>
</RESULT>

9.3 Повідомлення про успішну оплату у форматі JSON

{
    "shopBillId":"",
    "shopOrderNumber":"",
    "description":"",
    "cardMask":"",
    "billAmount":"",
    "status":"",
    "token":"",
    "tokenType":"",
    "acsUrl":"",
    "MD":"",
    "PaReq":"",
    "is3DS":"",
    "attribute1":"",
    "attribute2":"",
    "attribute3":"",
    "attribute4":"",
    "errorCode":"0",
    "error":""
}

9.3 Підтвердження прийому інформації про оплату у форматі JSON

{
  "errorCode":"0",
  "reason":"OK",
  "responseId":"123456789"
}

Додаток 1. Схема оплати карткою з перевіркою 3D-Secure

3DS flow diagramm

Крок	Опис
1	Мерчант відображає Клієнту платіжну форму (Примітка: для шифрування даних картки Клієнта перед відправкою форми на сервер Мерчанта, останній включає до платіжної форми бібліотеку JavaScript, що надана Portmone.com)
2	Клієнт вводить дані платіжної картки та надсилає їх на сервер Мерчанта. Дані картки надсилаються Мерчанту у зашифрованому вигляді
3	Сервер Мерчанта формує "Запит створення нового платежу для оплати карткою" та надсилає його на сервер Portmone (PSP)
4	Сервер Portmone відправляє до Directory Server запит на перевірку картки на участь у 3D-Secure (VEReq)
5	Directory Server повертає серверу Portmone відповідь на запит верифікації (VERes)
6	Сервер Portmone повертає серверу Мерчанта "Відповідь на запит створення нового платежу для оплати карткою" з параметром `is3DS = Y`
7-8	Сервер Мерчанта надсилає до ACS-серверу банка-емітента запит автентифікації платника (PAReq) через браузер Клієнта
9	ACS відображає Клієнту форму 3DS-авторизації
10	Клієнт здійснює 3DS-авторизацію
11-12	ACS-сервер банка-емітента формує відповідь з результатами 3DS-авторизації (PARes) та надсилає її на сервер Мерчанта через браузер Клієнта (на URL, що вказаний у кроці 7 у параметрі `TermUrl` запиту-редиректа до ACS-сервера)
13	Сервер Мерчанта надсилає на сервер Portmone "Запит завершення оплати"
14	Portmone надсилає запит оплати до банку-еквайра
15	Банк-еквайр здійснює обробку платежу та повертає відповідь з результатами до Portmone
16	Portmone повертає на сервер Мерчанта "Відповідь на запит завершення оплати" та надсилає Мерчанту повідомлення про успішну оплату (у разі необхідності)