Платіжний шлюз Portmone.com

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

Термін	Визначення
Мерчант, Інтернет-магазин або Партнер	Організація, що уклала договір з 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 – це протокол, який використовується для забезпечення додаткового рівня безпеки онлайн-платежів з використанням банківських карток
IBAN	Міжнародний номер банківського рахунку (англ. International Bank Account Number)
МПС	Міжнародна платіжна система

1. Технологія приймання оплат

Опис механізму приймання оплат платіжними картками на Інтернет-сайті магазину:

1. Покупець обирає товар на сайті (або у мобільному додатку) Магазину, формує замовлення та обирає форму оплати за платіжними картками.
2. Магазин переадресує Покупця на авторизаційний сервер системи Portmone.com, з передачею ряду необхідних параметрів (ідентифікатор партнера у системі Portmone.com, номер замовлення, його сума тощо).
3. Авторизаційний сервер Portmone.com встановлює з Покупцем з'єднання за захищеним протоколом (TLS 1.2), перевіряє дані, що отримані від Магазину.
4. Сайт Portmone.com приймає від Покупця параметри його платіжної картки та забезпечує авторизацію картки.
5. При використанні верифікації Картки за технологією 3-D Secure Portmone.com спрямовує Клієнта на сайт банку-емітенту Картки для підтвердження транзакції.
6. Запит на авторизацію передається через закриті банківські мережі банку-емітенту Карти Покупця або процесинговому центру, що уповноважений банком-емітентом.

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

7. При неуспішній авторизації картки (відмові у авторизації):

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

8. При успішній оплаті на сторінку Інтернет-магазину передається методом POST номер сплаченого замовлення та дані платежу.
9. Інтернет-магазин повинен додатково проконтролювати статус та суму замовлення одним з методів, що наведені у розділі 8 "Отримання результатів авторизації".

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

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

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

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

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

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

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

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

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

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

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

3. Оплата замовлення

3.1. POST запит

Опис:

Для приймання оплат за Платіжними картками необхідно передати запит методом POST на сторінку платіжного шлюзу – https://www.portmone.com.ua/gateway/.

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

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

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

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

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

Параметр	Опис	Обов’язковий	Значення
payee_id	Ідентифікатор Інтернет-магазину	Так	Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
shop_order_number	Номер замовлення (рахунку), що сплачується, у Інтернет-магазині. До 120 символів. Номер рахунку повинен бути унікальним у межах одного замовлення. Якщо замовлення з цим номером рахунку вже було сплачене, система Portmone.com відхилить транзакцію	Ні	До 120 символів
bill_amount	Сума замовлення. Валюта – гривні. Дробова частина відокремлюється символом крапки “.”	Так	Наприклад: 1.50
bill_currency	Валюта проведення платежу	Ні	Можливі значення: UAH, USD, EUR, GBP, PLN, KZT (значення без задання – UAH)
description	Коментар до замовлення/ опис призначення оплати	Ні	До 250 символів
success_url	Адреса Інтернет-магазину (внутрішній URL мобільного додатку), на яку буде спрямовано Клієнта після успішного завершення платежу. Після успішної оплати замовлення на цю адресу методом POST Portmone.com надішле номер замовлення shop_order_number та дані платежу. За фактом виклику цієї сторінки на сайті Інтернет-магазину можна виконати звірення статусу і суми транзакції в системі Portmone.com. Нижче описані ці процедури (див. розділ 8 «Отримання результатів авторизації»)	Ні	Наприклад: http://example.com/success.html
failure_url	Адреса Інтернет-магазину, на яку буде спрямовано Клієнта у разі скасування оплати	Ні	Наприклад: http://example.com/failure.html
lang	Мова інтерфейсу платіжної системи	Ні	uk – українська мова, en – англійська,
encoding	Кодування	Ні	Без задання – UTF-8
preauth_flag	Встановлює режим преавторизації, коли кошти тільки блокуються на картці клієнта, але фінансового списання з рахунку Клієнта не відбувається	Ні	"Y" – вмикає режим преавторизації, "N" – вимикає режим (значення без задання — "N")
attribute1-4	Службове поле	Ні	Заповнюється на розсуд компанії
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»)	Ні	Заповнюється у форматі: Desc1:payeeID1;amount1; Desc2:payeeID2;amount2; де Desc1 – опис замовлення для першої компанії-одержувача, payeeID1 – ID першої компанії-одержувача, amount1 – сума, яка повинна піти на першу компанію, Desc2 – опис замовлення для другої компанії-одержувача, payeeID2 – ID другої компанії-одержувача, amount2 – сума, яка повинна піти на другу компанію. Кількість компаній для розщеплення обмежена тільки довжиною рядку (до 500 символів)
exp_time	Встановлює інтервал, протягом якого замовлення може бути оплачене. Якщо значення параметру було передане, то з моменту виклику платіжної сторінки показується зворотний відлік, який видно Клієнту на сторінці оплати. По закінченню часу на оплату рахунок переходить в статус "REJECTED" і оплатити його неможливо	Ні	Заповнюється в секундах
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так

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

Будь ласка, зверніться до "3.1 Приклад відповіді шлюзу у разі успішного здійснення платежу для запиту методом POST" для вивчення структури відповіді.

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 128 символів
APPROVALCODE	Код авторизації
BILL_AMOUNT	Передана у запиті сума транзакції
TOKEN	Значення Токену для подальших оплат
RESULT	Результат виконання операції (у разі успіху = 0)
CARD_MASK	Маска Картки платника
ATTRIBUTE1	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE2	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE3	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE4	Службове поле, заповнюється на розсуд компанії
RECEIPT_URL	Посилання для отримання квитанції
LANG	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
DESCRIPTION	Коментар до замовлення/ опис призначення оплати. До 250 символів
ERRORIPSCODE	Код помилки, якщо токен Visa не був створений
ERRORIPSMESSAGE	Текст помилки, якщо токен Visa не був створений

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

Опис:

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

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

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

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

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

Параметри для формування JSON-структури запиту:

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
displayMessage	Відображення інформації на платіжній сторінці для клієнта:<font style=\"font-size:14px;\">Hello</font> %username% !	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Опис платежу (коментар до замовлення/призначення оплати). Максимальна кількість символів 250	Ні
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів 128	Ні
billAmount	Сума платежу	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
preauthConfirm	Дата автоматичного списання заблокованих коштів для платежів з преавторизацією. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y. Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація підтверджується автоматично). Не може бути менше поточної дати.	Ні
preauthReject	Дата автоматичного скасування преавторизації. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y. Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація скасовується автоматично). Не може бути менше поточної дати.	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
expTime	Встановлює інтервал, протягом якого замовлення може бути оплачене. Якщо значення параметру було передане, то з моменту виклику платіжної сторінки показується зворотний відлік, який видно Клієнту на сторінці оплати. По закінченню часу на оплату рахунок переходить в статус "REJECTED" і оплатити його неможливо	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»). Максимальна кількість символів 500	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".

Параметр	Опис	Обов’язковий
card	Оплата Карткою	Ні
portmone	Оплата через гаманець Portmone.com	Ні
token	Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються)	Ні
privat	Оплата через систему LiqPay, з вибором картки з Інтернет-банкінгу Приват24. Зверніть увагу! При оплаті через Приват24 функціонал преавторизації не працює	Ні
gpay	Оплата через систему Google Pay, з вибором картки з тих, що були раніше збережені в акаунті Google Pay	Ні
createtokenonly	Створення Токену для проведення платежів за Токеном (у разі активації цього параметру, інші способи не відображаються). Параметр надає можливість отримати Токен Картки без проведення реальної оплати (на рахунку блокується 1 грн, яка повертається протягом 30 хвилин). Підходить для звичайних оплат на користь Інтернет-магазину (див. розділ 4 «Оплата замовлення з використанням платіжного токену»), а також для подальшого використання у рамках платежів з картки на картку (див. розділ 5 «Переказ з картки на картку»)	Ні
gpayonly	Оплата через систему Google Pay, з вибором картки з тих, що були раніше збережені в акаунті Google Pay (у разі активації цього параметру, інші способи не відображаються – на сторінці оплати відображається тільки кнопка "Оплатити через GPay")	Ні
applepay	Оплата через систему Apple Pay, з вибором картки з тих, що були раніше збережені в акаунті Apple Pay	Ні
applepayonly	Оплата через систему Apple Pay, з вибором картки з тих, що були раніше збережені в акаунті Apple Pay (у разі активації цього параметру, інші способи не відображаються – на сторінці оплати відображається тільки кнопка "Apple Pay")	Ні
kyivstar	Оплата з балансу мобільного рахунку Київстару (тільки для передплачених номерів)	Ні
installment	Розстрочка платежу	Ні
link	Оплата методом BankPay (через застосунок Банка платника). Метод працює за умови передачі таких параметрів: expTime та "showEmail": "Y"	Ні

Зверніть увагу! Через внутрішні політики безпеки Google Pay та Apple Pay, при відкритті платіжної сторінки у WebView, гаманці Google Pay та Apple Pay можуть працювати нестабільно.
Для коректної роботи рекомендуємо пряму інтеграцію Google Pay та Apple Pay У разі наявності застосунку рекомендуємо інтегрувати SDKiOS, SDKAndroid

4. installmentPlan – параметри розстрочки платежу (див. розділ 3.7 «Розтермінування»).

5. autopayment – цей блок дозволяє налаштувати функціонал автоматичних оплат.

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

Для початку роботи з автоматичними платежами Партнеру необхідно отримати credentials в Особистому кабінеті.

Зверніть увагу! При зміні паролю необхідно сформувати credentials заново.

Після налаштування:

1. Буде створено підписку на виконання автоматичних оплат з Картки Клієнта. Portmone.com самостійно відстежує та проводить платіж. Клієнт може відключити послугу, звернувшись до підтримки Portmone.com або до співробітника Інтернет-магазину (Інтернет-магазин може самостійно видалити підписку Клієнта в Особистому кабінеті).

2. Всі наступні оплати будуть виконуватись на той же опис (description), що і при першій оплаті.

3. Номер замовлення для автоматичних оплат буде формуватись наступним чином:

   Номер замовлення при першій оплаті_RECURENT_Дата автоматичного списання

Параметр	Опис	Обов’язковий
show	Можливість для клієнта бачити на сторінці оплати деталі підписки на автоматичну оплату. Приймає значення: Y – клієнт може перейти на окрему сторінку та подивитись параметри підписки; N – клієнт не має можливості бачити деталі підписки (відображається тільки чекбокс "Зробити платіж регулярним") (див. мал. 1)	Ні
edit	Можливість для клієнта редагувати параметри автоматичної оплати. Приймає значення: Y – при переході на сторінку деталей підписки всі параметри можна редагувати, є можливість зберегти налаштування (див. мал. 2); N – відображаються параметри автоматичної оплати, що передані Інтернет-магазином, без можливості редагувати	Ні
settings	Блок параметрів для налаштування автоматичної оплати	Ні
credentials	Параметри авторизації	Так
changeCheckboxState	Значення автоплатежу Y	Так
defaultCheckboxState	Приймає значення: Y – чекбокс "Зробити платіж регулярним" автозаповнений; N – клієнт самостійно заповнює чекбокс "Зробити платіж регулярним"	Ні

Структура блоку settings:

Параметр	Опис	Обов’язковий
period	Періодичність автоматичних списань. Приймає наступні значення: 1 – щомісячно, 2 – щоквартально, 3 – щопівроку, 4 – щороку	Так
payDate	День проведення автоматичного списання. Приймає значення від 1 до 28	Ні
startDate	Дата початку автоматичних списань. Передається у форматі: DD.MM.YYYY. Якщо параметр не переданий, автоматично проставиться вчорашня дата	Ні
endDate	Дата закінчення автоматичних списань. Передається у форматі: DD.MM.YYYY. Якщо параметр не переданий, автоматично проставиться дата startDate + 3 роки (якщо startDate не задано – поточна дата платежу)	Ні
amount	Сума автооплати. При наявності дробової частини використовується розділювач крапка (".")	Так

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

Мал. 2 – приклад відображення параметрів автоматичної оплати з можливістю редагування

6. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

7. token – налаштування для роботи з Токеном (див. розділ 4 «Оплата замовлення з використанням платіжного токену»)

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Обов’язковий параметр для оплати за Токеном
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену	Обов’язковий параметр для оплати за Токеном
cardMask	Маска Картки	Обов’язковий параметр для оплати за Токеном
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Ні

8. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника (надсилаємо клієнту квитанцію про успішну оплату, не передаємо у відповідь на запит)	Ні
showEmail	"Y" або порожнє значення – вмикає відображення поля "e-mail" на сторінці оплати, "N" – приховує поле "e-mail" на сторінці оплати (значення без задання – "Y")	Ні

В залежності від переданих значень параметрів emailAddress та showEmail можливі 4 варіанти відображення поля "e-mail" на сторінці оплати:

Варіант	emailAddress	showEmail	Відображення на сторінці оплати
1	порожнє значення	Y	Відображається порожнє поле вводу e-mail
2	валідний e-mail	Y	Відображається попередньо заповнене поле вводу e-mail з можливістю редагування
3	порожнє значення	N	Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною
4	валідний e-mail	N	Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною. Однак e-mail, що переданий у запиті, обробляється і на нього надсилається квитанція про сплату

9. shipping – блок, що містить інформацію про доставку

Доставка "Нова Пошта"

Даний функціонал дозволяє оформити доставку "Нової Пошти".

Параметр	Опис	Обов’язковий
state	Y - підключається доставка, N - доставка вимкнена	Так
source	Назва служби доставки. Приймає значення novaposhta	Так

Приклад масиву в запиті:

"shipping": {
        "collect": {
            "state": "Y",
            "source": "novaposhta"
        }

Щоб передзаповнити поля на сторінці оплати необхідно передати дані Клієнта в блоці payer

"payer": {
        "lang": "uk",
        "emailAddress": "[email protected]",
        "showEmail": "Y",
        "phoneNumber": "660000000",
        "fullName": "Прізвище Ім'я"
    }

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника (надсилаємо клієнту квитанцію про успішну оплату, не передаємо у відповідь на запит)	Так
showEmail	Приймає значення "Y"	Так
phoneNumber	Номер телефону Клієнта. Передавати у форматі 660000000	Так
fullName	Прізвище та Ім'я Клієнта	Так

Доступні 3 типи доставки:

• У відділення
• До поштомату
• Кур’єром

Поля “Місто”, “Вулиця”, “Відділення”, “Поштомат” є випадаючим списком з пошуком на сторінці оплати, пошук починається після введення 3 символів. Редагувати дані доставки можна натиснувши кнопку "назад"

Доставка "Укрпошта"

Параметр	Опис	Обов’язковий
services	Найменування логістичних служб	Так
ukrposhta	Логістична служба	Так
deliveryTypes	Доступні способи доставки: W2D – доставка кур'єром на адресу одержувача; W2W – доставка до відділення	Так
senderClientId	Ідентифікатор магазину в системі логістичної служби. Створюється в Особистому кабінеті Мерчанта	Так
senderAddressId	Ідентифікатор адреси магазину в системі логістичної служби. Створюється в Особистому кабінеті Мерчанта	Так
senderPostCode	Поштовий індекс відправника	Так
type	Тип доставки відправлення. Можливі значення: STANDARD, EXPRESS	Так
parcelWeight	Вага відправлення. Вказується у грамах. Максимальне значення – 30000	Так
parcelLength	Довжина найбільшої сторони відправлення (тільки цифри), вказується в сантиметрах	Так
parcelWidth	Ширина відправлення у сантиметрах	Так
parcelHeight	Висота відправлення у сантиметрах	Так
parcelDeclaredPrice	Заявлена ціна відправлення, вказується у гривнях	Так
parcelDescription	Опис відправлення	Ні
fragile	Позначка про крихкість посилки. Можливі значення: Y або N	Ні
checkOnDelivery	Позначка про огляд при отриманні. Можливі значення: Y або N	Ні
bees	Позначка, що відправляються бджоли. Можливі значення: Y або N	Ні
payer	Вказується платник за доставку. Попередньо встановлене значення: client	Так
sms	Повідомити клієнта про прибуття посилки за допомогою SMS-повідомлення. Можливі значення: Y або N	Ні
withDeliveryNotification	Повідомити клієнта за допомогою сервісу повідомлень служби доставки. Можливі значення: Y або N	Ні
enable	Увімкнути відображення форми оформлення доставки. Можливі значення: Y або N	Так
required	Оформлення доставки є обов'язковим. Можливі значення: Y або N	Так

10. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

11. goods – блок, що містить масив даних для фіскалізації.

Параметр	Опис	Обов’язковий
internalCode	Код продавця	Так
manufacturerCode	Код виробника	Ні
govClassificationCode	Код УКТЗЕД	Ні
name	Назва товару\послуги	Так
name_en	Назва товару\послуги EN	Ні
description	Опис товару\послуги	Ні
description_en	Опис товару\послуги EN	Ні
price	Ціна ( шт)	Так
quantity	Кількість	Так
uomCode	Одиниця виміру ( не обов'язково, за замовчуванням шт)	Ні
amount	Сума	Так
taxRateCodes	Цифровий код ставки податку (попередньо програмується у особистому кабінеті податкового агента). Якщо до товару потрібно застосувати декілька податків — вказати через кому, наприклад: "1,2"	Так
descriptionUrl	Посилання на опис товару	Ні
imageUrl	Посилання на картинку товару	Ні
barcode	Штрих-код товару	Ні
serviceFlag	Ознака послуги. Визначає тип позиції в чеку для фіскалізації. N — товар	Ні
discount	Сума знижки по позиції товару в гривнях	Ні
discountName	Назва знижки	Ні

Показати приклад JSON-структури блоку goods

{
  "goods": [
    {
      "internalCode": "123456",
      "manufacturerCode": "123456",
      "govClassificationCode": "123456",
      "name": "",
      "name_en": "",
      "description": "",
      "description_en": "",
      "price": "100",
      "quantity": "2",
      "uomCode": "",
      "amount": "200",
      "serviceFlag": "N",
      "taxRateCodes": "1",
      "descriptionUrl": "",
      "imageUrl": "",
      "barcode": "1234567890",
      "discount": "10.00",
      "discountName": "Знижка"
    }
  ]
}

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

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

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
APPROVALCODE	Код авторизації
BILL_AMOUNT	Передана у запиті сума транзакції
TOKEN	Значення Токену для подальших оплат
RESULT	Результат виконання операції (у разі успіху = 0)
CARD_MASK	Маска Картки платника
ATTRIBUTE1	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE2	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE3	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE4	Службове поле, заповнюється на розсуд компанії
RECEIPT_URL	Посилання для отримання квитанції
LANG	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
DESCRIPTION	Коментар до замовлення / опис призначення оплати. До 250 символів
ERRORIPSCODE	Код помилки, якщо токен Visa не був створений
ERRORIPSMESSAGE	Текст помилки, якщо токен Visa не був створений

3.3. Управління зовнішнім виглядом сторінки оплати

Зовнішній вигляд сторінки оплати можна налаштовувати за допомогою параметру style.

Опис полів параметру style

Поле	Опис	Тип стилю сторінки (type), для якого може застосовуватись поле
type	Встановлює тип стилю для сторінки оплати: • portmone – значення без задання (стандартний стиль portmone.com, див. мал. 3); • brand – повна стилізація сторінки для партнера (див. мал. 4); • co-brand – логотип партнера на сторінці наведений разом з логотипом portmone.com (див. мал. 5); • light – версія для відображення у вигляді фрейму (див. мал. 6). Інструкцію з вбудовування платіжної сторінки у фрейм див. нижче
logo	Містить полсилання на логотип партнера. Підтримує тільки посилання з https схемою. Формат зображення тільки SVG, PNG. Рекомендується використовувати зображення з мінімальним відступом сюжету від усіх країв	brand, co-brand
logoWidth	Параметр, що визначає ширину логотипу. Необхідно вводити у вигляді "100px", максимальне рекомендоване значення 300px	brand, co-brand
logoHeight	Параметр, що визначає висоту логотипу. Необхідно вводити у вигляді "100px", максимальне рекомендоване значення 50px (для формата PNG максимальна висота – 53px)	brand, co-brand
backgroundColorHeader	Встановлює колір секції header на сторінці. Формат вводу – HEX (наприклад, #ff0000)	brand, light
backgroundColorButtons	Встановлює колір кнопок. Формат вводу – HEX (наприклад, #ff0000)	brand, light
colorTextAndIcons	Встановлює колір тексту та іконок. Формат вводу – HEX (наприклад, #ff0000)	brand, light
borderColorList	Встановлює колір ліній у списку методів проведення платежів. Формат вводу – HEX (наприклад, #ff0000)	brand, light
bcMain	Визначає колір фону сторінок. Формат вводу – HEX (наприклад, #ff0000)	brand, light
privatButtonPosition	У разі використання методу оплати "privat", цей параметр визначає розміщення кнопки Privat24 на платіжній формі. Розташування кнопки може бути задано одним із трьох варіантів: "top" (угорі платіжної форми), "middle" (посередині платіжної форми) або "bottom" (унизу платіжної форми). За замовчуванням використовується значення "bottom".	portmone, brand, light, co-brand

Приклади варіантів відображення кнопки оплати Privat24

Показати приклад розміщення кнопки оплати Privat24 зверху сторінки

Показати приклад розміщення кнопки оплати Privat24 посередині сторінки

Показати приклад розміщення кнопки оплати Privat24 внизу сторінки

Інструкція з вбудовування платіжної сторінки у фрейм

Зверніть увагу! Через внутрішні політики безпеки Google Pay та Apple Pay, при відкритті платіжної сторінки у WebView, гаманці Google Pay та Apple Pay можуть працювати нестабільно.
Для коректної роботи рекомендуємо пряму інтеграцію Google Pay та Apple Pay У разі наявності застосунку рекомендуємо інтегрувати SDKiOS, SDKAndroid

Для запуску IFRAME на сайті необхідно:

1. На сторінці партнера необхідно організувати можливість надсилання запиту на проведення оплати, наприклад, вставити форму наступного вигляду:

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="myFrame"
>
  <input
    type="hidden"
    name="bodyRequest"
    value='{
            "paymentTypes": {
                "card": "Y",
                "portmone": "Y",
                "token": "N",
                "createtokenonly": "N"
            },
            "priorityPaymentTypes": {
                "card": "1",
                "portmone": "2",
                "token": "0",
                "createtokenonly": "0"
            },
            "payee": {
                "payeeId": "1185",
                "login": "",
                "dt": "",
                "signature": "",
                "shopSiteId": ""
            },
            "order": {
                "description": "Test Payment",
                "shopOrderNumber": "SHP-00445401",
                "billAmount": "10",
                "attribute1": "1",
                "attribute2": "2",
                "attribute3": "3",
                "attribute4": "4",
                "attribute5": "",
                "successUrl": "",
                "failureUrl": "",
                "preauthFlag": "N",
                "billCurrency": "UAH",
                "encoding": ""
            },
            "token": {
                "tokenFlag": "N",
                "returnToken": "N",
                "token": "",
                "cardMask": "",
                "otherPaymentMethods": "Y",
                "sellerToken": ""
            },
            "payer": {
                "lang": "uk",
                "emailAddress": "[email protected]"
            },
            "style": {
                "type": "light",
                "logo": "",
                "backgroundColorHeader": "",
                "backgroundColorButtons": "",
                "colorTextAndIcons": "",
                "borderColorList": "",
                "bcMain": ""
            }
        }'
  />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Portmone.com" />
</form>

Структуру та опис параметрів запиту можна подивитись у розділі 3.2 «Запит у форматі JSON».

Для відображення фрейму у стилі light необхідно задати полю type параметру style значення "light".

Параметр target форми повинен вказувати на фрейм, в якому буде відображатись сторінка оплати (у наведеному вище прикладі це фрейм з ім'ям "myFrame").

2. Додати у DOM-модель сторінки елемент IFRAME, вказавши йому парамeтр name зі значенням, ідентичним параметру target форми з попереднього пункту.

<div>
  <iframe name="myFrame" width="50%" height="70%" frameborder="0"></iframe>
</div>

Параметри ширини та висоти фрейму можна налаштовувати за бажанням.

3. Після надсилання запиту, відповідь буде відображено у вказаному фреймі.

Способи виведення сторінки оплати:

Мал. 3 – стандартний стиль Portmone.com

Мал. 4 – повна стилізація сторінки для партнера

Мал. 5 – логотип партнера на сторінці наведений разом з логотипом Portmone.com

Мал. 6 – версія для відображення у вигляді фрейму на сайті Інтернет-магазину

3.4. Платіжний віджет

Призначення: Платіжний віджет дозволяє приймати платежі без перенаправлення клієнта на окрему сторінку Portmone. Оплата відбувається на сайті мерчанта у зручному для користувача форматі.

Платіжний віджет підтримує два режими роботи:

• Модальне вікно (popup): після натискання кнопки відкривається окреме спливаюче вікно браузера з платіжною сторінкою Portmone.
• Вбудований фрейм (iframe): платіжна форма відображається безпосередньо на сторінці мерчанта у вбудованому iframe.

3.4.1 Оплата у модальному вікні (popup)

Доступність і обмеження: Немає обмежень.

Інтеграція платіжної кнопки: Для розміщення платіжної кнопки Portmone на сторінці Мерчанта необхідно визначити місце розташування кнопки на сторінці та вставити JavaScript код для підключення скрипта і ініціалізації віджета.

Після завантаження скрипту pg.min.js платіжна кнопка буде розміщена в тому блоці, в якому розміщений код для завантаження скрипту.

Приклад:

<div class="span4">
  <script src="https://www.portmone.com.ua/r3/resources/pg/js/asset/pg.min.js?v=15092019"></script>
  <script type="text/javascript" id="portmone-script">
    var data = {};
    var brand = {
      height: "40px",
      width: "150px",
      buttoncolor: "#FF0000",
      fontfamily: "Open Sans",
      textcolor: "#FFF",
      lang: "uk",
      padding: "5px",
      border: "1px solid grey",
      fontsize: "14px",
      closemodal: "Y",
    };
    PG.success(function (data) {
      console.log(JSON.stringify(data));
    });
    PG.paymentData("gateway", data);
    PG.brandButton(brand);
  </script>
</div>

Брендування платіжної кнопки

Об'єкт brand відповідає за брендування кнопки «Оплатити», при натистканні якої відбувається виклик вікна оплати.

Параметр	Опис	Обов’язковий
height	Встановлює висоту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
width	Встановлює ширину кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
buttoncolor	Встановлює колір кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
fontfamily	Встановлює тип шрифту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
textcolor	Встановлює колір шрифту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
lang	Встановлює мову для відображення тексту кнопки “Сплатити”/ “Завантажити квитанцію”. Якщо інше не було задане, приймає значення uk – українська	Ні
padding	Встановлює значення полів навколо вмісту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
border	Дозволяє одночасно встановити товщину, стиль і колір рамки навколо кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
fontsize	Встановлює розмір шрифту. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
closemodal	Опція, що визначає, чи потрібно закривати модальне вікно після здійснення платежу клієнтом. При значенні "N" вікно не закривається, клієнту відображається повідомлення про успішну оплату у модальному вікні. При значенні "Y" – вікно закривається та виконується передача даних платежу до функції обробки мерчанта. Значення без задання: Y	Ні

Ініціалізація платіжного віджета: Для ініціалізації віджета необхідно передати об’єкт data, який містить інформацію про продавця, параметри замовлення та методи оплати.

Приклад об’єкта data наведено у розділі "3.4.1 Приклад об’єкта data для режиму popup"

Опис параметрів об’єкту data:

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
displayMessage	Відображення інформації на платіжній сторінці для клієнта:<font style=\"font-size:14px;\">Hello</font> %username% !	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Опис платежу (коментар до замовлення/призначення. Максимальна кількість символів 250 оплати)	Ні
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів 128	Ні
billAmount	Сума платежу	Так
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
preauthConfirm	Дата автоматичного списання заблокованих коштів для платежів з преавторизацією. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y. Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація підтверджується автоматично). Не може бути менше поточної дати.	Ні
preauthReject	Дата автоматичного скасування преавторизації. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y. Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація скасовується автоматично). Не може бути менше поточної дати.	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
expTime	Встановлює інтервал, протягом якого замовлення може бути оплачене. Якщо значення параметру було передане, то з моменту виклику платіжної сторінки показується зворотний відлік, який видно Клієнту на сторінці оплати. По закінченню часу на оплату рахунок переходить в статус "REJECTED" і оплатити його неможливо	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу. Максимальна кількість символів 500. (див. розділ 7 «Розщеплення платежу»)	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".

Параметр	Опис	Обов’язковий
card	Оплата Карткою	Ні
portmone	Оплата через гаманець Portmone.com	Ні
token	Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються)	Ні
privat	Оплата через систему LigPay, з вибором картки з Інтернет-банкінгу Приват24	Ні
gpay	Оплата через систему Google Pay, з вибором картки з тих, що були раніше збережені в акаунті Google Pay	Ні
createtokenonly	Створення Токену для проведення платежів за Токеном (у разі активації цього параметру, інші способи не відображаються). Параметр надає можливість отримати Токен Картки без проведення реальної оплати (на рахунку блокується 1 грн, яка повертається протягом 30 хвилин). Підходить для звичайних оплат на користь Інтернет-магазину (див. розділ 4 «Оплата замовлення з використанням платіжного токену»), а також для подальшого використання у рамках платежів з картки на картку (див. розділ 5 «Переказ з картки на картку»)	Ні
gpayonly	Оплата через систему Google Pay, з вибором картки з тих, що були раніше збережені в акаунті Google Pay (у разі активації цього параметру, інші способи не відображаються – на сторінці оплати відображається тільки кнопка "Оплатити через GPay")	Ні
applepay	Оплата через систему Apple Pay, з вибором картки з тих, що були раніше збережені в акаунті Apple Pay	Ні
applepayonly	Оплата через систему Apple Pay, з вибором картки з тих, що були раніше збережені в акаунті Apple Pay (у разі активації цього параметру, інші способи не відображаються – на сторінці оплати відображається тільки кнопка "Apple Pay")	Ні
installment	Розстрочка платежу (Розтермінування)	Ні
link	Оплата методом BankPay (через застосунок Банка платника). Метод працює за умови передачі таких параметрів: expTime та "showEmail": "Y"	Ні

4. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

5. token – налаштування для роботи з Токеном (див. розділ 4 «Оплата замовлення з використанням платіжного токену»)

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Обов’язковий параметр для оплати за Токеном
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену	Обов’язковий параметр для оплати за Токеном
cardMask	Маска Картки	Обов’язковий параметр для оплати за Токеном
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Ні

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні
showEmail	"Y" або порожнє значення – вмикає відображення поля "e-mail" на сторінці оплати, "N" – приховує поле "e-mail" на сторінці оплати (значення без задання – "Y")	Ні

В залежності від переданих значень параметрів emailAddress та showEmail можливі 4 варіанти відображення поля "e-mail" на сторінці оплати:

Варіант	emailAddress	showEmail	Відображення на сторінці оплати
1	порожнє значення	Y	Відображається порожнє поле вводу e-mail
2	валідний e-mail	Y	Відображається попередньо заповнене поле вводу e-mail з можливістю редагування
3	порожнє значення	N	Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною
4	валідний e-mail	N	Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною. Однак e-mail, що переданий у запиті, обробляється і на нього надсилається квитанція про сплату

7. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

8. goods – необов’язковий блок, що містить масив даних для фіскалізації.

Параметр	Опис	Обов’язковий
internalCode	Код продавця	Так
manufacturerCode	Код виробника	Ні
govClassificationCode	Код УКТЗЕД	Ні
name	Назва товару\послуги	Так
name_en	Назва товару\послуги EN	Ні
description	Опис товару\послуги	Ні
description_en	Опис товару\послуги EN	Ні
price	Ціна ( шт)	Так
quantity	Кількість	Так
uomCode	Одиниця виміру ( не обов'язково, за замовчуванням шт)	Ні
amount	Сума	Так
taxRateCodes	Цифровий код ставки податку (попередньо програмується у особистому кабінеті податкового агента). Якщо до товару потрібно застосувати декілька податків — вказати через кому, наприклад: "1,2"	Так
descriptionUrl	Посилання на опис товару	Ні
imageUrl	Посилання на картинку товару	Ні
barcode	Штрих-код товару	Ні
serviceFlag	Ознака послуги. Визначає тип позиції в чеку для фіскалізації. N — товар	Ні
discount	Сума знижки по позиції товару в гривнях	Ні
discountName	Назва знижки	Ні

9. installmentPlan – параметри розстрочки платежу (див. розділ 3.7 «Розтермінування»).

Службові функції:

1. PG.success – функція, що приймає об’єкт даних data, який описує проведений платіж. У випадку, якщо Мерчант не проводить обробку даних, платіжна кнопка змінює свій стан та назву, що дозволяє платнику завантажити квитанцію при натисканні на неї.

2. PG.brandButton – функція, що приймає об’єкт даних, який описує та стилізує платіжну кнопку.

3. PG.paymentData – функція, що ініціалізує та розміщує платіжну кнопку на сторінці Мерчанта.

Ця функція приймає наступні аргументи:

PG.paymentData(typePayment, data, typeView);

Де:

1) typePayment – рядок, що характеризує тип проведення платежу та може набувати наступних значень:

Значення	Опис
gateway	Цей тип платежу дозволяє створити та провести типовий платіж на основі переданих даних. Об’єкт data формується як для звичайного запиту на основі json
stock	Цей тип платежу передбачає проведення платежу на основі переданого ідентифікатора продукту, що був створений в Особистому кабінеті Мерчанта. В цьому випадку об’єкт data набуває наступної структури: var data = { "id":"303429c03b3a743bdf8ee02" };
terminal	Цей тип платежу зберігає обробку властивостей об’єкту data, що передаються при оплаті з використанням типу terminal, але дозволяє залишати billAmount, description, attribute1, attribute2, attribute3, attribute4 незаповненими для подальшої ініціалізації цих даних платником
p2p	Цей тип платежу передбачає проведення платежу із зарахуванням коштів на картку Мерчанта, що була перевірена та додана в Особистому кабінеті Мерчанта. В цьому випадку об’єкт data набуває наступної структури: var data = { "hash":"" };, де hash – значення з посилання на переказ

2) typeView – рядок, що характеризує вигляд модального вікна та може набувати наступних значень:

• modal – відкриває вікно оплати у новому вікні браузера з заданими розмірами (див. мал. 7).
• frame – відкриває вікно оплати у фреймі (див. мал. 8);

4. PG.create – функція, що створює платіжний фрейм на основі даних, що були передані у функцію PG. paymentData. Цю функцію можна використовувати у випадку, коли Мерчант створює власні механізми виклику платіжного фрейму. Не містить жодних аргументів.

5. PG.setButtonId – функція пропонується для випадків, коли Мерчант сам проводить стилізацію кнопки виклику фрейму та ініціалізує власний текст на кнопці. Ця функція приймає в якості аргументу html-атрибут id кнопки Мерчанта. Наприклад: PG.setButtonId('paymentButton');. Після цього, у разі натискання на кнопку, Мерчанту буде відкриватися платіжний фрейм Portmone.

Цю функцію необхідно використовувати у комбінації с функцією PG.create.

Приклад:

• створення фрейму на основі налаштувань із функції PG. paymentData

PG.paymentData("gateway",data,"frame"); PG.create();

• встановлення id кнопки Мерчанта

PG.setButtonId('paymentButton');

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

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

Опис параметрів, що надійдуть до функції обробки:

Параметр	Опис
status	Статус транзакції. Приймає значення PAYED
errorCode	Код помилки
error	Залишається незаповненим
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
billAmount	Сума платежу
shopOrderNumber	Номер замовлення (рахунку) у системі Мерчанта
cardMask	Маска Картки платника
attribute1	Службове поле
attribute2	Службове поле
attribute3	Службове поле
attribute4	Службове поле
receiptLink	Посилання для отримання квитанції
lang	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
description	Коментар до замовлення / опис призначення оплати. До 250 символів
token	Токен платіжної картки
commission	Комісія при проведенні платежу
payeeName	Назва Мерчанта
billCurrency	Валюта проведення платежу
IPSTokenValue	Унікальний токен Visa
errorIPSCode	Код помилки, якщо токен Visa не був створений
errorIPSMessage	Текст помилки, якщо токен Visa не був створений

Мал. 7 – приклад вікна оплати у новому вікні браузера з заданими розмірами

3.4.2 Оплата у вбудованому фреймі (iframe)

Технічні вимоги та налаштування Apple Pay: Для Apple Pay існують обмеження на рівні браузерів: у вбудованому iframe кнопка Apple Pay може працювати нестабільно або не відображатися взагалі. Це пов’язано з політикою безпеки Apple, яка вимагає прямої взаємодії з користувачем та перевірки домену мерчанта.

• Щоб забезпечити стабільну роботу Apple Pay у iframe, необхідно:

1. Створити сертифікати Apple та пройти верифікацію домену згідно інструкції.
2. У об'єкті ініціалізації платежу data в блоці payee передавати додаткові параметри, які ідентифікують мерчанта у системі Apple: appleMerchantName — унікальний Merchant ID, створений у кабінеті Apple Developer під час налаштування Apple Pay; appleMerchantLabel — назва, що відображається користувачу у вікні Apple Pay під час вибору картки.

• Для коректної роботи Apple Pay з QR-кодом підключіть офіційну бібліотеку apple-pay-js. Посилання на документацію Apple

<head>
  <script
    crossorigin
    src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"
    crossorigin="anonymous"
  ></script>
</head>

• Потрібно розміщати iframe у верхній структурі DOM-дерева сторінки. Для цього:

1. Створіть div і задайте йому унікальний id.
2. Розташуйте цей div на верхніх рівнях DOM-структури
3. У об'єкті ініціалізації платежу data передайте параметр frameHolderId зі значенням, яке відповідає id створеного елемента.

"frameHolderId": "paymentFrame1"

Інструкція з налаштування сертифікатів Apple Pay та верифікації домену:

Ознайомтесь з відео-інструкцією, яка детально пояснює реєстрацію та перевірку у системі Apple Pay. Детальна відео-інструкція з налаштування Apple Pay.

1. Реєстрація Merchant ID
Ідентифікатор мерчанта унікально ідентифікує вас в Apple Pay як мерчанта, який може приймати платежі. Ідентифікатор мерчанта ніколи не втрачає чинності, і ви можете використовувати один і той самий ідентифікатор для кількох додатків.

• Увійдіть до облікового запису Apple Developer Account.
• Перейдіть у розділ Certificates, Identifiers & Profiles.
• Натисніть Identifiers у боковій панелі, а потім кнопку додавання (+) у верхньому лівому куті.
• Виберіть Merchant IDs, а потім натисніть Continue.
• Введіть Description та Identifier*, після чого натисніть Continue.
• Перегляньте налаштування та натисніть Register.
• Надішліть ваш Merchant ID до Portmone на адресу: [email protected].
• Отримайте зворотнім листом CSR-файл, сформований Portmone, який буде необхідним для створення Apple Pay Payment Processing Certificate.

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

2. Створення Apple Pay Payment Processing Certificate

Apple Pay Payment Processing Certificate пов’язаний з вашим ідентифікатором мерчанта та використовується для шифрування платіжної інформації. Термін дії сертифіката обробки платежів закінчується кожні 25 місяців. Якщо сертифікат буде відкликано, ви можете створити його знову.

• Увійдіть до облікового запису Apple Developer Account.
• У розділі Certificates, Identifiers & Profiles натисніть Identifiers у боковій панелі.
• У розділі Identifiers використайте фільтр у верхньому правому куті та виберіть Merchant IDs.
• Справа оберіть ваш ідентифікатор мерчанта*.
• У розділі Apple Pay Payment Processing Certificate натисніть Create Certificate.
• Завантажте CSR-файл, отриманий від Portmone, натиснувши Choose File, а потім Continue.
• Натисніть Download.
• Надішліть завантажений сертифікат (apple_pay.cer) до Portmone на адресу: [email protected].

Примітка:
Якщо у верхній частині сторінки з’являється банер із повідомленням про необхідність прийняття угоди, натисніть кнопку Review Agreement та дотримуйтесь інструкцій перед продовженням.

3. Реєстрація та верифікація домену

• Увійдіть до облікового запису Apple Developer Account.
• У розділі Certificates, Identifiers & Profiles натисніть Identifiers у боковій панелі, а потім виберіть Merchant IDs у випадаючому меню у верхньому правому куті.
• Оберіть ваш Merchant ID.
• У розділі Merchant Domains натисніть Add Domain.
• Введіть назву свого домену та натисніть Save.
• Завантажте файл apple-developer-merchantid-domain-association.txt.
• Розмістіть файл у кореневій директорії вашого домену за наступним шляхом:

  https://<your-domain>/.well-known/apple-developer-merchantid-domain-association.txt
• Переконайтесь, що файл доступний через браузер за вказаним URL.
• Натисніть Verify.
• Якщо все налаштовано правильно, статус домену зміниться на Verified.

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

4. Створення Apple Pay Merchant Identity Certificate
Для роботи з Apple Pay необхідний Merchant Identity Certificate. Цей сертифікат забезпечує безпечне здійснення операцій і ідентифікує мерчанта. Також він потрібний для створення Apple Pay Payment Session під час верифікації магазину.

Перед створенням Apple Pay Merchant Identity Certificate вам необхідно отримати Certificate Signing Request (CSR). Це можна зробити одним із декількох способів:

• Отримання CSR і приватного ключа від Portmone. (Рекомендований спосіб)
  Надішліть лист на адресу: [email protected] із запитом на отримання CSR для створення Apple Pay Merchant Identity Certificate, у відповідь отримайте підготовлений CSR-файл, що відповідає вимогам Apple, разом із приватним ключем. Цей спосіб є рекомендованим, оскільки він спрощує процес і гарантує сумісність.

• Самостійна генерація CSR та приватного ключа

  Є декілька шляхів самостійного створення CSR та приватного ключа: використання Keychain Access на macOS (посилання на інструкцію Apple.) або через OpenSSL. Нижче наведено інструкцію для створення за допомогою Keychain Access:

  • Відкрийте Keychain Access, що знаходиться в /Applications/Utilities.
  • У меню оберіть: Keychain Access → Certificate Assistant → Request a Certificate from a Certificate Authority.
  • У вікні, що з'явиться, заповніть поля:
    • User Email Address: вкажіть вашу електронну пошту.
    • Common Name: введіть назву ключа.
    • CA Email Address: залиште пустим.
  • Оберіть опцію I will provide the key pair information, щоб вручну створити пару ключів, необхідних для CSR.
  • Оберіть опцію Saved to disk і натисніть Continue. Збережіть файл із розширенням .certSigningRequest.
  • Використовуйте алгоритм і розмір ключа: RSA(2048). Apple Pay on the Web troubleshooting guide / Create a merchant identity certificate

Після отримання CSR виконайте наступні дії для створення сертифікату:

• Увійдіть до облікового запису Apple Developer Account.
• У розділі Certificates, Identifiers & Profiles натисніть Identifiers у боковій панелі, а потім виберіть Merchant IDs у випадаючому меню у верхньому правому куті.
• У списку знайдіть створений Merchant ID та натисніть на нього.
• У розділі Apple Pay Merchant Identity Certificate натисніть Create Certificate.
• Завантажте CSR-файл, натиснувши Choose File, оберіть файл і натисніть Continue.
• Завершіть процес, натиснувши Download, щоб зберегти готовий сертифікат.
• Надішліть згенерований сертифікат (merchant_id.cer) та приватний ключ (якщо ви генерували його самостійно) до Portmone на адресу [email protected].

Інтеграція платіжної кнопки: Для розміщення платіжної кнопки Portmone на сторінці Мерчанта необхідно визначити місце розташування кнопки на сторінці та вставити JavaScript код для підключення скрипта і ініціалізації віджета.

Після завантаження скрипту pg.min.js платіжна кнопка буде розміщена в тому блоці, в якому розміщений код для завантаження скрипту.

Приклад:

<div class="span4">
  <script src="https://www.portmone.com.ua/r3/resources/pg/js/asset/pg.min.js?v=15092019"></script>
  <script type="text/javascript" id="portmone-script">
    var data = {};
    var brand = {
      height: "40px",
      width: "150px",
      buttoncolor: "#FF0000",
      fontfamily: "Open Sans",
      textcolor: "#FFF",
      lang: "uk",
      padding: "5px",
      border: "1px solid grey",
      fontsize: "14px",
      closemodal: "Y",
    };
    PG.success(function (data) {
      console.log(JSON.stringify(data));
    });
    PG.paymentData("gateway", data);
    PG.brandButton(brand);
  </script>
</div>

Брендування платіжної кнопки

Об'єкт brand відповідає за брендування кнопки «Оплатити», при натистканні якої відбувається виклик вікна оплати.

Параметр	Опис	Обов’язковий
height	Встановлює висоту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
width	Встановлює ширину кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
buttoncolor	Встановлює колір кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
fontfamily	Встановлює тип шрифту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
textcolor	Встановлює колір шрифту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
lang	Встановлює мову для відображення тексту кнопки “Сплатити”/ “Завантажити квитанцію”. Якщо інше не було задане, приймає значення uk – українська	Ні
padding	Встановлює значення полів навколо вмісту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
border	Дозволяє одночасно встановити товщину, стиль і колір рамки навколо кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
fontsize	Встановлює розмір шрифту. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці	Ні
closemodal	Опція, що визначає, чи потрібно закривати модальне вікно після здійснення платежу клієнтом. При значенні "N" вікно не закривається, клієнту відображається повідомлення про успішну оплату у модальному вікні. При значенні "Y" – вікно закривається та виконується передача даних платежу до функції обробки мерчанта. Значення без задання: Y	Ні

Ініціалізація платіжного віджета: Для роботи віджета необхідно передати об’єкт data, який містить інформацію про продавця, параметри замовлення та методи оплати.

Приклад об’єкта data наведено у розділі "3.4.2 Приклад об’єкта data для режиму iframe"

Опис параметрів об’єкту data:

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
appleMerchantName	Ідентифікатор продавця Apple - Merchant ID	Так
appleMerchantLabel	Назва, яка буде відображатися клієнту в Apple pay при виборі картки.	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
displayMessage	Відображення інформації на платіжній сторінці для клієнта:<font style=\"font-size:14px;\">Hello</font> %username% !	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Опис платежу (коментар до замовлення/призначення. Максимальна кількість символів 250 оплати)	Ні
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів 128	Ні
billAmount	Сума платежу	Так
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
preauthConfirm	Дата автоматичного списання заблокованих коштів для платежів з преавторизацією. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y. Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація підтверджується автоматично). Не може бути менше поточної дати.	Ні
preauthReject	Дата автоматичного скасування преавторизації. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y. Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація скасовується автоматично). Не може бути менше поточної дати.	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
expTime	Встановлює інтервал, протягом якого замовлення може бути оплачене. Якщо значення параметру було передане, то з моменту виклику платіжної сторінки показується зворотний відлік, який видно Клієнту на сторінці оплати. По закінченню часу на оплату рахунок переходить в статус "REJECTED" і оплатити його неможливо	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу. Максимальна кількість символів 500. (див. розділ 7 «Розщеплення платежу»)	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".

Параметр	Опис	Обов’язковий
card	Оплата Карткою	Ні
portmone	Оплата через гаманець Portmone.com	Ні
token	Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються)	Ні
privat	Оплата через систему LigPay, з вибором картки з Інтернет-банкінгу Приват24	Ні
gpay	Оплата через систему Google Pay, з вибором картки з тих, що були раніше збережені в акаунті Google Pay	Ні
createtokenonly	Створення Токену для проведення платежів за Токеном (у разі активації цього параметру, інші способи не відображаються). Параметр надає можливість отримати Токен Картки без проведення реальної оплати (на рахунку блокується 1 грн, яка повертається протягом 30 хвилин). Підходить для звичайних оплат на користь Інтернет-магазину (див. розділ 4 «Оплата замовлення з використанням платіжного токену»), а також для подальшого використання у рамках платежів з картки на картку (див. розділ 5 «Переказ з картки на картку»)	Ні
gpayonly	Оплата через систему Google Pay, з вибором картки з тих, що були раніше збережені в акаунті Google Pay (у разі активації цього параметру, інші способи не відображаються – на сторінці оплати відображається тільки кнопка "Оплатити через GPay")	Ні
applepay	Оплата через систему Apple Pay, з вибором картки з тих, що були раніше збережені в акаунті Apple Pay	Ні
applepayonly	Оплата через систему Apple Pay, з вибором картки з тих, що були раніше збережені в акаунті Apple Pay (у разі активації цього параметру, інші способи не відображаються – на сторінці оплати відображається тільки кнопка "Apple Pay")	Ні
installment	Розстрочка платежу (Розтермінування)	Ні
link	Оплата методом BankPay (через застосунок Банка платника). Метод працює за умови передачі таких параметрів: expTime та "showEmail": "Y"	Ні

4. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

5. token – налаштування для роботи з Токеном (див. розділ 4 «Оплата замовлення з використанням платіжного токену»)

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Обов’язковий параметр для оплати за Токеном
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену	Обов’язковий параметр для оплати за Токеном
cardMask	Маска Картки	Обов’язковий параметр для оплати за Токеном
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Ні

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні
showEmail	"Y" або порожнє значення – вмикає відображення поля "e-mail" на сторінці оплати, "N" – приховує поле "e-mail" на сторінці оплати (значення без задання – "Y")	Ні

В залежності від переданих значень параметрів emailAddress та showEmail можливі 4 варіанти відображення поля "e-mail" на сторінці оплати:

Варіант	emailAddress	showEmail	Відображення на сторінці оплати
1	порожнє значення	Y	Відображається порожнє поле вводу e-mail
2	валідний e-mail	Y	Відображається попередньо заповнене поле вводу e-mail з можливістю редагування
3	порожнє значення	N	Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною
4	валідний e-mail	N	Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною. Однак e-mail, що переданий у запиті, обробляється і на нього надсилається квитанція про сплату

7. style – налаштування стилів сторінки оплати.

Зовнішній вигляд сторінки оплати можна налаштовувати за допомогою параметру style.

Опис полів параметру style

Поле	Опис	Тип стилю сторінки (type), для якого може застосовуватись поле
type	Встановлює тип стилю для сторінки оплати: • portmone – значення без задання (стандартний стиль portmone.com, див. мал. 3); • brand – повна стилізація сторінки для партнера (див. мал. 4); • co-brand – логотип партнера на сторінці наведений разом з логотипом portmone.com (див. мал. 5); • light – версія для відображення у вигляді фрейму (див. мал. 6). Інструкцію з вбудовування платіжної сторінки у фрейм див. нижче
logo	Містить полсилання на логотип партнера. Підтримує тільки посилання з https схемою. Формат зображення тільки SVG, PNG. Рекомендується використовувати зображення з мінімальним відступом сюжету від усіх країв	brand, co-brand
logoWidth	Параметр, що визначає ширину логотипу. Необхідно вводити у вигляді "100px", максимальне рекомендоване значення 300px	brand, co-brand
logoHeight	Параметр, що визначає висоту логотипу. Необхідно вводити у вигляді "100px", максимальне рекомендоване значення 50px (для формата PNG максимальна висота – 53px)	brand, co-brand
backgroundColorHeader	Встановлює колір секції header на сторінці. Формат вводу – HEX (наприклад, #ff0000)	brand, light
backgroundColorButtons	Встановлює колір кнопок. Формат вводу – HEX (наприклад, #ff0000)	brand, light
colorTextAndIcons	Встановлює колір тексту та іконок. Формат вводу – HEX (наприклад, #ff0000)	brand, light
borderColorList	Встановлює колір ліній у списку методів проведення платежів. Формат вводу – HEX (наприклад, #ff0000)	brand, light
bcMain	Визначає колір фону сторінок. Формат вводу – HEX (наприклад, #ff0000)	brand, light
privatButtonPosition	У разі використання методу оплати "privat", цей параметр визначає розміщення кнопки Privat24 на платіжній формі. Розташування кнопки може бути задано одним із трьох варіантів: "top" (угорі платіжної форми), "middle" (посередині платіжної форми) або "bottom" (унизу платіжної форми). За замовчуванням використовується значення "bottom".	portmone, brand, light, co-brand
closeVisible	Дозволяє керувати відображенням кнопки "закрити" у платіжному фреймі. Приймає значення "Y" або "N".	portmone, brand, light, co-brand

8. goods – необов’язковий блок, що містить масив даних для фіскалізації.

Параметр	Опис	Обов’язковий
internalCode	Код продавця	Так
manufacturerCode	Код виробника	Ні
govClassificationCode	Код УКТЗЕД	Ні
name	Назва товару\послуги	Так
name_en	Назва товару\послуги EN	Ні
description	Опис товару\послуги	Ні
description_en	Опис товару\послуги EN	Ні
price	Ціна ( шт)	Так
quantity	Кількість	Так
uomCode	Одиниця виміру ( не обов'язково, за замовчуванням шт)	Ні
amount	Сума	Так
taxRateCodes	Цифровий код ставки податку (попередньо програмується у особистому кабінеті податкового агента). Якщо до товару потрібно застосувати декілька податків — вказати через кому, наприклад: "1,2"	Так
descriptionUrl	Посилання на опис товару	Ні
imageUrl	Посилання на картинку товару	Ні
barcode	Штрих-код товару	Ні
serviceFlag	Ознака послуги. Визначає тип позиції в чеку для фіскалізації. N — товар	Ні
discount	Сума знижки по позиції товару в гривнях	Ні
discountName	Назва знижки	Ні

9. installmentPlan – параметри розстрочки платежу (див. розділ 3.7 «Розтермінування»).

Службові функції:

1. PG.success – функція, що приймає об’єкт даних data, який описує проведений платіж. У випадку, якщо Мерчант не проводить обробку даних, платіжна кнопка змінює свій стан та назву, що дозволяє платнику завантажити квитанцію при натисканні на неї.

2. PG.brandButton – функція, що приймає об’єкт даних, який описує та стилізує платіжну кнопку.

3. PG.paymentData – функція, що ініціалізує та розміщує платіжну кнопку на сторінці Мерчанта.

Ця функція приймає наступні аргументи:

PG.paymentData(typePayment, data, typeView);

Де:

1) typePayment – рядок, що характеризує тип проведення платежу та може набувати наступних значень:

Значення	Опис
gateway	Цей тип платежу дозволяє створити та провести типовий платіж на основі переданих даних. Об’єкт data формується як для звичайного запиту на основі json
stock	Цей тип платежу передбачає проведення платежу на основі переданого ідентифікатора продукту, що був створений в Особистому кабінеті Мерчанта. В цьому випадку об’єкт data набуває наступної структури: var data = { "id":"303429c03b3a743bdf8ee02" };
terminal	Цей тип платежу зберігає обробку властивостей об’єкту data, що передаються при оплаті з використанням типу terminal, але дозволяє залишати billAmount, description, attribute1, attribute2, attribute3, attribute4 незаповненими для подальшої ініціалізації цих даних платником
p2p	Цей тип платежу передбачає проведення платежу із зарахуванням коштів на картку Мерчанта, що була перевірена та додана в Особистому кабінеті Мерчанта. В цьому випадку об’єкт data набуває наступної структури: var data = { "hash":"" };, де hash – значення з посилання на переказ

2) typeView – рядок, що характеризує вигляд модального вікна та може набувати наступних значень:

• modal – відкриває вікно оплати у новому вікні браузера з заданими розмірами (див. мал. 7).
• frame – відкриває вікно оплати у фреймі (див. мал. 8);

4. PG.create – функція, що створює платіжний фрейм на основі даних, що були передані у функцію PG. paymentData. Цю функцію можна використовувати у випадку, коли Мерчант створює власні механізми виклику платіжного фрейму. Не містить жодних аргументів.

5. PG.setButtonId – функція пропонується для випадків, коли Мерчант сам проводить стилізацію кнопки виклику фрейму та ініціалізує власний текст на кнопці. Ця функція приймає в якості аргументу html-атрибут id кнопки Мерчанта. Наприклад: PG.setButtonId('paymentButton');. Після цього, у разі натискання на кнопку, Мерчанту буде відкриватися платіжний фрейм Portmone.

Цю функцію необхідно використовувати у комбінації с функцією PG.create.

Приклад:

• створення фрейму на основі налаштувань із функції PG. paymentData

PG.paymentData("gateway",data,"frame"); PG.create();

• встановлення id кнопки Мерчанта

PG.setButtonId('paymentButton');

Додаткові можливості:

• Розміщення фрейму у визначений елемент сторінки:

1. Створіть div і задайте йому унікальний id.
2. Розташуйте цей div на верхніх рівнях DOM-структури
3. У об'єкті ініціалізації платежу data передайте параметр frameHolderId зі значенням, яке відповідає id створеного елемента.

"frameHolderId": "paymentFrame1"

• Керування відображенням кнопки "Закрити" у платіжному фреймі. Щоб керувати відображенням кнопки «Закрити» у фреймі, у блоці style об’єкта data встановіть параметр closeVisible: "Y" — кнопка «Закрити» відображається (значення за замовчуванням)
  "N" — кнопка «Закрити» приховується

• Для обробки події закриття фрейму використайте callback-функцію PG.onClose():

PG.onClose(function () {
  console.log("close event");
});

• Для обробки події завантаженя сторінки оплати у фреймі використайте callback-функцію PG.onFrameLoad():

PG.onFrameLoad(function() {
    console.log('frame loaded');
});

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

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

Опис параметрів, що надійдуть до функції обробки:

Параметр	Опис
status	Статус транзакції. Приймає значення PAYED
errorCode	Код помилки
error	Залишається незаповненим
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
billAmount	Сума платежу
shopOrderNumber	Номер замовлення (рахунку) у системі Мерчанта
cardMask	Маска Картки платника
attribute1	Службове поле
attribute2	Службове поле
attribute3	Службове поле
attribute4	Службове поле
receiptLink	Посилання для отримання квитанції
lang	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
description	Коментар до замовлення / опис призначення оплати.
token	Токен платіжної картки
commission	Комісія при проведенні платежу
payeeName	Назва Мерчанта
billCurrency	Валюта проведення платежу
IPSTokenValue	Унікальний токен Visa
errorIPSCode	Код помилки, якщо токен Visa не був створений
errorIPSMessage	Текст помилки, якщо токен Visa не був створений

Мал. 8 – приклад вікна оплати у фреймі на сайті Інтернет-магазину

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

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

$login = 'WDISHOP';
$payeeId = '1185';
$shopOrderNumber = 'test';
$billAmount='1';
$key = 'BDFC166F8AE2F5323A557DB6CA16758D';
$dt = date("YmdHis");
$strToSignature = $payeeId.$dt.bin2hex($shopOrderNumber).$billAmount;
$strToSignature = strtoupper($strToSignature).strtoupper(bin2hex($login));
$signature = strtoupper(hash_hmac('sha256', $strToSignature, $key));

echo $signature;

Параметр	Опис	Обов’язковий
login	Логін компанії	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера	Ні
billAmount	Сума платежу (значення без копійок - 10, з копійками - 10.23)	Так
key	Ключ, який надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
dt	Дата формування підпису	Так

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

Якщо передаєте параметр shopOrderNumber в запиті на оплату, тоді він має бути переданий у формуванні підпису запиту і співпадати. Параметр billAmount має співпадати в запиті на оплату.

3.6. Інформація про курс валют

Опис: Цей метод дозволяє отримати інформацію про курс валют.

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

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

Будь ласка, зверніться до "3.6 Інформація про курс валют" для вивчення структури запиту.

Параметри для формування JSON-структури запиту:

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
date	date	Так

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

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

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

Параметр	Опис
key	Назва валюти
value	курс валюти

Зверніть увагу:

Якщо налаштуваннями курсу валют не передбачено, то повертається помилка

"code": 500 "message": "Не знайдено курсу валют за вашими налаштуваннями. Зверніться до менеджера за уточненням деталей."

Якщо запит за некоректну дату, то повертається помилка

"code": 500 "message": "Не валідний параметр date. Формат для запиту: dd-mm-yyyy"

3.7 Розтермінування

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

Розтермінування підтримується у таких методах інтеграції:

Метод	Параметр	Примітка
JSON-запит на оплату (3.2)	installmentPlan	Якщо блок не передано, але в paymentTypes вказано "installment": "Y" — відображаються всі доступні банки зі стандартними термінами
Платіжний віджет popup, iframe (3.4)	installmentPlan	Якщо блок не передано, але в paymentTypes вказано "installment": "Y" — відображаються всі доступні банки зі стандартними термінами
createLinkPayment (12.5)	installmentPlan	Якщо блок не передано, але в paymentTypes вказано "installment": "Y" — відображаються всі доступні банки зі стандартними термінами
getLinkInvoice (12.4)	installment	Блоки paymentTypes та priorityPaymentTypes не застосовуються

Блок installmentPlan дозволяє обмежити перелік банків та термінів розтермінування, доступних клієнту на сторінці оплати. Передається у такому форматі:

"installmentPlan": {
    "privat24": {
        "parts": "3"
    },
    "oschad": {
        "parts": "5"
    },
    "monobank": {
        "parts": "8"
    },
    "pumb": {
        "parts": "3"
    },
    "otp": {
        "parts": "6"
        },
    "abank": {
        "parts": "6"
        }
}

Для платіжного віджета приклад передачі installmentPlan наведено у розділах 3.4.1 та 3.4.2.

Параметр	Опис	Обов’язковий
parts	Дозволяє регулювати максимальну кількість місяців для розстрочки. Через кому можна вказати кілька місяців розстрочки:5,6,12	Ні
privat24	Оплата частинами від ПриватБанку	Ні
oschad	Оплата частинами від Ощадбанку	Ні
monobank	Оплата частинами від Монобанку	Ні
pumb	Оплата частинами від ПУМБ	Ні
otp	Оплата частинами від ОТП Банку	Ні
abank	Оплата частинами від А-Банку	Ні

Розстрочка від Приват Банку

Для відображення розстрочки на сторінці оплати потрібно в блоці paymentTypes передавати параметр "installment": "Y" і в блоці priorityPaymentTypes вказати порядок розташування методу, наприклад: "installment":"3"

Приклад сторінки оплати розстрочки від ПриватБанк

Приклад оформлення оплати розстрочки від ПриватБанку

Розстрочка від Монобанку

Для відображення розстрочки на сторінці оплати потрібно в блоці paymentTypes передавати параметр "installment": "Y" і в блоці priorityPaymentTypes вказати порядок розташування методу, наприклад: "installment":"3"

Для можливості передачі номеру телефону платника потрібно в блоці payer передавати параметр phoneNumber=635337143 у форматі 635337143

Приклад сторінки оплати розстрочки від Монобанку

Приклад оформлення оплати розстрочки від Монобанку

Розстрочка від Ощадбанку

Для відображення розстрочки на сторінці оплати потрібно в блоці paymentTypes передавати параметр "installment": "Y" і в блоці priorityPaymentTypes вказати порядок розташування методу, наприклад: "installment":"3"

Приклад сторінки оплати розстрочки від Ощадбанку

Приклад оформлення оплати розстрочки від Ощадбанку

Розстрочка від ПУМБ

Для відображення розстрочки на сторінці оплати потрібно в блоці paymentTypes передавати параметр "installment": "Y" і в блоці priorityPaymentTypes вказати порядок розташування методу, наприклад: "installment":"4"

Приклад сторінки оплати розстрочки від ПУМБ

Приклад оформлення оплати розстрочки від ПУМБ

Розстрочка від ОТП Банк

Для відображення розстрочки на сторінці оплати потрібно в блоці paymentTypes передавати параметр "installment": "Y" і в блоці priorityPaymentTypes вказати порядок розташування методу, наприклад: "installment":"5"

Приклад сторінки оплати розстрочки від ОТП Банк

Приклад оформлення оплати розстрочки від ОТП Банк

Розстрочка від А-Банк

Для відображення розстрочки на сторінці оплати потрібно в блоці paymentTypes передавати параметр "installment": "Y" і в блоці priorityPaymentTypes вказати порядок розташування методу, наприклад: "installment":"6"

Приклад сторінки оплати розстрочки від А-Банк

Приклад оформлення оплати розстрочки від А-Банк

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

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

Опис:

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

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

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

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

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

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

Параметри для формування JSON-структури запиту:

1. paymentTypes – блок дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).

Параметр	Опис	Обов’язковий
createtokenonly	Для створення Токену необхідно вказати значення "Y" для цього параметру	Так

2. priorityPaymentTypes – блок дозволяє керувати розміщенням способів проведення платежів на сторінці

Параметр	Опис	Обов’язковий
createtokenonly	Для створення Токену необхідно вказати значення "1" для цього параметру	Так

3. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

4. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Опис платежу (коментар до замовлення/призначення оплати). Максимальна кількість символів 250	Обов’язковий, ідентифікує Токен у подальших оплатах
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів 128	Ні
billAmount	Сума платежу (для отримання Токену необхідно встановити значення 1 грн)	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
preauthFlag	Ознака преавторизації платежу. Обов’язкове значення при отриманні Токену – "N" (звичайна оплата без преавторизації)	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute1-4	Службові поля, заповнюються на розсуд компанії. Максимальна кількість символів 1000	Ні

5. token – налаштування для роботи з Токеном

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Обов’язковий параметр для оплати за Токеном
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену	Залишити порожнім
cardMask	Маска Картки	Залишити порожнім
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Обов’язкове значення "N"

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні

7. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

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

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

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
APPROVALCODE	Код авторизації
BILL_AMOUNT	Передана у запиті сума транзакції
TOKEN	Значення Токену для подальших оплат
RESULT	Результат виконання операції (у разі успіху = 0)
CARD_MASK	Маска Картки платника
ATTRIBUTE1	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE2	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE3	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE4	Службове поле, заповнюється на розсуд компанії
RECEIPT_URL	Посилання для отримання квитанції
LANG	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
DESCRIPTION	Коментар до замовлення / опис призначення оплати. До 250 символів

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

4.2.1. POST запит

Опис:

Для проведення оплати за Токеном необхідно передати запит методом POST на сторінку платіжного шлюзу – https://www.portmone.com.ua/r3/token/secure/token.

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

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

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

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

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

Параметр	Опис
payee_id	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
shop_order_number	Номер замовлення (рахунку), що сплачується, у Інтернет-магазині. До 128 символів
bill_amount	Сума замовлення. Валюта – гривні. Дробова частина відокремлюється символом крапки “.”
description	Коментар до замовлення/ опис призначення оплати. До 250 символів.
application_url	Адреса додатку або Інтернет-магазину, на яку буде спрямований клієнт після успішної авторизації картки. Після успішної оплати замовлення на цю адресу методом POST Portmone.com надішле номер замовлення shop_order_number та дані платежу
lang	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
token	Необхідно встановити значення токену, що отриманий на попередньому етапі
attribute1-4	Службові поля, заповнюються на розсуд компанії. До 1000 символів
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»). Максимальна кількість символів - 500

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

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

Опис параметрів відповіді шлюзу:

Параметр	Опис
BILL_AMOUNT	Передана у запиті сума транзакції
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
APPROVALCODE	Код авторизації
RECEIPT_URL	Посилання для отримання квитанції
TOKEN	Значення Токену для подальших оплат
CARD_PAYMENT_SYSTEM	Значення платіжної системи (VISA, MASTERCARD, PROSTIR)
CARD_LAST_DIGITS	Останні 4 цифри номеру Платіжної картки
RESULT	Результат виконання операції (у разі успіху = 0)

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

Опис:

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

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

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

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

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

Параметри для формування data:

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Опис платежу (коментар до замовлення/призначення оплати). Максимальна кількість символів - 250	Ні
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів - 128	Ні
billAmount	Сума платежу	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»). Максимальна кількість символів - 500	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".

Параметр	Опис	Обов’язковий
card	Оплата Карткою	Ні
portmone	Оплата через гаманець Portmone.com	Ні
token	Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються)	Ні

4. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! В paymentTypes спосіб оплати повинен бути в значенні "Y", в priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

5. token – налаштування для роботи з Токеном

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Так
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену	Так
cardMask	Маска Картки	Так
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Ні

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні

7. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

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

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

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
APPROVALCODE	Код авторизації
BILL_AMOUNT	Передана у запиті сума транзакції
TOKEN	Значення Токену для подальших оплат
RESULT	Результат виконання операції (у разі успіху = 0)
CARD_MASK	Маска Картки платника
ATTRIBUTE1	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE2	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE3	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE4	Службове поле, заповнюється на розсуд компанії
RECEIPT_URL	Посилання для отримання квитанції
LANG	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
DESCRIPTION	Коментар до замовлення / опис призначення оплати. До 250 символів

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

Опис:

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

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

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

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

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

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

Параметр	Опис
login	Логін Інтернет-магазину для доступу до управління акаунтом
password	Пароль Інтернет-магазину
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
token	Необхідно встановити значення токену, що отриманий на попередньому етапі
description	Коментар до замовлення/ опис призначення оплати. До 250 символів
billAmount	Сума платежу. Дробова частина відокремлюється символом крапки “.”
billCurrency	Валюта проведення платежу. Значення без задання: UAH
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»). Максимальна кількість символів - 500
id	Константа

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

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

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

Параметр	Опис
result	Ознака статусу замовлення. Може приймати значення: - PAYED – оплачене, - CREATED – створене, - REJECTED – скасоване.
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
description	Коментар до замовлення/ опис призначення оплати. До 250 символів
id	ID запиту з боку Інтернет-магазину до системи Portmone.com

Важливо! При отриманні помилки по запиту за токеном рекомендуємо робити наступний запит не раніше ніж через 72 години.

4.4. Формування замовлення (платіжного повідомлення) у Viber Bot

Опис:

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

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

Операція можлива тільки для тих користувачів, які зареєстровані у Portmone Viber Bot.

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

{
	"method":"initViberPayment",
	"params":{
		"data":{
			"payeeId":"11344",
			"billAmount":"1",
			"shopOrderNumber":"shp_0001",
			"description":"test",
			"msisdnClient":"+380630000000",
			"paymentMessage":"test message",
			"attribute1":"",
			"attribute2":"",
			"attribute3":"",
			"attribute4":"",
			"attribute5":"",
			"preauthFlag":"N",
			"emailAddress":"[email protected]",
			"credentials":""
		}
	},
    "id":"1"
}

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

Параметр	Опис
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
billAmount	Сума платежу. Дробова частина відокремлюється символом крапки “.”
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
description	Коментар до замовлення/ опис призначення оплати. До 250 символів
msisdnClient	Номер телефону клієнта
paymentMessage	Повідомлення, яке побачить клієнт у Viber Bot. Максимум 250 символів
attribute1, attribute2, attribute3, attribute4, attribute5	Атрибути операції, необов'язково заповнювати
preauthFlag	Має бути значення N
emailAddress	Email клієнта
credentials	Необхідні авторизаційні дані, можна отримати у вигляді хеш-рядку тут (у кабінеті: прийом платежів -> автоплатежі) - https://business.portmone.com.ua/request/subscriptions
id	Константа

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

{
    "result": {
        "errorCode": "0",
        "error": "",
        "linkqr": "",
        "linkbot": ""
    },
    "id": "1"
}

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

Параметр	Опис
errorCode	Код помилки
error	Опис помилки порожній у разі успішної відповіді. Якщо клієнт не знайдений, повернеться опис "Client not found"
linkqr	Посилання на QR код чат боту
linkbot	Посилання чат бот
id	Константа

4.5. Отримання даних МПС за токеном 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
id	Константа

Структура та приклад відповіді (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	Мета-дані карти

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

Опис:

Необхідно надіслати запит на такий 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 (tokenUniqueReference - для Mastercard\guid - для Visa)
id	Константа

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

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

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

Опис:

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

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

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

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

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

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

Параметр	Опис	Обов’язковий
method	Значення: paywith3ds	Так
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів	Ні
token	Необхідно встановити значення токену, що отриманий на попередньому етапі	Так
description	Коментар до замовлення/ опис призначення оплати. До 250 символів	Так
billAmount	Сума платежу. Дробова частина відокремлюється символом крапки “.”	Так
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати	Ні
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
id	Константа	Так

Структура успішної відповіді, коли потрібно пройти 3Ds:

Будь ласка, зверніться до "4.7.1 Успішна відповідь, коли потрібно пройти 3Ds" для вивчення структури відповіді

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

Параметр	Опис
status	Статус транзакції. Може приймати значення: - PAYED – оплачене, - CREATED – створене, - REJECTED – скасоване.
shopbillId	Ідентифікатор замовлення у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
description	Коментар до замовлення/ опис призначення оплати. До 250 символів
pdfUrl	Залишається порожнім
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
isNeed3DS	Ознака необхідності проходження перевірки 3D Secure ("Y" – необхідно пройти процедуру перевірки 3D Secure, "N" – додаткові дії не потрібні)
actionMPI	URL банку, на який треба перенаправити клієнта для проходження 3D Secure перевірки
id	Константа

При таких значеннях параметрів isNeed3DS = Y, status = CREATED необхідно перейти по actionMPI

Структура відповіді після проходження 3Ds:

Будь ласка, зверніться до "4.7.2 Відповідь після проходження 3Ds" для вивчення структури відповіді

Відповідь надходить на successUrl у форматі POST

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

Параметр	Опис
shopbillId	Ідентифікатор замовлення у системі Portmone.com
status	Статус транзакції. Може приймати значення: - PAYED – оплачене, - CREATED – створене, - REJECTED – скасоване.
billAmount	Сума платежу. Дробова частина відокремлюється символом крапки “.”
billNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
payeeName
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
commission	Комісія при проведенні платежу
pdfUrl	Залишається порожнім
payeeId	Ідентифікатор Інтернет-магазину
payDate	Дата оплати
description	Коментар до замовлення/ опис призначення оплати. До 250 символів
cardMask	Маска Картки платника
errorMessage	Повідомлення про помилку
errorCode	Код помилки

Структура успішної відповіді, коли не потрібно проходити 3Ds:

Будь ласка, зверніться до "4.7.3 Успішна відповідь, коли не потрібно проходити 3Ds" для вивчення структури відповіді

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

Параметр	Опис
status	Статус транзакції. Може приймати значення: - PAYED – оплачене, - CREATED – створене, - REJECTED – скасоване.
shopbillId	Ідентифікатор замовлення у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
description	Коментар до замовлення/ опис призначення оплати. До 250 символів
pdfUrl	Посилання на квитанцію
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
isNeed3DS	Ознака необхідності проходження перевірки 3D Secure ("Y" – необхідно пройти процедуру перевірки 3D Secure, "N" – додаткові дії не потрібні)
actionMPI	URL банку, на який треба перенаправити клієнта для проходження 3D Secure перевірки
id	Константа

При таких значеннях параметрів isNeed3DS = N, status = PAYED - транзакція успішна.

Структура неуспішної відповіді:

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

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

Параметр	Опис
Code	Код помилки
Message	Текст помилки
id	Константа

4.8. Проведення оплати за Токеном з відображенням зовнішнього вигляду картки без CVV2

Опис:

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

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

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

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

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

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

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
credentials	Параметри авторизації ( можна отримати у вигляді хеш-рядку у кабінеті: прийом платежів -> автоплатежі https://business.portmone.com.ua/request/subscriptions	Так

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Опис платежу (коментар до замовлення/призначення оплати). Максимальна кількість символів - 250	Ні
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів - 128	Ні
billAmount	Сума платежу	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»). Максимальна кількість символів - 500	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".

Параметр	Опис	Обов’язковий
token	Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються)	Так

4. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! В paymentTypes спосіб оплати повинен бути в значенні "Y", в priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

5. token – налаштування для роботи з Токеном

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Так
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену	Так
cardMask	Маска Картки	Так
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Ні

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні
showEmail	"Y" або порожнє значення – вмикає відображення поля "e-mail" на сторінці оплати, "N" – приховує поле "e-mail" на сторінці оплати (значення без задання – "Y")	Ні

5. Переказ з картки на картку

Платіжна система Portmone.com дозволяє здійснювати переказ грошових коштів з Картки на Картку будь-якого банку України.

Переказ може здійснюватись:

1. Між Токенами Карток без вводу номерів Карток відправника та одержувача (попередньо разово створюються Токен Картки відправника та Токен Картки одержувача).

Схема взаємодії:

1. Відправник (Клієнт) разово реєструє свою картку у системі Portmome.com (здійснює транзакцію на 1 грн з наступним поверненням цієї суми на картку Клієнта протягом 30 хвилин. Інтернет-магазин отримує ідентифікатор (Токен) цієї Картки, який може зберігати у своїй системі (див. розділ 5.1 «Отримання Токену для картки»).

2. Одержувач (Клієнт або Мерчант) разово реєструє свою картку у системі Portmome.com (здійснює транзакцію на 1 грн з наступним її поверненням протягом 30 хвилин). Інтернет-магазин отримує ідентифікатор (Токен) цієї Картки, який може зберігати у своїй системі (див. розділ 5.1 «Отримання Токену для картки»).

3. Коли відправник бажає перерахувати гроші одержувачеві, Інтернет-магазин надсилає до системи Portmome.com запит у форматі json із зазначенням Токену та маски Картки відправника, Токену та маски Картки одержувача і суми платежу (див. розділ 5.2 «Створення запиту на переказ коштів між токенами карток»).

2. З Токену Картки відправника на номер Картки одержувача (див. розділ 5.3 «Запит на переказ коштів з токену на картку»).

3. З Токену Картки відправника на транзитний розрахунковий рахунок (р/р) еквайра та з розрхункового рахунку на Токен Картки одержувача (див. розділ 5.4 «Розривний переказ коштів (з картки на рахунок + з рахунку на картку)»).

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

Опис:

Для отримання Токену (для будь-якого з учасників – як для відправника, так і для одержувача) необхідно виконати запит на адресу: https://www.portmone.com.ua/gateway/.

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

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

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

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

Параметри для формування JSON-структури запиту:

1. paymentTypes – блок дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).

Параметр	Опис	Обов’язковий
createtokenonly	Для створення Токену необхідно вказати значення "Y" для цього параметру	Так

2. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

3. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

4. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Залишити порожнім	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів - 128	Ні
billAmount	Сума платежу (для отримання Токену необхідно встановити значення 1 грн)	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute2-4	Службові поля, заповнюються на розсуд компанії. Максимальна кількість символів - 1000	Ні

5. token – налаштування для роботи з Токеном

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Обов’язкове значення "N"
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Обов’язкове значення "Y"
token	Значення Токену	Залишити порожнім
cardMask	Маска Картки	Залишити порожнім
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Обов’язкове значення "N"
sellerToken	Токен Картки отримувача	Залишити порожнім

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні

7. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

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

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

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
APPROVALCODE	Код авторизації
BILL_AMOUNT	Передана у запиті сума транзакції
TOKEN	Значення Токену для подальших оплат
RESULT	Результат виконання операції (у разі успіху = 0)
CARD_MASK	Маска Картки
ATTRIBUTE1	Службове поле
ATTRIBUTE2	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE3	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE4	Службове поле, заповнюється на розсуд компанії
RECEIPT_URL	Посилання для отримання квитанції
LANG	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
DESCRIPTION	Маска картки отдержувача

5.2. Створення запиту на переказ коштів між токенами карток

Опис:

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

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

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

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

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

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

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Маска Картки одержувача	Так
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів - 128	Ні
billAmount	Сума платежу	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".

Параметр	Опис	Обов’язковий
card	Оплата Карткою	Ні
portmone	Оплата через гаманець Portmone.com	Ні
token	Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються)	Ні

4. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

5. token – налаштування для роботи з Токеном

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Так
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену Картки відправника	Так
cardMask	Маска Картки відправника	Так
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Ні
sellerToken	Токен Картки одержувача	Так

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні

7. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

5.3. Запит на переказ коштів з токену на картку

Опис:

Метод дозволяє виконати переказ коштів з Токену Картки відправника на номер Картки одержувача.

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

Під час виклику методу відкривається сторінка оплати Portmone.com, на якій Клієнтові необхідно вказати номер Картки одержувача, CVV-код Картки відправника та ПІБ відправника.

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

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

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

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

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

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
checkParams	Необхідно встановити значення "Y"	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Номер Картки одержувача (якщо номер не буде переданий, то його має вказати відправник	Ні
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів - 128	Ні
billAmount	Сума платежу	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).

Параметр	Опис	Обов’язковий
token	Переказ з Токену на Картку	Так

4. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

5. token – налаштування для роботи з Токеном

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Так
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену Картки відправника	Так
cardMask	Маска Картки відправника	Так
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Так

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні

7. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

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

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

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
APPROVALCODE	Код авторизації
BILL_AMOUNT	Передана у запиті сума транзакції
TOKEN	Значення Токену для подальших оплат
RESULT	Результат виконання операції (у разі успіху = 0)
CARD_MASK	Маска Картки відправника
ATTRIBUTE1	Службове поле
ATTRIBUTE2	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE3	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE4	Службове поле, заповнюється на розсуд компанії
RECEIPT_URL	Посилання для отримання квитанції
LANG	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
DESCRIPTION	Маска Картки одержувача

5.4. Розривний переказ коштів (з картки на рахунок + з рахунку на картку)

Метод дозволяє виконати розривний переказ коштів між токенами карток відправника та одрежувача (з Токена Картки відправника на транзитний розрахунковий рахунок еквайра (р/р) та з р/р на Токен Картки одержувача).

5.4.1. Переказ з токену картки відправника на рахунок

Опис:

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

Під час виклику методу відкривається сторінка оплати Portmone.com, на якій Клієнтові необхідно ввести CVV-код Картки відправника та здійснити переказ.

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

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

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

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

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

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
checkParams	Необхідно встановити значення "N"	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів - 128	Ні
billAmount	Сума платежу	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів - 1000	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).

Параметр	Опис	Обов’язковий
token	Переказ з Токену на рахунок	Так

4. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

5. token – налаштування для роботи з Токеном

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Так
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену Картки відправника	Так
cardMask	Маска Картки відправника	Так
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Так

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні
showEmail	"Y" або порожнє значення – вмикає відображення поля "e-mail" на сторінці оплати, "N" – приховує поле "e-mail" на сторінці оплати (значення без задання – "Y")	Ні

7. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

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

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

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
APPROVALCODE	Код авторизації
BILL_AMOUNT	Передана у запиті сума транзакції
TOKEN	Значення Токену для подальших оплат
RESULT	Результат виконання операції (у разі успіху = 0)
CARD_MASK	Маска Картки відправника
ATTRIBUTE1	Службове поле
ATTRIBUTE2	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE3	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE4	Службове поле, заповнюється на розсуд компанії
RECEIPT_URL	Посилання для отримання квитанції
LANG	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
DESCRIPTION	Маска Картки одержувача

5.4.2. Переказ з рахунку на токен картки одержувача

Опис:

Мерчант ініціює зарахування коштів з розрахункового рахунку на Токен Картки одержувача.

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

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

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

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

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

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

Параметр	Опис
method	Обов’язковий параметр для виклику процедури зарахування коштів з рахунку на Токен Картки одержувача. Значення: confirmp2p
login	Логін Інтернет-магазину
password	Пароль Інтернет-магазину
shopBillId	Номер замовлення у системі Portmone.com (повинен бути отриманий з відповіді на запит, що описаний у розділі 5.4.1 «Переказ з токену картки відправника на рахунок»)
token	Токен Картки одержувача, на яку необхідно зарахувати кошти
id	Константа

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

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

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
SHOPORDERNUMBER	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
APPROVALCODE	Код авторизації
BILL_AMOUNT	Передана у запиті сума транзакції
TOKEN	Значення Токену для подальших оплат
RESULT	Результат виконання операції (у разі успіху = 0)
CARD_MASK	Маска Картки відправника
ATTRIBUTE1	Службове поле
ATTRIBUTE2	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE3	Службове поле, заповнюється на розсуд компанії
ATTRIBUTE4	Службове поле, заповнюється на розсуд компанії
RECEIPT_URL	Посилання для отримання квитанції
LANG	Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська
DESCRIPTION	Маска Картки одержувача

6. Платежі з преавторизацією

6.1. Проведення преавторизації платежу (блокування коштів)

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

Важливо! Згідно правил МПС, для більшості MCC, термін блокування коштів на Картці користувача можливий до 7 календарних днів. При блокуванні коштів більше ніж на 7 календарних днів - рішення про підтвердження списання коштів буде прийматись банком-емітентом. Максимальний термін преавторизації не повинен перевищувати 30 календарних днів.

Для проведення преавторизації платежу Мерчант повинен передати у POST запиті параметр preauth_flag=Y (для запиту у форматі JSON – параметр preauthFlag=Y). Опис формату та параметрів запитів див. у розділі 3 «Оплата замовлення».

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

6.2.1. POST запит

Опис:

Для завершення оплат з преавторизацією (оплат, при проведенні яких використовувався параметр preauth_flag=Y), повинна бути виконана процедура поставторизації.

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

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

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

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

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

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

Параметр	Опис	Обов’язковий
method	Значення: preauth	Так
login	Логін Інтернет-магазину	Так
password	Пароль Інтернет-магазину	Так
action	Ідентифікатор дії, що повинна бути виконана по відношенню до цього замовлення – підтвердження блокування коштів (можливе зі зміною суми). Значення: set_paid	Ні
shop_bill_id	Номер замовлення у системі Portmone.com (повинен бути отриманий за допомогою методу result, що описаний у розділі 8.2 «Запит результатів авторизації»)	Ні
postauth_amount	Сума оплати. Передається при значенні action=set_paid. Не може бути більше за суму, на яку проводилась преавторизація
encoding	Кодування	Ні
lang	Мова повідомлень про помилки	Ні

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

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

Секція результату <request> може бути використана для налагодження – теги відповідають реально отриманим параметрам запиту. Якщо якогось тегу у <request> немає – значить, цей параметр не був переданий у запиті.

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

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

Опис:

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

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

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

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

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

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

Параметр	Опис	Обов’язковий
method	Значення: confirmPreauth	Так
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів	*Так/Ні
shopbillId	Ідентифікатор замовлення у системі Portmone.com. Необов’язковий параметр	*Так/Ні
postauthAmount	Сума оплати. Не може бути більше за суму, на яку проводилась преавторизація	Ні
id	Константа	Так

Важливо! *Пошук може виконуватись за параметром shopOrderNumber або shopbillId. У випадку, коли передані обидва параметри, пошук буде виконуватись за параметром shopbillId. Якщо жодний з параметрів не був переданий, виникне помилка.

1. goods – необов’язковий блок, що містить масив даних для фіскалізації.

Параметр	Опис	Обов’язковий
internalCode	Код продавця	Так
manufacturerCode	Код виробника	Ні
govClassificationCode	Код УКТЗЕД	Ні
name	Назва товару\послуги	Так
name_en	Назва товару\послуги EN	Ні
description	Опис товару\послуги	Ні
description_en	Опис товару\послуги EN	Ні
price	Ціна ( шт)	Так
quantity	Кількість	Так
uomCode	Одиниця виміру ( не обов'язково, за замовчуванням шт)	Ні
amount	Сума	Так
taxRateCodes	Цифровий код ставки податку (попередньо програмується у особистому кабінеті податкового агента). Якщо до товару потрібно застосувати декілька податків — вказати через кому, наприклад: "1,2"	Так
descriptionUrl	Посилання на опис товару	Ні
imageUrl	Посилання на картинку товару	Ні
barcode	Штрих-код товару	Ні
serviceFlag	Ознака послуги. Визначає тип позиції в чеку для фіскалізації. N — товар	Ні
discount	Сума знижки по позиції товару в гривнях	Ні
discountName	Назва знижки	Ні

Показати приклад JSON-структури блоку goods

{
  "goods": [
    {
      "internalCode": "123456",
      "manufacturerCode": "123456",
      "govClassificationCode": "123456",
      "name": "",
      "name_en": "",
      "description": "",
      "description_en": "",
      "price": "100",
      "quantity": "2",
      "uomCode": "",
      "amount": "200",
      "serviceFlag": "N",
      "taxRateCodes": "1",
      "descriptionUrl": "",
      "imageUrl": "",
      "barcode": "1234567890",
      "discount": "10.00",
      "discountName": "Знижка"
    }
  ]
}

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

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

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

Параметр	Опис
payee_id	Ідентифікатор Інтернет-магазину
shop_bill_id	Ідентифікатор замовлення (рахунку) у системі Portmone
shop_order_number	Номер замовлення (рахунку) у системі Інтернет-магазину
description	Опис замовлення
bill_date	Дата створення рахунку
pay_date	Дата та час оплати
pay_order_date	Дата банківського меморіального ордеру
bill_amount	Сума рахунку
auth_code	Код авторизації банку (повертається, якщо замовлення оплачено)
status	Статус замовлення
bank_id	Назва банка еквайра
terminal_id	Номер терміналу еквайра
merchant_id	Назва терміналу
rrn	RRN банківської транзакції
attribute1	Службове поле
attribute2	Службове поле
attribute3	Службове поле
attribute4	Службове поле
attribute5	Службове поле
attribute6	Маска картки
error_code	Код помилки
error_message	Повідомлення про помилку

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

6.3.1. POST запит

Опис:

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

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

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

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

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

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

Параметр	Опис	Обов’язковий
method	Значення: preauth	Так
login	Логін Інтернет-магазину	Так
password	Пароль Інтернет-магазину	Так
action	Ідентифікатор дії, що повинна бути виконана по відношенню до цього замовлення. Значення: reject – відміна блокування	Так
shop_bill_id	Номер замовлення у системі Portmone.com (має бути отриманий за допомогою методу result, що описаний у розділі 8.2 «Запит результатів авторизації»)	Так
encoding	Кодування	Ні
lang	Мова повідомлень про помилки	Ні

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

Будь ласка, зверніться до "6.3.1 Приклад відповіді на POST запит скасування платежу з преавторизацією" для вивчення структури відповіді.

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

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

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

Опис:

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

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

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

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

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

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

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

Важливо! Пошук може виконуватись за параметром shopOrderNumber або shopbillId. У випадку, коли передані обидва параметри, пошук буде виконуватись за параметром shopbillId. Якщо жодний з параметрів не був переданий, виникне помилка.

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

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

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

Параметр	Опис
shop_bill_id	Ідентифікатор замовлення у системі Portmone.com
shop_order_number	Номер замовлення (рахунку) у системі Інтернет-магазину. До 128 символів
description	Опис замовлення
bill_amount	Сума рахунку
status	Статус замовлення
bank_id	Назва банка еквайра
terminal_id	Номер терміналу еквайра
merchant_id	Назва терміналу
rrn	RRN транзакціїї
auth_code	Код авторизації банку (проставляється якщо замовлення оплачене)
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
attribute6	маска картки
commission	комісія мерчата
error_code	Код помилки
error_message	Повідомлення про помилку

7. Розщеплення платежу

Платіжна система Portmone.com надає можливість розщеплення 1 (одного) карткового платежу на декілька компаній (юридичних осіб). З Картки Клієнта списується єдина сума, яка потім окремими транзакціями переказується на рахунок кожного з одержувачів, дані яких Мерчант передав у запиті на оплату. Розщеплення платежу доступне для компаній-одержувачів, що зареєстровані в Portmone.com.

Схема взаємодії:

1. Кожна з компаній-одержувачів реєструється у системі Portmone.com.

2. Клієнт робить замовлення на сайті Основної компанії.

3. Основна компанія (компанія, що виступає ініціатором розщеплення) передає в полі attribute5 запиту на оплату параметри розщеплення:

   • опис замовлення по кожному з одержувачів (Desc);

   • ID компанії для кожного з одержувачів (payeeID);

   • суму, яку необхідно зарахувати на рахунок кожного з одержувачів (amount).

Поле attribute5 заповнюється у форматі:

Desc1:payeeID1;amount1;Desc2:payeeID2;amount2;...

Кількість компаній-одержувачів для одного запиту на оплату з розщепленням платежу обмежена довжиною рядку (до 500 символів).

У відповіді методу повернення з розщепленням повертаємо всіх учасників розщеплення.

4. Portmone.com надсилає до Основної компанії XML-повідомлення з результатом авторизації на всю суму замовлення.

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

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

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

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

• при поверненні клієнта на сайт Мерчанта відразу після оплати;
• самостійно в Особистому кабінеті Мерчанта: https://www.portmone.com.ua/b2b_dash/;
• XML-запитом до системи Portmone.com;
• передача XML-повідомлення до Інтернет-магазину про результат авторизації (XML-нотифікация про оплату);
• передача XML-повідомлення до Інтернет-магазину про платіжне доручення (XML-нотифікація про фінансове покриття транзакцій);
• повідомлення про результат авторизації та платіжне доручення у форматі JSON
• повідомленнями на електронну пошту.

8.1. Отримання виписок з результатами авторизації в Особистому кабінеті

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

Для авторизації у Особистому кабінеті необхідно перейти за адресою https://www.portmone.com.ua/b2b_dash та у окні, що з’явиться, ввести логін та пароль. Реквізити для роботи з Особистим кабінетом (логін та пароль) можна отримати у Portmone.com за запитом (телефоном або по e-mail).

Інформацію про операції можна отримати на сторінці «Замовлення». Виписку можна подивитись за будь-який проміжок часу, фільтруючи транзакції за наявністю платіжки, номером замовлення, результатом операції (усі, вдалі, невдалі або повернення) або кодом авторизації.

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

8.2.1. POST запит

Опис:

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

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

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

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

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

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

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

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

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

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

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

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

Опис:

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

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

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

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

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

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

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

Важливо! Пошук може виконуватись за параметром shopOrderNumber або shopbillId. У випадку, коли передані обидва параметри, пошук буде виконуватись за параметром shopbillId. Якщо жодний з параметрів не був переданий, виникне помилка.

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

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

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

Параметр	Опис
payeeId	Ідентифікатор Інтернет-магазину
description	Опис замовлення
status	Статус замовлення. У разі успішної операції приймає значення PAYED або PREAUTH
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
attribute5	Передаємо у разі використання розщелення платежу
distribution_payee_id	Опис замовлення при використанні розщеплення оплати
commission	Значення поверненої комісії з платежу
bank_name	Назва банка еквайра
terminal_id	Номер терміналу еквайра
merchant_id	Назва терміналу
rrn	RRN транзакціїї
pay_date	Дата оплати
payee_export_date	Дата відправки суми/повідомлення про сплату постачальникові
payee_export_flag	При успішній оплаті прймає значення Y
chargeback	Чи був поданий за транзакцією чарджбек
payee_name	Назва мерчанта
payee_commission	Комісія з мерчанта
pay_order_date	Дата банківського меморіального ордеру
pay_order_number	Номер рахунку
pay_order_amount	Сума рахунку
shopBillId	Ідентифікатор замовлення у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
billAmount	Сума рахунку
errorCode	Код помилки
errorMessage	Повідомлення про помилку
authCode	Код авторизації банку (проставляється якщо замовлення оплачене)
cardMask	Маска Картки платника
cardBankName	Назва банка-емітента
token	Значення Токену для подальших оплат
payeeExportResult	Опис помилки
gateType	Ідентифікатор методу оплати
cardTypeName	Назва МПС

8.2.2.1. Запит результатів авторизації при використанні Оплати Частинами (розстрочки) у форматі JSON

Опис:

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

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

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

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

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

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

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

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

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

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

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

8.2.2.2. Приклад упішної відповіді для доставки "Нова Пошта" у форматі JSON

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

Параметр	Опис
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com
description	Спосіб доставки
shopBillId	Ідентифікатор замовлення у системі Portmone.com
delivery_id	Внутрішній номер доставки
pib	ПІБ отримувача
phone_number	Номер телефону отримувача
delivery_type	Вид доставки: WarehouseWarehouse - відділення чи поштомат, WarehouseDoors - кур'єр
warehouse_description	Назва відділення
warehouse_short_address	Коротка адреса відділення
city_name	Назва населеного пункту
street_name	Назва вулиці
creation_date	Дата створення доставки
delivery_company	Служба доставки

Приклад відповіді для доставки у Відділення (ключові параметри)

[
    {
        "payee_id": "123000",
        "description": "Viddilennya",
        ...
        "shopBillId": "2026463560",
        ...
        "delivery": {
            "delivery_id": "81",
            "pib": "Солоніченко Дмитро",
            "phone_number": "380660000000",
            "delivery_type": "WarehouseWarehouse",
            "warehouse_description": "Відділення №49 (до 30 кг): вул. Йорданська, 1, озеро\"Вербне\"(Оболонь)",
            "warehouse_short_address": "Київ, Йорданська, 1",
            "city_name": "м. Київ, Київська обл.",
            "street_name": null,
            "creation_date": "27.06.2025",
            "delivery_company": "Нова Пошта"
        }
    }
]

Приклад відповіді для доставки в Поштомат (ключові параметри)

[
    {
        "payee_id": "123000",
        "description": "Poshtomat",
        ...
        "shopBillId": "2026463560",
        ...
        "delivery": {
            "delivery_id": "82",
            "pib": "Солоніченко Дмитро",
            "phone_number": "380660000000",
            "delivery_type": "WarehouseWarehouse",
            "warehouse_description": "Поштомат \"Нова Пошта\" №1526: вул. Йорданська, 9, під'їзд №1 (ТІЛЬКИ ДЛЯ МЕШКАНЦІВ)",
            "warehouse_short_address": "Київ, Йорданська, 9, під'їзд №1 (ТІЛЬКИ ДЛЯ МЕШКАНЦІВ)",
            "city_name": "м. Київ, Київська обл.",
            "street_name": null,
            "creation_date": "27.06.2025",
            "delivery_company": "Нова Пошта"
        }
    }
]

Приклад відповіді для доставки Кур'єром (ключові параметри)

[
    {
        "payee_id": "123000",
        "description": "Kurier",
        "status": "PAYED",
        ...
        "shopBillId": "2026477024",
        ...
        "delivery": {
            "delivery_id": "83",
            "pib": "Солоніченко Дмитро",
            "phone_number": "380660000000",
            "delivery_type": "WarehouseDoors",
            "warehouse_description": null,
            "warehouse_short_address": null,
            "city_name": "м. Київ, Київська обл.",
            "street_name": "просп. Оболонський",
            "creation_date": "27.06.2025",
            "delivery_company": "Нова Пошта"
        }
    }
]

8.3. Повідомлення серверу Інтернет-магазину про результат авторизації

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

Опис:

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

Приклад:

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

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

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

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

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

Назва поля	Тип	Коментар
PAYEE\NAME	CHAR(100)	Назва компанії отримувача коштів
PAYEE\CODE	NUMBER(15,0)	Код компанії (надається компанії системою Portmone.com)
BANK\NAME	CHAR(100)	Назва банку відправника
BANK\CODE	CHAR(6)	МФО банку відправника. У разі заповнення номеру рахунку відправника за стандартом IBAN в полі BANK\CODE передаватиметься значення "0" (нуль)
BANK\ACCOUNT	CHAR(29)	Рахунок банку відправника або IBAN (в залежності від того, який з реквізитів був заповнений при здійсненні платежу)
BILL_ID	NUMBER(15,0)	Унікальний ID рахунку у системі Портмоне. Компанія повинна перевіряти унікальність BILL_ID. Та не дозволяти реєструвати два повідомлення з однаковими BILL_ID. Відповідає параметру SHOPBILLID (див. розділ 3 «Оплата замовлення»).
BILL_NUMBER	CHAR(120)	Номер рахунку. Відповідає параметру shop_order_number (якщо переданий, див. розділ 3 «Оплата замовлення»).
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)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається
NAME	CHAR	Назва компанії одержувача розподілення
CODE	CHAR	Код компанії одержувача розподілення
EDRPOU	CHAR	ЄДРПОУ компанії одержувача розподілення
IBAN	CHAR	Розрахунковий рахунок компанії одержувача розподілення
AMOUNT	NUMBER	Сума розподілення
DESCRIPTION	CHAR	Опис розподілення

Приклади:

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

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

Опис:

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

Приклад:

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

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

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

Будь ласка, зверніться до "8.3 Повідомлення про банківський платіж – 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)	МФО банку відправника. У разі заповнення номеру рахунку відправника за стандартом IBAN в полі BANK\CODE передаватиметься значення "0" (нуль)
BANK\ACCOUNT	CHAR(29)	Рахунок банку відправника або IBAN (в залежності від того, який з реквізитів був заповнений при здійсненні платежу)
BILL_ID	NUMBER(15,0)	Унікальний ID рахунку у системі Портмоне. Компанія повинна перевіряти унікальність BILL_ID. Та не дозволяти реєструвати два повідомлення з однаковими BILL_ID. Відповідає параметру SHOPBILLID (див. розділ 3 «Оплата замовлення»)
BILL_NUMBER	CHAR(120)	Номер рахунку. Відповідає параметру shop_order_number (якщо переданий, див. розділ 3 «Оплата замовлення»).
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)	Додатковий параметр ідентифікації клієнта. Якщо для ідентифікації абонента він не потрібний, то у повідомленні він не передається

Приклади:

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

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

Опис:

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

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

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

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

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

Приклади:

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

8.4. Отримання виписок з результатами авторизації на електронну пошту

Виписки розсилаються магазинам відразу ж після успішної авторизації картки. Можливі два варианти розсилання виписок:

1. Надсилання на e-mail Партнера двох електронних листів – одного з випискою у текстовому вигляді та другого з випискою у вигляді XML-повідомлення (дивіться "8.4 Приклад виписки з результатами авторизації у форматі XML");
2. Надсилання на e-mail Партнера тільки текстового повідомлення.

Приклад виписки у текстовому вигляді:

В системі Portmone.com оплачено замовлення: Номер замовлення: 305966 Дата замовлення: 18.03.2010 Коментар: 50908: покриття по платіжним карткам Сума: 108.98 Валюта: UAH Код авторизації: 87446Z Тип авторизації: 3DSECURE

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

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

Опис:

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

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

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

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

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

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

Опис:

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

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

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

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

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

8.6. Передача повідомлення про платіжне доручення (текстове повідомлення на e-mail про фінансове покриття за транзакціями)

Наступного дня після перерахування банком фінансового покриття на розрахунковий рахунок магазину, система Portmone.com надсилає на e-mail магазину листа з текстовим файлом, що містить перелік замовлень, які покриті цим платіжним дорученням.

Лист містить наступну інформацію:

Агент: ООО "ПОРТМОНЕ" Довіритель ТОВ Квіточка Реєстр отриманих оплат "Райффайзен банк Аваль" МФО 300335 розрахунковий рахунок 29249215 № п/д 6559503 дата 17.07.2010 +------------------------------------------------------------------------+ |Дата оплати |Номер замовлення |Код авт.|Сум. плат. | +------------------------------------------------------------------------+ |14.07.2014 00:08 | 141192| 171363| 191.00| |14.07.2014 02:10 | 141205| 29797B| 104.00| |14.07.2014 10:49 | 141225| 432054| 104.00| |14.07.2014 12:40 | 141249| 37614B| 89.00| |14.07.2014 14:47 | 141275| 34502Z| 158.00| |14.07.2014 14:54 | 141281| 083689| 220.00| |14.07.2014 18:52 | 141339| 841013| 290.50| |14.07.2014 19:26 | 141348| 587414| 91.00| |14.07.2014 19:35 | 141353| 389922| 141.50| |14.07.2014 19:56 | 141361| 638960| 74.00| |14.07.2014 22:08 | 141405| 61791B| 249.00| |14.07.2014 22:47 | 141418| 013761| 131.00| +------------------------------------------------------------------------+ Всього оплат на суму 1843.00 грн. Комісія 36.86 грн. Всього за день 1843.00 грн. Комісія 36.86 грн. Перераховується одержувачу 1806.14 грн.

8.7. Отримання посилання на квитанцію

8.7.1 Отримання посилання на квитанцію для оплат shopBillId

Опис:

За допомогою даного методу можна отримати:

• квитанцію про успішну оплату;
• квитанцію про повернення коштів (у разі, якщо по замовленню виконувалося повернення).

Метод дозволяє отримувати квитанції для одного або декількох замовлень. У відповіді формується агрегований PDF-файл з квитанціями за всіма переданими замовленнями.

Для отримання посилання на квитанцію необхідно виконати POST-запит у форматі JSON на адресу: https://www.portmone.com.ua/r3/api/gateway/

Доступність і обмеження:
Максимальна кількість замовлень у масиві shopOrderNumber — 30.

Структура запиту:
Будь ласка, зверніться до "8.7.1 Приклад запиту для методу отримання квитанцій" для вивчення структури запиту.

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

Параметр	Опис	Обовʼязковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
shopOrderNumber	Масив номерів замовлень. Підтримує один або декілька елементів. Максимум — 30 значень.	Так
id	Константа	Так

Структура відповіді: Будь ласка, зверніться до "8.7.1 Приклад відповіді для методу отримання квитанцій" для вивчення структури відповіді.

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

Параметр	Опис
linkPdf	Посилання на агрегований PDF-файл з квитанціями за всіма переданими замовленнями
linkPdfReturn	Посилання на агрегований PDF-файл з квитанціями про повернення коштів (повертається лише якщо по замовленнях виконувались повернення)
id	Константа

8.7.2 Отримання посилання на квитанцію для оплат billId

Опис:

За допомогою даного методу можна отримати: квитанцію про успішну оплату;

Метод дозволяє отримувати квитанції для одного або декількох замовлень. У відповіді формується агрегований PDF-файл з квитанціями за всіма переданими замовленнями.

Для отримання посилання на квитанцію необхідно виконати POST-запит у форматі JSON на адресу: https://www.portmone.com.ua//r3/uk/api/merchant-bills

Доступність і обмеження:
Максимальна кількість замовлень у масиві shopOrderNumber — 30.

Структура запиту:
Будь ласка, зверніться до "8.7.2 Приклад запиту для методу отримання квитанцій" для вивчення структури запиту.

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

Параметр	Опис	Обовʼязковий
billId	Масив рахунків. Підтримує один або декілька елементів. Максимум — 30 значень.	Так
credentials	Параметри авторизації (отримати можна за допомогою методу getcredentials, п.10.2	Так
id	Константа	Так

Структура відповіді: Будь ласка, зверніться до "8.7.2 Приклад відповіді для методу отримання квитанцій" для вивчення структури відповіді.

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

Параметр	Опис
id	billId оплати
linkPdf	Посилання на агрегований PDF-файл з квитанціями за всіма переданими замовленнями
id	Константа

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

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

Опис:

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

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

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

У зв'язку з тим, що у кожного банка-еквайра індивідуальний регламент повернень/відмін оплат рекомендуємо здійснювати повернення (в повному обсязі або часткове) через 24 години. У разі додаткової інформації, будь ласка, звертайтеся за адресою [email protected]

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

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

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

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

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

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

Секція результату <request> може бути використана для налагодження – теги відповідають реально отриманим параметрам запиту. Якщо якогось тегу у <request> немає – значить, цей параметр не був переданий у запиті.

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

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

Опис:

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

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

У зв'язку з тим, що у кожного банка-еквайра індивідуальний регламент повернень/відмін оплат рекомендуємо здійснювати повернення (в повному обсязі або часткове) через 24 години. У разі додаткової інформації, будь ласка, звертайтеся за адресою [email protected]

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

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

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

Параметр	Опис	Обов’язковий
method	Значення: return	Так
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів	Так
shopbillId	Ідентифікатор замовлення у системі Portmone.com	Ні
attribute5	Використовується при розщепленні оплати. Максимальна кількість символів - 500
returnAmount	Сума повернення. Можливе повернення суми платежу повністю або частково	Так
message	Коментар до повернення	Так
id	Константа	Так

Важливо! Повернення може виконуватись за параметром shopOrderNumber або shopbillId. У випадку, коли передані обидва параметри, пошук буде виконуватись за параметром shopbillId. Якщо жодний з параметрів не був переданий, виникне помилка.

1. goods – необов’язковий блок, що містить масив даних для фіскалізації (використовується, для часткового повернення).

Параметр	Опис	Обов’язковий
internalCode	Код продавця	Так
manufacturerCode	Код виробника	Ні
govClassificationCode	Код УКТЗЕД	Ні
name	Назва товару\послуги	Так
name_en	Назва товару\послуги EN	Ні
description	Опис товару\послуги	Ні
description_en	Опис товару\послуги EN	Ні
price	Ціна ( шт)	Так
quantity	Кількість	Так
uomCode	Одиниця виміру ( не обов'язково, за замовчуванням шт)	Ні
amount	Сума	Так
taxRateCodes	Цифровий код ставки податку (попередньо програмується у особистому кабінеті податкового агента). Якщо до товару потрібно застосувати декілька податків — вказати через кому, наприклад: "1,2"	Так
descriptionUrl	Посилання на опис товару	Ні
imageUrl	Посилання на картинку товару	Ні
barcode	Штрих-код товару	Ні
serviceFlag	Ознака послуги. Визначає тип позиції в чеку для фіскалізації. N — товар	Ні
discount	Сума знижки по позиції товару в гривнях	Ні
discountName	Назва знижки	Ні

Показати приклад JSON-структури блоку goods

{
   "method":"return",
   "params":{
      "data":{
         "login":"TEST_432231",
         "password":"111111",
         "payeeId":"1185",
         "shopbillId":2265131947,
         "returnAmount":"7.2",
         "message":"test return by shopbillId",
         "goods":[
            {
               "internalCode":"001017",
               "name":"Машина",
               "price":3,
               "quantity":1,
               "amount":3,
               "taxRateCodes":8,
               "govClassificationCode":"3306200000",
               "barcode":"1234-543121"
            },
            {
               "internalCode":"001018",
               "name":"Хліб",
               "price":4.2,
               "quantity":1,
               "amount":4.2,
               "taxRateCodes":8,
               "govClassificationCode":"3306200000",
               "barcode":"1234-567891"
            }
         ]
      }
   },
   "id":1
}
}

Важливо! Сума повернення має відповідати сумі товарів, переданих у параметрі goods. Інакше буде повернуто помилку:

{
"error":"Сума по позиціям в оплаті не співпадає із загальною сумою в оплаті. Оплата неможлива, перевірте запит на оплату.",
"errorCode":"13"
}

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

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

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

Параметр	Опис
description	Опис замовлення
status	Статус замовлення
bank_id	Код банка-эквайра
terminal_id	Номер терміналу банка-эквайра
merchant_id	Назва терміналу
rrn	RRN транзакції (ідентифікатор трнанзакції в банківській системі)
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
attribute5	Використовується при розщепленні оплати
commission	Значення поверненої комісії з платежу
shopBillId	Ідентифікатор замовлення у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
billAmount	Сума повернення
errorCode	Код помилки
errorMessage	Повідомлення про помилку
authCode	Код авторизації банку (проставляється, якщо замовлення оплачене)
cardMask	Маска картки
token	Токен картки
gateType	Ідентифікатор методу оплати

9.2 Запит відміни оплати у форматі JSON

Опис:

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

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

Запит можна використовувати за умови, якщо він відбуватиметься в день оплати.

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

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

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

Параметр	Опис	Обов’язковий
method	Значення: reject	Так
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopbillId	Ідентифікатор замовлення у системі Portmone.com	Так
returnAmount	Сума повернення	Так
message	Коментар до повернення	Ні
id	Константа	Так

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

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

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

Параметр	Опис
description	Опис замовлення
status	Статус замовлення
bank_id	Код банка-эквайра
terminal_id	Номер терміналу банка-эквайра
merchant_id	Назва терміналу
rrn	RRN транзакції (ідентифікатор трнанзакції в банківській системі)
attribute1	Службове поле, заповнюється на розсуд компанії
attribute2	Службове поле, заповнюється на розсуд компанії
attribute3	Службове поле, заповнюється на розсуд компанії
attribute4	Службове поле, заповнюється на розсуд компанії
commission	Значення поверненої комісії з платежу
shopBillId	Ідентифікатор замовлення у системі Portmone.com
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів
billAmount	Сума повернення
errorCode	Код помилки
errorMessage	Повідомлення про помилку
authCode	Код авторизації банку (проставляється, якщо замовлення оплачене)
cardMask	Маска картки
token	Токен картки
gateType	Ідентифікатор методу оплати

10. Використання Gateway для сплати сервісів Portmone

Опис:

Платіжний шлюз Portmone дозволяє здійснювати оплату рахунків URL для виклику методів: – https://www.portmone.com.ua/r3/:lang/bills/merchant.

10.1. Методи

Назва методу	Опис
10.1.1. getsessid	результатом виклику методу _ getsessid_ є поверення параметру sessid, який необхідний для подальший запитів на формування рахунку
10.1.2. region	метод використовується для отримання списку регіонів України з пошуком за назвою регіону
10.1.3. cities	метод використовується для отримання списку населених пунктів вказаного регіону за назвою населеного пункту
10.1.4. streets	метод використовується для отримання списку вулиць вказаного населеного пункту з пошуком за назвою вулиці
10.1.5. houses	метод використовується для отримання списку будинків для вказаної вулиці з пошуком за номером будинку
10.1.6. apartments	метод використовується для отримання списку квартир за відомим ідентифікатором будинку (тільки для багатоквартирних будинків) з пошуком за номером квартири
10.1.7. getBillsAttributesByAddressId	метод використовується для отримання даних для формування рахунку
10.1.8. billsCreate	метод використовується для отримання списку рахунків за знайденим ідентифікатором будинку (для приватних будинків) або квартири (для багатоквартирних будинків). Повертає рахунки з повною відповідністю за адресою
10.1.9. updateTariffItems	метод використовується для оновлення суми рахунку
10.1.10. payees	метод використовується для отримання параметрів біллерів

10.1.1. Запит на отримання параметру сесії

Метод: _ getsessid_

Опис: результатом виклику методу _ getsessid_ є поверення параметру sessid, який необхідний для подальший запитів на формування рахунку.

Параметри:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
id	Константа	Так

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

{
  "method": "getsessid",
  "params": {
    "data": {
      "login": "PORTMONE_DIRECT_IT_SERVE",
      "password": "11111111"
    }
  },
  "id": "1"
}

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

{
  "result": {
    "errorCode": "0",
    "error": "",
    "status": "success",
    "sessid": "3ek43kplfjlho2ndn75a66g6u1"
  },
  "id": "1"
}

10.1.2. Запит інформації по регіону

Метод: _ region_

Опис: результатом виклику методу _ region_ є отримання списку регіонів України.

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

{
  "method": "search",
  "params": {
    "data": {
      "requestType": "region",
      "query": "Кие"
    }
  },
  "id": "1"
}

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

{
  "result": [
    {
      "regionId": "44",
      "name": "м. Київ",
      "sort": 4
    },
    {
      "regionId": "45",
      "name": "Київська область",
      "sort": 4
    }
  ],
  "id": "1"
}

10.1.3. Запит інформації по містах (населених пунктах)

Метод: cities

Опис: результатом виклику методу _ cities_ є отримання списку міст (населених пунктів) по регіону.

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

{
  "method": "search",
  "params": {
    "data": {
      "requestType": "cities",
      "query": "Кие",
      "regionId": "44"
    }
  },
  "id": "1"
}

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

{
  "result": [
    {
      "cityId": "22",
      "name": "м. Київ",
      "sort": 4,
      "highlight": null
    }
  ],
  "id": "1"
}

10.1.4. Запит інформації по вулицях

Метод: _ streets_

Опис: результатом виклику методу _ streets_ є отримання списку вулиць по місту (населеному пункту).

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

{
  "method": "search",
  "params": {
    "data": {
      "requestType": "streets",
      "query": "Лаврух",
      "cityId": "22"
    }
  },
  "id": "1"
}

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

{
  "result": [
    {
      "streetId": "2368",
      "name": "вулиця Миколи Лаврухіна",
      "sort": 4,
      "highlight": "вулиця Миколи <em>Лаврух</em>іна"
    }
  ],
  "id": "1"
}

10.1.5. Запит інформації по будинках

Метод: _ houses_

Опис: результатом виклику методу houses є отримання списку будинків по вулиці.

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

{
  "method": "search",
  "params": {
    "data": {
      "requestType": "houses",
      "query": "14",
      "streetId": "2368"
    }
  },
  "id": "1"
}

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

{
  "result": [
    {
      "houseId": 373194,
      "name": "14",
      "hasApartments": "Y",
      "highlight": "<em>14</em>",
      "sort": 13
    }
  ],
  "id": "1"
}

10.1.6. Запит інформації по квартирах будинку

Метод: _ apartment_

Опис: результатом виклику методу _ apartment_ є отримання списку будинків по вулиці.

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

{
  "method": "search",
  "params": {
    "data": {
      "requestType": "apartment",
      "query": "34",
      "houseId": "373194"
    }
  },
  "id": "1"
}

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

{
  "result": [
    {
      "apartmentId": "7381096",
      "name": "34",
      "sort": 34,
      "highlight": "<em>34</em>"
    }
  ],
  "id": "1"
}

10.1.7. Запит для отримання даних по формуваню рахунку

Метод: _ getBillsAttributesByAddressId_

Опис: результатом виклику методу _ getBillsAttributesByAddressId_ є отримання даних для формування рахунку.

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

{
  "method": "getBillsAttributesByAddressId",
  "params": {
    "data": {
      "sessid": "3ek43kplfjlho2ndn75a66g6u11",
      "addressId": "7587028"
    }
  },
  "id": "1"
}

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

{
  "result": [
    {
      "payeeId": "22494",
      "contractNumber": "168847",
      "attribute1": "КИЇВ, ЛАВРУХІНА МИКОЛИ ВУЛ. Д14 КВ14",
      "contractNumberTitle": "ІД",
      "attribute1Title": "Адреса",
      "contractNumberType": "N",
      "attribute1Type": "C",
      "attribute1ForInfo": "Y",
      "payany": "N"
    },
    {
      "payeeId": "14329",
      "contractNumber": "164024100140100",
      "attribute1": "КИЇВ, ЛАВРУХІНА МИКОЛИ ВУЛ. Д14 КВ14",
      "contractNumberTitle": "О/р",
      "attribute1Title": "Адреса",
      "contractNumberType": "C",
      "contractNumberSize": "15",
      "attribute1Type": "C",
      "attribute1ForInfo": "Y",
      "payany": "N"
    },
    {
      "payeeId": "17495",
      "contractNumber": "12058901418",
      "attribute1": "вул.Лаврухіна Миколи буд.14 кв.14",
      "contractNumberTitle": "Особовий рахунок",
      "attribute1Title": "Адреса",
      "contractNumberType": "C",
      "attribute1Type": "C",
      "attribute1ForInfo": "Y",
      "payany": "N"
    }
  ],
  "id": "1"
}

10.1.8. Запит на отримання рахунків

Метод: _ billsCreate_

Опис: результатом виклику методу _ billsCreate_ є отримання рахунків.

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

{
  "method": "billsCreate",
  "params": {
    "data": {
      "sessid": "3ek43kplfjlho2ndn75a66g6u11",
      "attributes": [
        {
          "payeeId": "22494",
          "contractNumber": "168847"
        },
        {
          "payeeId": "14329",
          "contractNumber": "164024100140100"
        },
        {
          "payeeId": "17495",
          "contractNumber": "12058901418"
        }
      ]
    }
  },
  "id": "1"
}

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

{
  "result": {
    "bills": [
      {
        "payeeId": "22494",
        "contractNumber": "168847",
        "billId": "802655789",
        "billAmount": "0.00",
        "billTariffItems": [
          {
            "billTariffItemId": "425366990",
            "billId": "802655789",
            "name": "Вивезення побутових відходів",
            "subsidy": "0.00",
            "tariff": "0",
            "counter": "0",
            "prevCounter": "0",
            "amount": "36.12",
            "calculatedAmount": "36.12",
            "calculatedAmountClass": null,
            "debt": "-41.58",
            "paidDebt": "-36.12",
            "paidDebtName": "врах.переп.",
            "paidDebtClass": null,
            "compensation": "0",
            "itemTypeId": "28859",
            "nameUa": "Вивезення побутових відходів",
            "nameEng": "Вивезення побутових відходів",
            "itemTypeCode": "727",
            "itemTypeSubCode": "11",
            "readOnly": "N",
            "shortName": "Вивезення побутових відходів",
            "shortNameUa": "Вивезення побутових відходів",
            "shortNameEng": "Вивезення побутових відходів",
            "attribute1": "36.12",
            "attribute2": "121541",
            "attribute3": "1921",
            "attribute4": null,
            "attribute5": null,
            "attribute6": null,
            "attribute7": null,
            "attribute8": null,
            "attribute9": null,
            "attribute10": null,
            "payeeName": null,
            "calculated": "Y",
            "counterState": "N",
            "counterClass": null,
            "prevCounterState": "N",
            "prevCounterClass": null,
            "tariffState": "N",
            "tariffClass": null,
            "subsidyState": "E",
            "subsidyClass": null,
            "amountState": "E",
            "amountClass": null,
            "debtState": "E",
            "debtClass": null,
            "attribute1State": "V",
            "attribute1Class": null,
            "attribute2State": "N",
            "attribute2Class": null,
            "attribute3State": "N",
            "attribute3Class": null,
            "attribute4State": null,
            "attribute4Class": null,
            "attribute5State": null,
            "attribute5Class": null,
            "tariffName": null,
            "counterName": null,
            "prevCounterName": null,
            "subsidyName": "субсидія",
            "debtName": "перепл.",
            "attribute1Name": "нараховано",
            "attribute2Name": null,
            "attribute3Name": null,
            "attribute4Name": null,
            "attribute5Name": null,
            "compansationName": null,
            "overpayment": null,
            "overpaymentName": null,
            "overpaymentState": null,
            "overpaymentClass": null,
            "amountName": "сплачую",
            "id": "425366990",
            "canPaySeparateDebt": null,
            "totalAmount": "0",
            "totalAmountName": "сплачено",
            "totalAmountState": "E",
            "totalAmountClass": null,
            "difference": null,
            "differenceName": null,
            "differenceState": null,
            "differenceClass": null,
            "negativeAmount": "N",
            "counterAccuracy": null,
            "description": null
          }
        ],
        "errorCode": "",
        "errorMessage": ""
      },
      {
        "payeeId": "14329",
        "contractNumber": "164024100140100",
        "billId": "802655793",
        "billAmount": "3694.58",
        "billTariffItems": [
          {
            "billTariffItemId": "425366992",
            "billId": "802655793",
            "name": "Централізоване постачання гарячої води лічильник",
            "subsidy": "0.00",
            "tariff": "0",
            "counter": "0",
            "prevCounter": "0",
            "amount": "195.78",
            "calculatedAmount": "195.78",
            "calculatedAmountClass": null,
            "debt": "3498.8",
            "paidDebt": "3498.8",
            "paidDebtName": "спл.борг",
            "paidDebtClass": null,
            "compensation": "0",
            "itemTypeId": "26167",
            "nameUa": "Централізоване постачання гарячої води лічильник",
            "nameEng": "Централізоване постачання гарячої води лічильник",
            "itemTypeCode": "677",
            "itemTypeSubCode": "11",
            "readOnly": "N",
            "shortName": "Централізоване постачання гарячої води лічильник",
            "shortNameUa": "Централізоване постачання гарячої води лічильник",
            "shortNameEng": "Централізоване постачання гарячої води лічильник",
            "attribute1": "195.78",
            "attribute2": "116977",

            "attribute3": "1834",
            "attribute4": null,
            "attribute5": null,
            "attribute6": null,
            "attribute7": null,
            "attribute8": null,
            "attribute9": null,
            "attribute10": null,
            "payeeName": null,
            "calculated": "Y",
            "counterState": "N",
            "counterClass": null,
            "prevCounterState": "N",
            "prevCounterClass": null,
            "tariffState": "N",
            "tariffClass": null,
            "subsidyState": "E",
            "subsidyClass": null,
            "amountState": "E",
            "amountClass": null,
            "debtState": "E",
            "debtClass": null,
            "attribute1State": "V",
            "attribute1Class": null,
            "attribute2State": "N",
            "attribute2Class": null,
            "attribute3State": "N",
            "attribute3Class": null,
            "attribute4State": null,
            "attribute4Class": null,
            "attribute5State": null,
            "attribute5Class": null,
            "tariffName": null,
            "counterName": null,
            "prevCounterName": null,
            "subsidyName": "субсидія",
            "debtName": "борг",
            "attribute1Name": "нараховано",
            "attribute2Name": null,
            "attribute3Name": null,
            "attribute4Name": null,
            "attribute5Name": null,
            "compansationName": null,
            "overpayment": null,
            "overpaymentName": null,
            "overpaymentState": null,
            "overpaymentClass": null,
            "amountName": "сплачую",
            "id": "425366992",
            "canPaySeparateDebt": null,
            "totalAmount": "3694.58",
            "totalAmountName": "сплачено",
            "totalAmountState": "E",
            "totalAmountClass": null,
            "difference": null,
            "differenceName": null,
            "differenceState": null,
            "differenceClass": null,
            "negativeAmount": "N",
            "counterAccuracy": "0",
            "description": null
          },
          {
            "billTariffItemId": "425366993",
            "billId": "802655793",
            "name": "Централізоване постачання гарячої води лічильник",
            "subsidy": "0.00",
            "tariff": "97.89",
            "counter": "2",
            "prevCounter": "1",
            "amount": "0",
            "calculatedAmount": "97.89",
            "calculatedAmountClass": null,
            "debt": "0",
            "paidDebt": "0",
            "paidDebtName": null,
            "paidDebtClass": null,
            "compensation": "0",
            "itemTypeId": "26168",
            "nameUa": "Централізоване постачання гарячої води лічильник",
            "nameEng": "Централізоване постачання гарячої води лічильник",
            "itemTypeCode": "677",
            "itemTypeSubCode": "20",
            "readOnly": "N",
            "shortName": "Централізоване постачання гарячої води лічильник",
            "shortNameUa": "Централізоване постачання гарячої води лічильник",
            "shortNameEng": "Централізоване постачання гарячої води лічильник",
            "attribute1": "191555382А",
            "attribute2": "116977",
            "attribute3": "1834",
            "attribute4": null,
            "attribute5": "1",
            "attribute6": null,
            "attribute7": null,
            "attribute8": null,
            "attribute9": null,
            "attribute10": null,
            "payeeName": null,
            "calculated": "Y",
            "counterState": "V",
            "counterClass": null,
            "prevCounterState": "V",
            "prevCounterClass": null,
            "tariffState": "V",
            "tariffClass": null,
            "subsidyState": "N",
            "subsidyClass": null,
            "amountState": "N",
            "amountClass": null,
            "debtState": "N",
            "debtClass": null,
            "attribute1State": "V",
            "attribute1Class": null,
            "attribute2State": "N",
            "attribute2Class": null,
            "attribute3State": "N",
            "attribute3Class": null,
            "attribute4State": null,
            "attribute4Class": null,
            "attribute5State": null,
            "attribute5Class": null,
            "tariffName": "тариф",
            "counterName": "поточні",
            "prevCounterName": "поперед.",
            "subsidyName": null,
            "debtName": null,
            "attribute1Name": "ID ліч.",
            "attribute2Name": null,
            "attribute3Name": null,
            "attribute4Name": null,
            "attribute5Name": null,
            "compansationName": null,
            "overpayment": null,
            "overpaymentName": null,
            "overpaymentState": null,
            "overpaymentClass": null,
            "amountName": null,
            "id": "425366993",
            "canPaySeparateDebt": null,
            "totalAmount": "0",
            "totalAmountName": null,
            "totalAmountState": "N",
            "totalAmountClass": null,
            "difference": null,
            "differenceName": null,
            "differenceState": null,
            "differenceClass": null,
            "negativeAmount": "N",
            "counterAccuracy": "2",
            "description": null
          },
          {
            "billTariffItemId": "425366994",
            "billId": "802655793",
            "name": "Централізоване постачання гарячої води лічильник. показання на дату оплати",
            "subsidy": "0.00",
            "tariff": "97.89",
            "counter": "2",
            "prevCounter": "0",
            "amount": "0",
            "calculatedAmount": "195.78",
            "calculatedAmountClass": null,
            "debt": "0",
            "paidDebt": "0",
            "paidDebtName": null,
            "paidDebtClass": null,
            "compensation": "0",
            "itemTypeId": "26170",
            "nameUa": "Централізоване постачання гарячої води лічильник. показання на дату оплати",
            "nameEng": "Централізоване постачання гарячої води лічильник. counter meter readings on payment date",
            "itemTypeCode": "677",
            "itemTypeSubCode": "21",
            "readOnly": "N",
            "shortName": "Централізоване постачання гарячої води лічильник. показания на дату оплаты",
            "shortNameUa": "Централізоване постачання гарячої води лічильник. показання на дату оплати",
            "shortNameEng": "Централізоване постачання гарячої води лічильник. counter meter readings on payment date",
            "attribute1": "191555382А",
            "attribute2": "116977",
            "attribute3": "1834",
            "attribute4": null,
            "attribute5": "1",
            "attribute6": null,
            "attribute7": null,
            "attribute8": null,
            "attribute9": null,
            "attribute10": null,
            "payeeName": null,
            "calculated": "N",
            "counterState": "E",
            "counterClass": null,
            "prevCounterState": "N",
            "prevCounterClass": null,
            "tariffState": "V",
            "tariffClass": null,
            "subsidyState": "N",
            "subsidyClass": null,
            "amountState": "N",
            "amountClass": null,
            "debtState": "N",
            "debtClass": null,
            "attribute1State": "V",
            "attribute1Class": null,
            "attribute2State": "N",
            "attribute2Class": null,
            "attribute3State": "N",
            "attribute3Class": null,
            "attribute4State": null,
            "attribute4Class": null,
            "attribute5State": null,
            "attribute5Class": null,
            "tariffName": "тариф",
            "counterName": "поточні",
            "prevCounterName": null,
            "subsidyName": null,
            "debtName": null,
            "attribute1Name": "ID ліч.",
            "attribute2Name": null,
            "attribute3Name": null,
            "attribute4Name": null,
            "attribute5Name": null,
            "compansationName": null,
            "overpayment": null,
            "overpaymentName": null,
            "overpaymentState": null,
            "overpaymentClass": null,
            "amountName": null,
            "id": "425366994",
            "canPaySeparateDebt": null,
            "totalAmount": "0",
            "totalAmountName": null,
            "totalAmountState": "N",
            "totalAmountClass": null,
            "difference": null,
            "differenceName": null,
            "differenceState": null,
            "differenceClass": null,
            "negativeAmount": "N",
            "counterAccuracy": "2",
            "description": null
          },
          {
            "billTariffItemId": "425366995",
            "billId": "802655793",
            "name": "Централізоване постачання гарячої води лічильник",
            "subsidy": "0.00",
            "tariff": "97.89",
            "counter": "2",
            "prevCounter": "1",
            "amount": "0",
            "calculatedAmount": "97.89",
            "calculatedAmountClass": null,
            "debt": "0",
            "paidDebt": "0",
            "paidDebtName": null,
            "paidDebtClass": null,
            "compensation": "0",
            "itemTypeId": "26168",
            "nameUa": "Централізоване постачання гарячої води лічильник",
            "nameEng": "Централізоване постачання гарячої води лічильник",
            "itemTypeCode": "677",
            "itemTypeSubCode": "20",
            "readOnly": "N",
            "shortName": "Централізоване постачання гарячої води лічильник",
            "shortNameUa": "Централізоване постачання гарячої води лічильник",
            "shortNameEng": "Централізоване постачання гарячої води лічильник",
            "attribute1": "191554256А",
            "attribute2": "116977",
            "attribute3": "1834",
            "attribute4": null,
            "attribute5": "2",
            "attribute6": null,
            "attribute7": null,
            "attribute8": null,
            "attribute9": null,
            "attribute10": null,
            "payeeName": null,
            "calculated": "Y",
            "counterState": "V",
            "counterClass": null,
            "prevCounterState": "V",
            "prevCounterClass": null,
            "tariffState": "V",
            "tariffClass": null,
            "subsidyState": "N",
            "subsidyClass": null,
            "amountState": "N",
            "amountClass": null,
            "debtState": "N",
            "debtClass": null,
            "attribute1State": "V",
            "attribute1Class": null,
            "attribute2State": "N",
            "attribute2Class": null,
            "attribute3State": "N",
            "attribute3Class": null,
            "attribute4State": null,
            "attribute4Class": null,
            "attribute5State": null,
            "attribute5Class": null,
            "tariffName": "тариф",
            "counterName": "поточні",
            "prevCounterName": "поперед.",
            "subsidyName": null,
            "debtName": null,
            "attribute1Name": "ID ліч.",
            "attribute2Name": null,
            "attribute3Name": null,
            "attribute4Name": null,
            "attribute5Name": null,
            "compansationName": null,
            "overpayment": null,
            "overpaymentName": null,
            "overpaymentState": null,
            "overpaymentClass": null,
            "amountName": null,
            "id": "425366995",
            "canPaySeparateDebt": null,
            "totalAmount": "0",
            "totalAmountName": null,
            "totalAmountState": "N",
            "totalAmountClass": null,
            "difference": null,
            "differenceName": null,
            "differenceState": null,
            "differenceClass": null,
            "negativeAmount": "N",
            "counterAccuracy": "2",
            "description": null
          },
          {
            "billTariffItemId": "425366996",
            "billId": "802655793",
            "name": "Централізоване постачання гарячої води лічильник. показання на дату оплати",
            "subsidy": "0.00",
            "tariff": "97.89",
            "counter": "2",
            "prevCounter": "0",
            "amount": "0",
            "calculatedAmount": "195.78",
            "calculatedAmountClass": null,
            "debt": "0",
            "paidDebt": "0",
            "paidDebtName": null,
            "paidDebtClass": null,
            "compensation": "0",
            "itemTypeId": "26170",
            "nameUa": "Централізоване постачання гарячої води лічильник. показання на дату оплати",
            "nameEng": "Централізоване постачання гарячої води лічильник. counter meter readings on payment date",
            "itemTypeCode": "677",
            "itemTypeSubCode": "21",
            "readOnly": "N",
            "shortName": "Централізоване постачання гарячої води лічильник. показания на дату оплаты",
            "shortNameUa": "Централізоване постачання гарячої води лічильник. показання на дату оплати",
            "shortNameEng": "Централізоване постачання гарячої води лічильник. counter meter readings on payment date",
            "attribute1": "191554256А",
            "attribute2": "116977",
            "attribute3": "1834",
            "attribute4": null,
            "attribute5": "2",
            "attribute6": null,
            "attribute7": null,
            "attribute8": null,
            "attribute9": null,
            "attribute10": null,
            "payeeName": null,
            "calculated": "N",
            "counterState": "E",
            "counterClass": null,
            "prevCounterState": "N",
            "prevCounterClass": null,
            "tariffState": "V",
            "tariffClass": null,
            "subsidyState": "N",
            "subsidyClass": null,
            "amountState": "N",
            "amountClass": null,
            "debtState": "N",
            "debtClass": null,
            "attribute1State": "V",
            "attribute1Class": null,
            "attribute2State": "N",
            "attribute2Class": null,
            "attribute3State": "N",
            "attribute3Class": null,
            "attribute4State": null,
            "attribute4Class": null,
            "attribute5State": null,
            "attribute5Class": null,
            "tariffName": "тариф",
            "counterName": "поточні",
            "prevCounterName": null,
            "subsidyName": null,
            "debtName": null,
            "attribute1Name": "ID ліч.",
            "attribute2Name": null,
            "attribute3Name": null,
            "attribute4Name": null,
            "attribute5Name": null,
            "compansationName": null,
            "overpayment": null,
            "overpaymentName": null,
            "overpaymentState": null,
            "overpaymentClass": null,
            "amountName": null,
            "id": "425366996",
            "canPaySeparateDebt": null,
            "totalAmount": "0",
            "totalAmountName": null,
            "totalAmountState": "N",
            "totalAmountClass": null,
            "difference": null,
            "differenceName": null,
            "differenceState": null,
            "differenceClass": null,
            "negativeAmount": "N",
            "counterAccuracy": "2",
            "description": null
          }
        ],
        "errorCode": "",
        "errorMessage": ""
      },
      {
        "payeeId": "17495",
        "contractNumber": "12058901418",
        "billId": "802655796",
        "billAmount": "84.16",
        "billTariffItems": [
          {
            "billTariffItemId": "425366998",
            "billId": "802655796",
            "name": "Електропостачання",
            "subsidy": "0.00",
            "tariff": "0",
            "counter": "0",
            "prevCounter": "0",
            "amount": "84.16",
            "calculatedAmount": "84.16",
            "calculatedAmountClass": null,
            "debt": "0",
            "paidDebt": "0",
            "paidDebtName": "спл.борг",
            "paidDebtClass": null,
            "compensation": "0",
            "itemTypeId": "29634",
            "nameUa": "Електропостачання",
            "nameEng": "Power supply",
            "itemTypeCode": "1",
            "itemTypeSubCode": "1",
            "readOnly": "N",
            "shortName": "Электроснабжение",
            "shortNameUa": "Електропостачання",
            "shortNameEng": "Power supply",
            "attribute1": null,
            "attribute2": "84.16",
            "attribute3": null,
            "attribute4": null,
            "attribute5": null,
            "attribute6": null,
            "attribute7": null,
            "attribute8": null,
            "attribute9": null,
            "attribute10": null,
            "payeeName": null,
            "calculated": "Y",
            "counterState": "E",
            "counterClass": null,
            "prevCounterState": "E",
            "prevCounterClass": null,
            "tariffState": "W",
            "tariffClass": null,
            "subsidyState": "E",
            "subsidyClass": null,
            "amountState": "E",
            "amountClass": null,
            "debtState": "E",
            "debtClass": null,
            "attribute1State": "N",
            "attribute1Class": null,
            "attribute2State": "V",
            "attribute2Class": null,
            "attribute3State": "N",
            "attribute3Class": null,
            "attribute4State": null,
            "attribute4Class": null,
            "attribute5State": null,
            "attribute5Class": null,
            "tariffName": "тариф",
            "counterName": "поточ",
            "prevCounterName": "поперед",
            "subsidyName": "субс./пільг",
            "debtName": "борг",
            "attribute1Name": null,
            "attribute2Name": "рек.сума",
            "attribute3Name": null,
            "attribute4Name": null,
            "attribute5Name": null,
            "compansationName": null,
            "overpayment": null,
            "overpaymentName": null,
            "overpaymentState": null,
            "overpaymentClass": null,
            "amountName": "сума",
            "id": "425366998",
            "canPaySeparateDebt": null,
            "totalAmount": "84.16",
            "totalAmountName": "сплачено",
            "totalAmountState": "E",
            "totalAmountClass": null,
            "difference": null,
            "differenceName": null,
            "differenceState": null,
            "differenceClass": null,
            "negativeAmount": "N",
            "counterAccuracy": "0",
            "description": null
          }
        ],
        "errorCode": "",
        "errorMessage": ""
      }
    ]
  },
  "id": "1"
}

10.1.9. Запит для оновлення даних по рахунку

Метод: _ updateTariffItems_

Опис: результатом виклику методу _ updateTariffItems_ є можливість для оновлення суми рахунку.

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

{
  "method": "updateTariffItems",
  "params": {
    "data": {
      "sessid": "3ek43kplfjlho2ndn75a66g6u11",
      "billId": "",
      "billTariffItemId": "",
      "tariff": "",
      "counter": "",
      "prevCounter": "",
      "subsidy": "",
      "debt": "",
      "paidDebt": "",
      "amount": "",
      "attribute1": "",
      "attribute2": "",
      "attribute3": ""
    }
  },
  "id": "1"
}

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

{
  "result": true,
  "id": "1"
}

10.1.10. Запит інформації про доступні компанії-біллери

Метод: _ payees_

Опис: результатом виклику методу payees є отримання рахунків.

Параметри:

Параметр	Опис	Обов’язковий
sessid	Параметр, який отримали за допомогою методу getsessid	Так
direct	Параметр, яки завжди приймає значення Y	Так
id	Константа	Так

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

{
  "method": "payees",
  "params": {
    "data": {
      "sessid": "vsgput63liar2ktfn1dau7m3of",
      "direct": "Y"
    }
  },
  "id": "1"
}

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

{
    "result": [
        {
            "payeeId": "1003",
            "merchant": null,
            "terminal": null,
            "name": "Укртелеком м. Київ",
            "nameInCheck": "АТ \"УКРТЕЛЕКОМ\"",
            "billMessage": "<b>Без комісії</b>",
            "requestBillMessage": "Особовий рахунок повинен складатись із 16 цифр.",
            "contractNumberTitle": "Особовий рахунок",
            "contractNumberType": "C",
            "contractNumberTypeFormat": null,
            "contractNumberSize": "16",
            "contractNumberMask": null,
            "contractNumberHint": null,
            "attribute1": null,
            "attribute2": null,
            "attribute3": null,
            "attribute4": null,
            "attribute5": null,
            "attribute1Title": "Номер телефону",
            "attribute1Type": "C",
            "attribute1TypeFormat": null,
            "attribute1Size": null,
            "attribute1ForInfo": "Y",
            "attribute1Mask": null,
            "attribute1Hint": null,
            "attribute2Title": "Адреса",
            "attribute2Type": "C",
            "attribute2TypeFormat": null,
            "attribute2Size": null,
            "attribute2ForInfo": "Y",
            "attribute2Mask": "type:address",
            "attribute2Hint": null,
            "attribute3Title": null,
            "attribute3Type": "C",
            "attribute3TypeFormat": null,
            "attribute3Size": null,
            "attribute3ForInfo": "N",
            "attribute3Mask": null,
            "attribute3Hint": null,
            "attribute4Title": null,
            "attribute4Type": "C",
            "attribute4TypeFormat": null,
            "attribute4Size": null,
            "attribute4ForInfo": "N",
            "attribute4Mask": null,
            "attribute4Hint": null,
            "payeeGroupId": "1006",
            "bankCode": "300346",
            "bankName": "АТ \"Сенс Банк\"",
            "bankAccount": "UA463003460000026007010194910",
            "zkpo": "21560766"
        },
        ....
      ]
}

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

{
  "error": {
    "code": 400,
    "message": "Оновіть sessid",
    "data": {}
  },
  "id": "1"
}

10.2. Оплата рахунку за допомою Gateway

Опис:

Для здійснення оплати отриманого рахунку необхідно виконати запит на адресу: https://www.portmone.com.ua/gateway/. Перед запитом на форму оплати необхідно отримати параметр credentials через метод getcredentials зі значенням sessid отриманного в розділі 10.1.1.:

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

{
  "method": "getcredentials",
  "params": {
    "data": {
      "sessid": "3ek43kplfjlho2ndn75a66g6u11"
    }
  },
  "id": "1"
}

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

{
  "result": {
    "credentials": "000186f6a4e33bf33625e9afdabc99afc7f7010085c89209407dd5ad0ea5074d83f3d0f73aecc606700f7c0a27bbc9189d82e5ba219a006cac545c57f4f883df76dccf0a100816964106057730fa953087a0a5fa75edb74ef26ab6e34f107d4828ed1718820addc1b915009d51b9671c601d9604f6894280ef20d6293cb22b528e4004e6fa6f00578e6373dd88ed7b71d61967b7aa08025732514294057b2eeca97c5d8da5cd0252f60a2751122b004280b156b409f69e457ee3039648dbc6e8a1a4ee68462599b314b4409630fbd965a9723583cd853a2becced809ee4101a4913cb7e8d81f3807387c2cb92e17b46d960cd26decafde037cfa1cd4396cfedd0b128e0b07ebe5279c5ee769c62d5929bec4894e1b80208be948564b4cbc670c01acc22225cb8e8beff1867cd32c6c0bc5fc30d898"
  },
  "id": "1"
}

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

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

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

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

Параметри для формування JSON-структури запиту:

1. paymentTypes – блок дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).

Параметр	Опис	Обов’язковий
card	Для оплати рахунку за допомогою картки необхідно вказати значення "Y" для цього параметру	Так
gpay	Для оплати рахунку за допомогою GooglePay необхідно вказати значення "Y" для цього параметру	Так
applepay	Для оплати рахунку за допомогою ApplePay необхідно вказати значення "Y" для цього параметру	Так

2. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

3. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

4. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні

5. bill – налаштування для роботи з рахунком

Параметр	Опис	Обов’язковий
id	id рахунку	Обов’язкове значення
billAmount	Сума рахунку	Обовязкове значення

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська, uk – українська мова	Ні
emailAddress	Адреса електронної пошти платника	Ні

7. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

8. credentials – параметр отриманий в данному розділі.

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

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

10.3. Отримання посилання для сплати рахунку

Опис:

Для отримання посилання необхідно виконати запит на адресу: https://www.portmone.com.ua/r3/uk/api/merchant-bills .

Перед запитом на форму оплати необхідно отримати параметр credentials через метод getcredentials зі значенням sessid отриманного в розділі 10.1.1.:

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

{
  "method": "getcredentials",
  "params": {
    "data": {
      "sessid": "3ek43kplfjlho2ndn75a66g6u11"
    }
  },
  "id": "1"
}

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

{
  "result": {
    "credentials": "000186f6a4e33bf33625e9afdabc99afc7f7010085c89209407dd5ad0ea5074d83f3d0f73aecc606700f7c0a27bbc9189d82e5ba219a006cac545c57f4f883df76dccf0a100816964106057730fa953087a0a5fa75edb74ef26ab6e34f107d4828ed1718820addc1b915009d51b9671c601d9604f6894280ef20d6293cb22b528e4004e6fa6f00578e6373dd88ed7b71d61967b7aa08025732514294057b2eeca97c5d8da5cd0252f60a2751122b004280b156b409f69e457ee3039648dbc6e8a1a4ee68462599b314b4409630fbd965a9723583cd853a2becced809ee4101a4913cb7e8d81f3807387c2cb92e17b46d960cd26decafde037cfa1cd4396cfedd0b128e0b07ebe5279c5ee769c62d5929bec4894e1b80208be948564b4cbc670c01acc22225cb8e8beff1867cd32c6c0bc5fc30d898"
  },
  "id": "1"
}

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

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

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

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

Параметри для формування JSON-структури запиту:

1. paymentTypes – блок дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).

Параметр	Опис	Обов’язковий
card	Для оплати рахунку за допомогою картки необхідно вказати значення "Y" для цього параметру	Так
gpay	Для оплати рахунку за допомогою GooglePay необхідно вказати значення "Y" для цього параметру	Так
applepay	Для оплати рахунку за допомогою ApplePay необхідно вказати значення "Y" для цього параметру	Так

2. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

3. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

4. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні

5. bill – налаштування для роботи з рахунком

Параметр	Опис	Обов’язковий
id	id рахунку	Обов’язкове значення
billAmount	Сума рахунку	Обовязкове значення

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

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

10.4. Масова оплата рахунку за допомою Gateway

Опис:

Даний метод дозволяє оплатити одночасно кілька рахунків. У відповідь отримаєте посилання на оплату. Для здійснення запитів використовуйте адресу: https://www.portmone.com.ua/r3/uk/api/merchant-bills .

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

Максимальна кількість рахунків для однієї оплати - 10.

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

Параметри для формування JSON-структури запиту:

Параметр	Опис	Обов’язковий
credentials	Параметри авторизації	Так
token	Токен, який був отриманий для масових оплат рахунків	Так
bills	Масив рахунків billId (максимальна кількість - 10)	Так

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

{
  "method":"payment",
  "params": {
     "data": {
       "credentials": "89743386f7fbc474d38ab2f4665a0d40e1dc37518b39296273576b00db1bd96b728eb9b7b96d947a064c7e0ec9",
       "token": "7E1DF0F539AD0269714FE6DB9EDEE82390779943F634662DF08594BDF34AECACDBB3A9280046B95897C64EA70CF44A",
       "bills":[{"id":"2266395477"}, {"id":"2266395478"}, {"id":"2266396128"}, {"id":"2266395475"}, {"id":"2266394511"}]
      }
  },
  "id":"1"
}

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

{
    "result": {
        "link": "https://prt.mn/gj0uTp_ix"
    },
    "id": "1"
}

**Опис отримання параметру credentials **

Даний параметр можна отрмати за допомогою методу getcred

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

Параметри для формування JSON-структури запиту:

Параметр	Опис	Обов’язковий
login	Логін компанії-реселера в системі Portmone.com	Так
password	Пароль компанії-реселера в системі Portmone.com	Так
id	Константа	Так

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

{
  "method":"getcred",
  "params": {
     "data": {
       "login": "",
       "password": ""
      }
  },
  "id":"1"
}

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

{
    "result": {
        "credentials": "7d41aaf61d701cd93833d738ffd2e273a2cfa112237a4b32b21512e8ff9755c9ea41c0096bb09da1ea8e2b7337452a23"
    },
    "id": "1"
}

Опис отримання параметру token

Даний параметр можна отрмати за допомогою методу createToken У відповідь отримаєте link - посилання для збереження токену.

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

Параметри для формування JSON-структури запиту:

Параметр	Опис	Обов’язковий
credentials	Параметри авторизації	Так
description	Постійна велечина, яка характерезує клієнта (номер телефону тощо). До 250 символів	Так
successUrl	Адреса компанії-реселера, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Так
id	Константа	Так

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

{
    "method": "createToken",
    "params": {
        "data": {
            "credentials": "",
            "description": "",
            "successUrl":""
        }
    },
    "id": "1"
}

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

{
    "result": {
        "link": ""
    },
    "id": "1"
}

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

Параметр	Опис
SHOPBILLID	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
RESULT	Результат виконання операції (у разі успіху = 0)
TOKEN	Значення Токену для подальших оплат
CARD_MASK	Маска Картки платника
DESCRIPTION	Постійна велечина, яка характерезує клієнта (номер телефону тощо). До 250 символів

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

'SHOPBILLID'          => '411587640',
'RESULT'              => '0',
'TOKEN'               => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE016',
'CARD_MASK'           => '516874******5179',
'DESCRIPTION'         => 'test',

11. Використання Gateway для мобільних додатків

Для інтеграції платіжного шлюзу Potrmone.com у мобільні додатки (наприклад, iOS або Android) можливо використовувати механізми custom-URL. Вони дозволяють викликати з додатку сторінку платіжного шлюзу з необхідними параметрами і після оплати отримати управління назад у додаток.

Приклад, як це можливо зробити для iOS додатків:

Звернення до url на оплату робиться методом GET (! а не POST) з передачею усіх параметрів, що вказані в нашій документації з підключення Інтернет-магазину.

У якості параметрів success_url та failure_url необхідно вказати url-и, в яких замість https протоколу вказаний певний custom utl type, що зареєстрований в iOS додатку Інтернет-магазину.

Наприклад, якщо в iOS-додатку зареєстрований наступний url type: “customurl”, то параметри success_url та failure_url будуть виглядати так:

success_url = “customurl://success” failure_url = “customurl://failure”

URL виклику сервісу Portmone.com буде виглядати так:

https://www.portmone.com.ua/gateway/?payee_id=1185&bill_amount=123.56 &shop_order_number=shopordernumber1&description=My%20test &success_url=customurl://success&failure_url=customurl://failure

де:

payee_id = 1185 – ID Інтернет-магазину

bill_amount = 123.56 – сума до сплати за замовленням

shop_order_number = shopordernumber – номер замовлення

description = “My test” – коментар до замовлення

В результаті такого виклику буде відкритий браузер із стандартною сторінкою оплати замовлення, де необхідно ввести реквізити картки. За результатами виконання оплати буде викликаний або success_url, або failure_url з параметрів первинного запиту магазину, та відповідно буде виконаний переход до iOS-програми Інтернет-магазину.

Зовнішній вигляд сторінки, адаптованої для екрану смартфонів, показаний на малюнку:

12. Виставлення рахунків клієнтам

Платіжний шлюз Portmone.com дозволяє виставляти рахунки (замовлення) на оплату по e-mail або SMS.

12.1. Відправка рахунку по e-mail

Для відправки рахунку по e-mail необхідно викликати форму з наступними параметрами:

Параметр	Опис	Обов’язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів	Ні
namePayer	Ім’я Клієнта	Ні
comment	Коментар до оплати	Ні
amount	Сума оплати	Так
emailRecipient	Адреса електронної пошти Клієнта	Так
lang	Мова листа	Ні
cc_email	Електронна адреса, на яку буде надіслано копію рахунку	Ні
preauth_flag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
bill_currency	Валюта проведення платежу. Можливі значення: UAH, USD, EUR, GBP, PLN, KZT (значення без задання – UAH)	Ні
exp_date	Встановлює час, до якого Клієнт може сплатити рахунок. По закінченню зазначеного часу рахунок переходить в статус "REJECTED" і оплатити його неможливо. Передається у форматі: ррррммддггххсс (наприклад, 20181208130724)	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»)	Ні

Приклади:

Дивіться "12.1 Форма для відправки рахунку по e-mail".

12.2. Відправка рахунку за допомогою SMS

Для відправки рахунку за допомогою SMS необхідно викликати форму з наступними параметрами:

Параметр	Опис	Обов’язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів	Ні
namePayer	Ім’я Клієнта	Ні
comment	Коментар до оплати	Ні
amount	Сума оплати	Так
phoneRecipient	Номер мобільного телефону Клієнта	Так
lang	Мова SMS-повідомлення	Ні
preauth_flag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
bill_currency	Валюта проведення платежу. Можливі значення: UAH, USD, EUR, GBP, PLN, KZT (значення без задання – UAH)	Ні
expDate	Встановлює час, до якого Клієнт може сплатити рахунок. По закінченню зазначеного часу рахунок переходить в статус "REJECTED" і оплатити його неможливо. Передається у форматі: ррррммддггххсс (наприклад, 201812080724)	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу. Максимальна кількість символів - 500 (див. розділ 7 «Розщеплення платежу»)	Ні

Приклади:

Дивіться "12.2 Форма для відправки рахунку по SMS".

При отриманні такого рахунку на оплату, клієнт отримає повідомлення наступного змісту:

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

12.3. Масове виставлення рахунків на оплату по e-mail або SMS

Опис:

Для масового виставлення рахунків по e-mail або SMS необхідно надіслати запит на такий URL: https://www.portmone.com.ua/r3/api/gateway/.

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

У блоці даних повинно бути мінімум 5 обов'язкових параметрів, що заповнені в суворій послідовності (див. таблицю з описом параметрів запиту). Також є 4 додаткові параметри, які заповнюються за необхідності.

За один раз можливо виставити максимум 100 рахунків.

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

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

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

Порядок у блоці даних	Параметр	Опис	Обов’язковий
1	ПІБ одержувача	Ім’я Клієнта, яке буде відображатись у рахунку, що надійде	Так
2	E-mail одержувача або номер телефону одержувача	Адреса електронної пошти або номер мобільного телефону Клієнта. Номер телефону необхідно вказувати у форматі "+380ХХХХХХХХХ"	Так
3	Номер замовлення	Номер замовлення (рахунку) у системі Інтернет-магазину. До 120 символів	Так
4	Призначення платежу	Коментар до замовлення/ опис призначення оплати	Так
5	Сума	Сума оплати	Так
6	Валюта	Валюта проведення платежу. Можливі значення: UAH, USD, EUR, GBP, KZT, PLN (значення без задання – UAH)	Ні
7	Преавторизація	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації. Значення без задання – "N")	Ні
8	Мова рахунку	Мова електронного листа або SMS-повідомленя. Може приймати значення: uk – українська мова, en – англійська. Якщо параметр не переданий, то рахунок виставляється українською мовою	Ні
9	Термін дії рахунку	Встановлює час, до якого Клієнт може сплатити рахунок. По закінченню зазначеного часу рахунок переходить в статус "REJECTED" і оплатити його неможливо. Передається у форматі: ррррммддггххсс (наприклад, 20181208130724)	Ні

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

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

12.4. Отримання платіжного посилання

Опис:

Якщо не вказувати значення expDate, тоді посилання не матиме строку дії. Для отримання платіжного посилання необхідно надіслати запит на такий URL: https://www.portmone.com.ua/r3/api/gateway/.

Доступність і обмеження: Немає обмежень.

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

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

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

Параметр	Опис	Обов’язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
amount	Сума оплати	Так
shopOrderNumber	Номер замовлення (рахунку) у системі Інтернет-магазину. До 128 символів	Ні
emailRecipient	Адреса електронної пошти Клієнта, яка буде автоматично заповнена на сторінці оплати	Ні
description	Коментар до оплати. Максимальна кількість символів 250	Ні
preauth_flag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
bill_currency	Валюта проведення платежу. Можливі значення: UAH, USD, EUR, GBP, PLN, KZT (значення без задання – UAH)	Ні
installment	Параметри розтермінування оплати для інвойсу. Дозволяють сформувати платіжне посилання з оплатою частинами через банки-партнери Portmone. Формат параметра, перелік банків та правила використання наведені у розділі 3.7 «Розтермінування».	Ні
expDate	Встановлює час, до якого Клієнт може сплатити рахунок. По закінченню зазначеного часу рахунок переходить в статус "REJECTED" і оплатити його неможливо. Передається у форматі: ррррммддггххсс (наприклад, 20181208130724)	Ні
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»). Максимальна кількість символів 500	Ні

1. goods – блок, що містить масив даних для фіскалізації.

Параметр	Опис	Обов’язковий
internalCode	Код продавця	Так
manufacturerCode	Код виробника	Ні
govClassificationCode	Код УКТЗЕД	Ні
name	Назва товару\послуги	Так
name_en	Назва товару\послуги EN	Ні
description	Опис товару\послуги	Ні
description_en	Опис товару\послуги EN	Ні
price	Ціна ( шт)	Так
quantity	Кількість	Так
uomCode	Одиниця виміру ( не обов'язково, за замовчуванням шт)	Ні
amount	Сума	Так
taxRateCodes	Цифровий код ставки податку (попередньо програмується у особистому кабінеті податкового агента). Якщо до товару потрібно застосувати декілька податків — вказати через кому, наприклад: "1,2"	Так
descriptionUrl	Посилання на опис товару	Ні
imageUrl	Посилання на картинку товару	Ні
barcode	Штрих-код товару	Ні
serviceFlag	Ознака послуги. Визначає тип позиції в чеку для фіскалізації. N — товар	Ні
discount	Сума знижки по позиції товару в гривнях	Ні
discountName	Назва знижки	Ні

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

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

12.5. Створення платіжного посилання

Опис:

Метод дозволяє створти платіжне посилання і отримати його на сервер мерчанта. Підходить для використання у Instagram, Facebook. Якщо не вказати expTime то цей виклик не створює інвойс, а складає дані в сесію, яка живе 15 хв після останнього звернення до неї. Для створення платіжного посилання необхідно надіслати запит на такий URL: https://www.portmone.com.ua/gateway/.

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

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

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

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

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

1. payee – блок, що необхідний для ідентифікації партнера

Параметр	Опис	Обов’язковий
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
login	Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
dt	Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature)	Так
signature	Підпис запиту	Так
displayMessage	Відображення інформації на платіжній сторінці для клієнта: <font style=\"font-size:14px;\">Hello</font> %username% !	Ні
shopSiteId	Цифровий ідентифікатор каналу продажу	Ні

2. order – блок, що містить опис платежу

Параметр	Опис	Обов’язковий
description	Опис платежу (коментар до замовлення/призначення оплати). Максимальна кількість символів 250	Ні
shopOrderNumber	Номер замовлення, що сплачується, у системі Партнера. Максимальна кількість символів 128	Ні
billAmount	Сума платежу	Так
successUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати. Максимальна кількість символів 250	Ні
failureUrl	Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати. Максимальна кількість символів 250	Ні
preauthFlag	Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації)	Ні
billCurrency	Валюта проведення платежу. Значення без задання: UAH	Ні
expTime	Встановлює інтервал, протягом якого замовлення може бути оплачене. Якщо значення параметру було передане, то з моменту виклику платіжної сторінки показується зворотний відлік, який видно Клієнту на сторінці оплати. По закінченню часу на оплату рахунок переходить в статус "REJECTED" і оплатити його неможливо	Ні
encoding	Кодування (кодує текст запиту з встановленого кодування у UTF-8)	Ні
attribute1	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute2	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute3	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute4	Службове поле, заповнюється на розсуд компанії. Максимальна кількість символів 1000	Ні
attribute5	Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»). Максимальна кількість символів 500	Ні

3. paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".

Параметр	Опис	Обов’язковий
card	Оплата Карткою	Ні
portmone	Оплата через гаманець Portmone.com	Ні
token	Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються)	Ні
privat	Оплата через систему LiqPay, з вибором картки з Інтернет-банкінгу Приват24. Зверніть увагу! При оплаті через Приват24 функціонал преавторизації не працює	Ні
gpay	Оплата через систему Google Pay, з вибором картки з тих, що були раніше збережені в акаунті Google Pay	Ні
createtokenonly	Створення Токену для проведення платежів за Токеном (у разі активації цього параметру, інші способи не відображаються). Параметр надає можливість отримати Токен Картки без проведення реальної оплати (на рахунку блокується 1 грн, яка повертається протягом 30 хвилин). Підходить для звичайних оплат на користь Інтернет-магазину (див. розділ 4 «Оплата замовлення з використанням платіжного токену»), а також для подальшого використання у рамках платежів з картки на картку (див. розділ 5 «Переказ з картки на картку»)	Ні
applepay	Оплата через систему Apple Pay, з вибором картки з тих, що були раніше збережені в акаунті Apple Pay	Ні
installment	Розстрочка платежу (Розтермінування)	Ні
link	Оплата методом BankPay (через застосунок Банка платника). Метод працює за умови передачі таких параметрів: expTime та "showEmail": "Y"	Ні

4. priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.

Важливо! У paymentTypes спосіб оплати повинен бути в значенні "Y", у priorityPaymentTypes – мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).

5. token – налаштування для роботи з Токеном (див. розділ 4 «Оплата замовлення з використанням платіжного токену»)

Параметр	Опис	Обов’язковий
tokenFlag	Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних)	Обов’язковий параметр для оплати за Токеном
returnToken	"Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера	Ні
token	Значення Токену	Обов’язковий параметр для оплати за Токеном
cardMask	Маска Картки	Обов’язковий параметр для оплати за Токеном
otherPaymentMethods	Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає)	Ні

6. payer – блок описує налаштування платника

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника	Ні
showEmail	"Y" або порожнє значення – вмикає відображення поля "e-mail" на сторінці оплати, "N" – приховує поле "e-mail" на сторінці оплати (значення без задання – "Y")	Ні

В залежності від переданих значень параметрів emailAddress та showEmail можливі 4 варіанти відображення поля "e-mail" на сторінці оплати:

Варіант	emailAddress	showEmail	Відображення на сторінці оплати
1	порожнє значення	Y	Відображається порожнє поле вводу e-mail
2	валідний e-mail	Y	Відображається попередньо заповнене поле вводу e-mail з можливістю редагування
3	порожнє значення	N	Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною
4	валідний e-mail	N	Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною. Однак e-mail, що переданий у запиті, обробляється і на нього надсилається квитанція про сплату

7. installmentPlan – параметри розстрочки платежу (див. розділ 3.7 «Розтермінування»).

8. autopayment – цей блок дозволяє налаштувати функціонал автоматичних оплат.

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

Для початку роботи з автоматичними платежами Партнеру необхідно отримати credentials в Особистому кабінеті.

Зверніть увагу! При зміні паролю необхідно сформувати credentials заново.

Після налаштування:

1. Буде створено підписку на виконання автоматичних оплат з Картки Клієнта. Portmone.com самостійно відстежує та проводить платіж. Клієнт може відключити послугу, звернувшись до підтримки Portmone.com або до співробітника Інтернет-магазину (Інтернет-магазин може самостійно видалити підписку Клієнта в Особистому кабінеті).

2. Всі наступні оплати будуть виконуватись на той же опис (description), що і при першій оплаті.

3. Номер замовлення для автоматичних оплат буде формуватись наступним чином:

   Номер замовлення при першій оплаті_RECURENT_Дата автоматичного списання

Параметр	Опис	Обов’язковий
show	Можливість для клієнта бачити на сторінці оплати деталі підписки на автоматичну оплату. Приймає значення: Y – клієнт може перейти на окрему сторінку та подивитись параметри підписки; N – клієнт не має можливості бачити деталі підписки (відображається тільки чекбокс "Зробити платіж регулярним") (див. мал. 1)	Ні
edit	Можливість для клієнта редагувати параметри автоматичної оплати. Приймає значення: Y – при переході на сторінку деталей підписки всі параметри можна редагувати, є можливість зберегти налаштування (див. мал. 2); N – відображаються параметри автоматичної оплати, що передані Інтернет-магазином, без можливості редагувати	Ні
settings	Блок параметрів для налаштування автоматичної оплати	Ні
credentials	Параметри авторизації	Так
changeCheckboxState	Значення автоплатежу Y	Так
defaultCheckboxState	Приймає значення: Y – чекбокс "Зробити платіж регулярним" автозаповнений; N – клієнт самостійно заповнює чекбокс "Зробити платіж регулярним"	Ні

Структура блоку settings:

Параметр	Опис	Обов’язковий
period	Періодичність автоматичних списань. Приймає наступні значення: 1 – щомісячно, 2 – щоквартально, 3 – щопівроку, 4 – щороку	Так
payDate	День проведення автоматичного списання. Приймає значення від 1 до 28	Ні
startDate	Дата початку автоматичних списань. Передається у форматі: DD.MM.YYYY. Якщо параметр не переданий, автоматично проставиться вчорашня дата	Ні
endDate	Дата закінчення автоматичних списань. Передається у форматі: DD.MM.YYYY. Якщо параметр не переданий, автоматично проставиться дата startDate + 3 роки (якщо startDate не задано – поточна дата платежу)	Ні
amount	Сума автооплати. При наявності дробової частини використовується розділювач крапка (".")	Так

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

Мал. 2 – приклад відображення параметрів автоматичної оплати з можливістю редагування

9. goods – блок, що містить масив даних для фіскалізації.

Параметр	Опис	Обов’язковий
internalCode	Код продавця	Так
manufacturerCode	Код виробника	Ні
govClassificationCode	Код УКТЗЕД	Ні
name	Назва товару\послуги	Так
name_en	Назва товару\послуги EN	Ні
description	Опис товару\послуги	Ні
description_en	Опис товару\послуги EN	Ні
price	Ціна ( шт)	Так
quantity	Кількість	Так
uomCode	Одиниця виміру ( не обов'язково, за замовчуванням шт)	Ні
amount	Сума	Так
taxRateCodes	Цифровий код ставки податку (попередньо програмується у особистому кабінеті податкового агента). Якщо до товару потрібно застосувати декілька податків — вказати через кому, наприклад: "1,2"	Так
descriptionUrl	Посилання на опис товару	Ні
imageUrl	Посилання на картинку товару	Ні
barcode	Штрих-код товару	Ні
serviceFlag	Ознака послуги. Визначає тип позиції в чеку для фіскалізації. N — товар	Ні
discount	Сума знижки по позиції товару в гривнях	Ні
discountName	Назва знижки	Ні

Показати приклад JSON-структури блоку goods

{
  "goods": [
    {
      "internalCode": "123456",
      "manufacturerCode": "123456",
      "govClassificationCode": "123456",
      "name": "",
      "name_en": "",
      "description": "",
      "description_en": "",
      "price": "100",
      "quantity": "2",
      "uomCode": "",
      "amount": "200",
      "serviceFlag": "N",
      "taxRateCodes": "1",
      "descriptionUrl": "",
      "imageUrl": "",
      "barcode": "1234567890",
      "discount": "10.00",
      "discountName": "Знижка"
    }
  ]
}

10. style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).

11. shipping – блок, що містить інформацію про доставку

Доставка "Нова Пошта"

Даний функціонал дозволяє оформити доствку "Нової Пошти".

Параметр	Опис	Обов’язковий
state	Y - підключаєтсья доставка, N - доставка вимкнена	Так
source	Назва служби доставки. Приймає значенн novaposhta	Так

Приклад масиву в запиті:

"shipping": {
        "collect": {
            "state": "Y",
            "source": "novaposhta"
        }

Щоб передзаповнити поля на сторінці оплати необхідно передати дані Клієнта в блоці payer

"payer": {
        "lang": "uk",
        "emailAddress": "[email protected]",
        "showEmail": "Y",
        "phoneNumber": "660000000",
        "fullName": "Прізвище Ім'я"
    }

Параметр	Опис	Обов’язковий
lang	Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська	Ні
emailAddress	Адреса електронної пошти платника (надсилаємо клієнту квитанцію про успішну оплату, не передаємо у відповідь на запит)	Так
showEmail	Приймає значення "Y"	Так
phoneNumber	Номер телефону Клієнта. Передавати у форматі 660000000	Так
fullName	Прізвище та Ім'я Клієнта	Так

Доступні 3 типи доставки:

• У відділення
• До поштомату
• Кур’єром

Поля “Місто”, “Вулиця”, “Відділення”, “Поштомат” є випадаючим списком з пошуком на сторінці оплати, пошук починається після введення 3 символів. Редагувати дані доставки можна натиснувши кнопку "назад"

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

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

12.6 Запит на закриття рахунку

Опис:

Метод дозволяє закрити виставлений рахунок в статусі CREATED та REJECTED (рахунок стає неактнивним).

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

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

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

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

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

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

Параметр	Опис	Обов’язковий
method	Значення: closeInvoice	Так
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
shopOrderNumber	Номер замовлення в Інтернет-магазині. Максимальна кількість символів 128	Так

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

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

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

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

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

Опис:

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

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

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

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

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

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

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

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

Блок identification (ідентифікація відправника/отримувача).

Дані відправника

sender

Параметр	Опис	Обов’язковий
firstName	Ім'я відправника. У разі юридичної особи вказувати назву ТОВ "Квітка" або ФОП ПІБ	Так
lastName	Приізвище відправника. У разі юридичної особи вказувати назву ТОВ "Квітка" або ФОП ПІБ	Так
firstName	Ім'я по батькові відправника	Ні
account_number	Номер розрахункового рахунку відправника	Так

senderAddress

Параметр	Опис	Обов’язковий
countryCode	Код країни реєстрації	Так
city	Місто реєстрації	Так
address	Адреса реєстрації	Так
zipCode	Код	Ні

Дані одержувача

recipient

Параметр	Опис	Обов’язковий
dstFirstName	Ім'я одержувача	Так
dstLastName	Прізвище одержувача	Так
dstMiddleName	Ім'я по батькові одержувача	Ні
tax_id	ІПН одержувача	Так

В блоці taxes вказують суму податків

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

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

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

Параметр	Опис	Обов’язковий
client_id	ПІБ отримувача коштів	Так
income	Сума ПДФО в копійках	Так
social	Сума ЄСВ в копійках	Так
military	Сума ВЗ в копійках	Так
date_of_birth	Дата народження отримувача коштів. Передається у форматі YYYYMMDD	Так, у разі без сплати податків
tax_id	ІПН отримувача коштів	Так

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

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

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

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

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

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

14. Фіскалізація

Опис:

Дозволяє здіснювати реєстрації розрахункових операцій та передачу інформації про фінансові транзакції до державних податкових органів.

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

Термін	Визначення
Фіскалізація	Процес реєстрації розрахункових операцій та передачу інформації про фінансові транзакції до державних податкових органів.
Податкова ставка	Це ставка податку яка застосовується до операцій продажу товарів або послуг, визначається державними органами і може відрізнятися в залежності від типу товару або послуги, регіону, в якому проводяться операції, а також інших факторів.
Зміна	Період передачі даних до податкової з моменту першої фіскалізації оплати після останнього Z-звіту та до формування наступного.
Фіскальний чек	Документ, який формується в результаті здійснення реєстрації розрахункової операції. Містить інформацію про фінансову транзакцію між платником і мерчантом, включаючи дату і час операції, назву товару або послуги, їх кількість та ціну, загальну суму оплати, а також податкові реквізити.
Код УКТзЕД	Система кодів, яка використовується для класифікації товарів при зовнішньоекономічних операціях, тобто при здійсненні міжнародної торгівлі товарами. Ця система регламентується Державною митною службою України та відображається в "Класифікаторі товарів зовнішньоекономічної діяльності".

14.1 Отримання податкових ставок ПРРО

Опис: Цей метод дозволяє отримати податкові ставки ПРРО для подальшого використання їх при фіскалізації. Запит необхідно виконати на адресу: https://www.portmone.com.ua/r3/api/gateway

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

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

Параметр	Опис	Обов’язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
id	Константа	Так

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

{
  "method": "getListTaxes",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451"
    }
  },
  "id": "1"
}

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

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

Параметр	Опис
uuid	Унікальний ідентифікатор у форматі UUID
code	Цифровий код податкової ставки
label	Назва податкової ставки
symbol	Літерний код податкової ставки
rate	Розмір податкової ставки у відсотках
extra_rate	Розмір додаткового збору у відсотках
included	Тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо.
created_at	Мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
updated_at	Мітка часу останньої зміни параметрів податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
no_vat	Індикатор податку, податок виключений/податок включений (true/false)
advanced_code	Поле для внутрішньої інформації (не використовується)
decimal_rate	Розмір податкової ставки десятковий
decimal_extra_rate	Розмір додаткового збору десятковий
id	Константа

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

{
  "result": [
    {
      "uuid": "16edb3d1-8669-4006-b16d-c483a92c33eb",
      "code": "1",
      "label": "Без ПДВ",
      "symbol": "Є",
      "rate": "0",
      "extra_rate": null,
      "included": "true",
      "created_at": "18-JUL-24 05.57.37.637059000 PM +03:00",
      "updated_at": null,
      "no_vat": "true",
      "advanced_code": null,
      "decimal_rate": "0",
      "decimal_extra_rate": null
    }
  ],
  "id": "1"
}

14.2 Ручна фіскалізація оплати/фіскалізація повернення оплати

Опис: Цей метод дозволяє вручну здійснити фіскалізацію оплати або фіскалізацію повернення оплати. Запит необхідно виконати на адресу: https://www.portmone.com.ua/r3/api/gateway

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

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

Параметр	Опис	Обов’язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
sendFiscalReceipt	Параметер відправки фіскального чека. Може приймати значення: : - Y – відправляти, - N – не відправляти	Так
id	Константа	Так

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

{
  "method": "createFiscalReceipt",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "shopBillId": "1776344335",
      "payeeId": "1185",
      "sendFiscalReceipt": "Y"
    }
  },
  "id": "1"
}

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

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

Параметр	Опис
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
fiscalized	Статус фіскалізації. Може приймати значення: : - Y – фіскалізовано, - N – не фіскалізовано
fiscalCode	Номер фіскального чека
billAmount	Сума транзакції
fiscalUrl	Посилання на зображення фіскального чека
id	Константа

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

{
  "result": {
    "shopBillId": "1776341932",
    "fiscalized": "Y",
    "fiscalCode": "TEST-QlJczi",
    "billAmount": "3.2",
    "fiscalUrl": "https://check.checkbox.ua/TEST-QlJczi"
  },
  "id": "1"
}

14.3 Відправка фіскального чеку на email користувача

Опис: Цей метод дозволяє здійснити відправку фіскального чеку вказавши в параметрі email користувача. Запит необхідно виконати на адресу: https://www.portmone.com.ua/r3/api/gateway

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

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

Параметр	Опис	Обов’язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com	Так
payeeId	Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com	Так
emails	Адреса електронної пошти платника	Так
id	Константа	Так

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

{
  "method": "sendFiscalReceipt",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "1185",
      "shopBillId": "1775990208",
      "emails": "[email protected]"
    }
  },
  "id": "1"
}

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

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

Параметр	Опис
status	Статус відправки. Може приймати значення: : - **SUCCES ** – відправлене, - **FAILURE ** – не відправлене
id	Константа

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

{
  "result": {
    "status": "sucess"
  },
  "id": "1"
}

14.4 Запит статусу фіскалізації оплати

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

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

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

Параметр	Опис	Обов’язковий
login	Логін Інтернет-магазину для доступу до управління акаунтом	Так
password	Пароль Інтернет-магазину	Так
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com	Так

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

{
  "method": "getFiscalStatus",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "shopBillId": "1776341308"
    }
  }
}

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

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

Параметр	Опис
shopBillId	Ідентифікатор транзакції (платіжного документу) у системі Portmone.com
billAmount	Сума транзакції
fiscalized	Статус фіскалізації. Може приймати значення: : - Y – фіскалізовано, - N – не фіскалізовано
receiptNumber	Номер фіскального чека
fiscalUrl	Посилання на зображення фіскального чека

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

{
  "shopBillId": "1776341308",
  "billAnount": "3.2",
  "fiscalized": "Y",
  "receiptNumber": "TEST-NOupeS",
  "fiscalUrl": "https://check.checkbox.ua/TEST-NOupeS"
}

Приклади

До розділу 3 «Оплата замовлення»

3.1 Запит оплати замовлення методом POST

<form action="https://www.portmone.com.ua/gateway/" method="post">
  <input type="hidden" name="payee_id" value="1185" />
  <input type="hidden" name="shop_order_number" value="76575j65465464161hhhh" />
  <input type="hidden" name="bill_amount" value="1" />
  <input type="hidden" name="description" value="Опис замовлення" />
  <input
    type="hidden"
    name="success_url"
    value="http://example.com/success.html"
  />
  <input
    type="hidden"
    name="failure_url"
    value="http://example.com/failure.html"
  />
  <input type="hidden" name="lang" value="uk" />
  <input type="hidden" name="encoding" value="UTF-8" />
  <input type="hidden" name="exp_time" value="400" />
  <input type="hidden" name="signature" value="9579C33D36C5BC98627BAA1E38C3DDFC039F682B03785BC3F6D728FED45A5CB9" />
  <input type="hidden" name="dt" value="20220512022427"/>
</form>

3.1 Приклад відповіді шлюзу у разі успішного здійснення платежу для запиту методом POST

SHOPBILLID: 420651576 SHOPORDERNUMBER: 123456789qwe APPROVALCODE: TESTPM
BILL_AMOUNT: 1 TOKEN: RESULT: 0 CARD_MASK: 444433******1111 ATTRIBUTE1: null
ATTRIBUTE2: null ATTRIBUTE3: null ATTRIBUTE4: null RECEIPT_URL:
https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/
353472d8de85c380d94e49e592050631486e357ebdcedf374ccd07c89682f31d181076bbd1f2d920b4d00b3e
11983dfb8777ccee0a19a9a00cd7cb5c1262c83c LANG: en DESCRIPTION: 999999 IPSTOKEN:
null ERRORIPSCODE: null ERRORIPSMESSAGE: null

3.2 Запит оплати замовлення у форматі JSON

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<?= $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Оплатити через Portmone.com" style="width: 350px;" class="button_green" />
</form>

де $data – структура json наступного вигляду:

{
  "paymentTypes": {
    "card": "Y",
    "portmone": "Y",
    "token": "N",
    "createtokenonly": "N"
  },
  "autopayment": {
    "show": "Y",
    "edit": "N",
    "defaultCheckboxState": "N",
    "changeCheckboxState": "Y",
    "settings": {
      "period": "1",
      "payDate": "27",
      "startDate": "",
      "endDate": "01.01.2021",
      "amount": "1.22"
    },
    "credentials": "393433af5c5c46bb776878f8208fae4ad91f4ca450a28e4b558386e4c30325e3f5673522b2929adfe39655d5a530fc193094cb089a9bac58137c4533edcfa08a4c299d27a8fc060b2d671d1b63a32e66f8fc1db433185d0788fe145b93faaa75e60713d99673e4bd"
  },
  "priorityPaymentTypes": {
    "card": "1",
    "portmone": "2",
    "token": "0",
    "createtokenonly": "5"
  },
  "payee": {
    "payeeId": "1185",
    "login": "",
    "dt": "",
    "signature": "",
    "displayMessage": "",
    "shopSiteId": ""
  },
  "order": {
    "description": "test",
    "shopOrderNumber": "123456",
    "billAmount": "2500",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "attribute5": "",
    "successUrl": "",
    "failureUrl": "",
    "preauthFlag": "Y",
    "preauthConfirm": "20190321132000",
    "billCurrency": "EUR",
    "expTime": "1000",
    "encoding": ""
  },
  "token": {
    "tokenFlag": "N",
    "returnToken": "N",
    "token": "18333832303637393435128BD118A706492899CBF82382ADC631520BBD466A0F2C611A0231AEE0BBCBC6B97752972A8037563F6E4FD11F11ED74709ADD3DD1F9D0CDD30899063D95F713F77",
    "cardMask": "516874******5179",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "[email protected]",
    "showEmail": "N"
  },
  "shipping": {
    "services": {
      "ukrposhta": {
        "deliveryTypes": ["W2D", "W2W"],
        "senderClientId": "91cfddfe-5c94-44d0-9410-c78e2a877512",
        "senderAddressId": "2651676",
        "senderPostCode": "08040",
        "type": "STANDARD",
        "parcelWeight": "600",
        "parcelLength": "50",
        "parcelWidth": "50",
        "parcelHeight": "50",
        "parcelDeclaredPrice": "25",
        "parcelDescription": "",
        "fragile": "",
        "checkOnDelivery": "",
        "bees": "",
        "payer": "client",
        "sms": "Y",
        "withDeliveryNotification": ""
      }
    },
    "enable": "Y",
    "required": "N"
  },
  "style": {
    "type": "light",
    "logo": "",
    "backgroundColorHeader": "",
    "backgroundColorButtons": "",
    "colorTextAndIcons": "",
    "borderColorList": "",
    "logoWidth": "",
    "logoHeight": "",
    "bcMain": ""
  }
}

3.2 Приклад відповіді шлюзу у разі успішного здійснення платежу для запиту у форматі JSON

'SHOPBILLID'          => '411587640',
'SHOPORDERNUMBER'     => 'SHP-000000002792',
'APPROVALCODE'        => '366999',
'BILL_AMOUNT'         => '1',
'TOKEN'               => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE016
44F39F009A3EDDEF992C6A5E22ACD01AE91D1CB491B645B530EDCE8C289778611A37D0D045D650DE3495E84',
'RESULT'              => '0',
'CARD_MASK'           => '516874******5179',
'ATTRIBUTE1'          => '49026347',
'ATTRIBUTE2'          => '2',
'ATTRIBUTE3'          => '3',
'ATTRIBUTE4'          => '4',
'RECEIPT_URL'         => 'https://www.portmone.com.ua/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e676f58cc
92084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG'                => 'uk',
'DESCRIPTION'         => 'test',
'IPSTOKEN'            => 'null',
'ERRORIPSCODE'        => 'null',
'ERRORIPSMESSAGE'     => 'null'

3.4.1 Приклад об’єкта data для режиму popup

var data = {
  paymentTypes: {
    card: "Y",
    gpay: "Y",
    applepay: "Y",
    installment: "Y",
  },
  priorityPaymentTypes: {
    card: "1",
    gpay: "2",
    applepay: "3",
    installment: "4",
  },
  installmentPlan: {
    privat24: { parts: "3" },
    oschad:   { parts: "5" },
    monobank: { parts: "8" },
    pumb:     { parts: "3" },
    otp:      { parts: "6" },
    abank:    { parts: "6" },
  },
  payee: {
    payeeId: "1185",
    signature:
      "7DE75312FCBFCB7A3BA0248C4ED6E1255780CE38248C4E462E170295CE382DC1",
    login: "shop",
    dt: "20250919174335",
    shopSiteId: "",
  },
  payer: {
    lang: "uk",
    emailAddress: "",
  },
  order: {
    billAmount: "4269",
    shopOrderNumber: "2833398",
    attribute1: "19.09.2025",
    attribute2: "Тест Оплати Тест",
  },
  goods: [
    {
      internalCode: "customer",
      name: "Персональна знижка 10 %",
      price: -1.0,
      quantity: 1,
      amount: -1.0,
      taxRateCodes: 1,
      govClassificationCode: "",
    },
    {
      internalCode: "001017",
      name: "Marvis Toothbrush Black Medium",
      price: 10,
      quantity: 1,
      amount: 10,
      taxRateCodes: 1,
      govClassificationCode: "3306200000",
    },
  ],
  style: {
    type: "light",
    backgroundColorButtons: "#2F2F82",
    colorTextAndIcons: "#2F2F82",
    bcMain: "#ffffff",
  },
};

3.4.2 Приклад об’єкта data для режиму iframe

var data = {
  paymentTypes: { card: "Y", gpay: "Y", installment: "Y" },
  priorityPaymentTypes: { card: "1", gpay: "2", installment: "3" },
  installmentPlan: {
    privat24: { parts: "3" },
    oschad:   { parts: "5" },
    monobank: { parts: "8" },
    pumb:     { parts: "3" },
    otp:      { parts: "6" },
    abank:    { parts: "6" },
  },
  payee: {
    payeeId: "1185",
  },
  payer: {
    lang: "uk",
  },
  goods: [
    {
      internalCode: "ЦБ208406",
      manufacturerCode: "92949",
      govClassificationCode: "8708803598",
      name: "ВАЖІЛЬ ПІДВІСКИ передній правий Logan II",
      name_en: "something Logan II",
      description: "Сірий, залізний",
      description_en: "Gray, iron",
      price: "1.6",
      quantity: "2",
      uomCode: "",
      amount: "3.2",
      serviceFlag: "N",
      taxRateCodes: "A",
      descriptionUrl: "",
      imageUrl: "",
    },
  ],
  order: { billAmount: "3.2" },
  closeModal: "N",
  frameHolderId: "paymentFrame1",
};

3.6.Інформація про курс валют

Запит

{
  "method": "getRateCurrencies",
  "params": {
    "data": {
      "payeeId": "72276",
      "date": "21-11-2022"
    }
  },
  "id": "1"
}

Відповідь

{
  "result": {
    "currencies": [
      {
        "key": "AUD",
        "value": "24.5503"
      },
      {
        "key": "EUR",
        "value": "37.8906"
      },
      {
        "key": "GBP",
        "value": "43.5239"
      },
      {
        "key": "KZT",
        "value": "0.079196"
      },
      {
        "key": "PLN",
        "value": "8.0569"
      },
      {
        "key": "USD",
        "value": "36.5686"
      }
    ],
    "notice": "Portmone не здійснює купівлі, продажу, обміну, конвертації та визначення курсу безготівкової іноземної валюти. Розрахунок вартості товарів та послуг на поточну дату здійснюється на підставі даних, отриманих з сервісу розрахунку курсу валют, обраного Отримувачем. Portmone не несе відповідальності за працездатність цього сервісу"
  },
  "id": "1"
}

До розділу 4 «Оплата замовлення з використанням платіжного токену»

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

{
  "paymentTypes": {
    "createtokenonly": "Y"
  },
  "priorityPaymentTypes": {
    "createtokenonly": "1"
  },
  "payee": {
    "payeeId": "1185",
    "login": "",
    "dt": "",
    "signature": "",
    "shopSiteId": ""
  },
  "order": {
    "description": "testPayment",
    "shopOrderNumber": "SHP-000000002792",
    "billAmount": "1",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "successUrl": "",
    "failureUrl": "",
    "preauthFlag": "N",
    "billCurrency": "UAH",
    "encoding": ""
  },
  "token": {
    "tokenFlag": "N",
    "returnToken": "Y",
    "token": "",
    "cardMask": "",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "[email protected]"
  },
  "style": {
    "type": "",
    "logo": "",
    "backgroundColorHeader": "",
    "backgroundColorButtons": "",
    "colorTextAndIcons": "",
    "borderColorList": ""
  }
}

JSON-структуру помістити у поле bodyRequest, та додати параметр typeRequest зі значенням "json".

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="СТРУКТУРА JSON" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Portmone.com" />
</form>

4.1 Успішна відповідь на створення Токену

'SHOPBILLID'          => '411587640',
'SHOPORDERNUMBER'     => 'SHP-000000002792',
'APPROVALCODE'        => '366999',
'BILL_AMOUNT'         => '1',
'TOKEN'               => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644
F39F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84',
'RESULT'              => '0',
'CARD_MASK'           => '516874******5179',
'ATTRIBUTE1'          => '49026347',
'ATTRIBUTE2'          => '2',
'ATTRIBUTE3'          => '3',
'ATTRIBUTE4'          => '4',
'RECEIPT_URL'         => 'https://www.portmone.com.ua/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e676f58cc9
2084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG'                => 'uk',
'DESCRIPTION'         => 'test'

4.2.1 Проведення оплати за Токеном. POST-запит

<form method="POST" action="https://www.portmone.com.ua/r3/token/secure/token/">
  <input type="text" value="1185" name="payee_id" />
  <input type="text" value="test_123" name="description" />
  <input type="text" value="1" name="bill_amount" />
  <input type="text" value="test_1" name="shop_order_number" />
  <input
    type="text"
    value="https://www.portmone.com.ua/r3/ecommerce/test/"
    name="application_url"
  />
  <input type="text" value="en" name="lang" />
  <input
    type="text"
    value="183233333139333633381280337D20FA7B4F0D5DC08EF36ADB828EFC510
A1EF2E1965DFEF0F1E5421D0CE264CB46A01EB95638BADAFD7E7E738928B873B30DB753E10AE4A0932BEE4491
E66"
    name="token"
  />
  <input type="text" value="" name="attribute1" />
  <input type="text" value="" name="attribute2" />
  <input type="text" value="" name="attribute3" />
  <input type="text" value="" name="attribute4" />
</form>

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

BILL_AMOUNT=45& SHOPORDERNUMBER=test_2& APPROVALCODE=TESTPM&
RECEIPT_URL=https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-receipts
%2Fshop-bill-id%2F35348409d793c705eb6250a1576451abad87d010699109d1a6578e81a4f9b40e70d67
085deb9e94e54a62093a09ff92062953366caa6e80f64025449318491ec&
TOKEN=183233333139333633381280337D20FA7B4F0D5DC08EF36ADB828EFC510A1EF2E1965DFEF0F1E5421D0C
E264CB46A01EB95638BADAFD7E7E738928B873B30DB753E10AE4A0932BEE4491E66&
CARD_PAYMENT_SYSTEM=VISA& CARD_LAST_DIGITS=1111& RESULT=0

4.2.2 Проведення оплати за Токеном. Приклад запиту у JSON форматі

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<?= $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Оплатити через Portmone.com" style={{ width:
  '350px' }} class="button_green" />
</form>

де $data - структура json наступного вигляду:

{
       	"paymentTypes":
       	{
       		"card":"N",
       		"portmone":"N",
       		"token":"N"
       	},
       	"priorityPaymentTypes":
       	{
       		"card":"4",
       		"portmone":"2",
      		"token":"8"
       	},
       	"payee":
       	{
       		"payeeId":"1185",
       		"login":"",
       		"dt":"",
       		"signature":"",
       		"shopSiteId":""
       	},
       	"order":
       	{
       		"description":"191237564",
       		"shopOrderNumber":"SHP-00000111",
       		"billAmount":"1",
       		"attribute1":"1",
       		"attribute2":"2",
       		"attribute3":"3",
       		"attribute4":"4",
       		"successUrl":"",
       		"failureUrl":"",
       		"preauthFlag":"N",
       		"billCurrency":"UAH",
       		"encoding":""
       	},
       	"token":
       	{
       		"tokenFlag":"Y",
       		"returnToken":"Y",
       		"token":"1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644F39F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84",
       		"cardMask":"516874******5179",
       		"otherPaymentMethods":"N"
       	},
       	"payer":
       	{
       		"lang":"uk",
       		"emailAddress":""
       	},
       	"style":
       	{
       		"type":"brand",
       		"logo":",
       		"logoWidth":"171px",
       		"logoHeight":"41px",
       		"backgroundColorHeader":"#009DE0",
       		"backgroundColorButtons":"#009DE0",
       		"colorTextAndIcons":"#1e282c",
       		"borderColorList":"#1e282c"
       	}
}

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

'module'          => 'ecommerce',
'controller'      => 'test',
'action'          => 'success',
'SHOPBILLID'      => '421606955',
'SHOPORDERNUMBER' => 'SHP-00000000279210',
'APPROVALCODE'    => '416477',
'BILL_AMOUNT'     => '1',
'TOKEN'           => '18333832303637393435128BD118A706492899CBF82382ADC631520BBD466A0F2C6
11A0231AEE0BBCBC6B97752972A8037563F6E4FD11F11ED74709ADD3DD1F9D0CDD30899063D95F713F77',
'RESULT'          => '0',
'CARD_MASK'       => '516874******5179',
'ATTRIBUTE1'      => '1',
'ATTRIBUTE2'      => '2',
'ATTRIBUTE3'      => '3',
'ATTRIBUTE4'      => '4',
'RECEIPT_URL'     => 'https://portmone2.com/r3/services/receipts/get-receipts/
shop-bill-id/35343ea3aabe8b49a35f95b78dba465ec24d36e9794f27ce97d9b1d9080b930ed
e870ed357a32212de9b5dda00c158a37ce9877be5c7a279cf2ed2114849c779',
'LANG'            => 'uk',
'DESCRIPTION'     => '191237564'

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

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

$jsoncontent = '{
  "method": "pay",
  "params": {
    "login": "SHP_**",
    "password": "******",
    "payeeId": "1185",
    "shopOrderNumber": "123456",
    "token": "1834373930303635***FCC",
    "description": "Опис замовлення",
    "billAmount": "1.24",
    "billCurrency": "EUR",
    "preauthFlag": "Y",
    "attribute1":"1",
    "attribute2":"2",
    "attribute3":"3",
    "attribute4":"4",
    "attribute5":"Water:3048;2;Souvenir:11344;1;"
  },
  "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);
print_r($result);
curl_close($ch);

Приклад відповіді по успішному платежу:

{
  "result": {
    "result": "PAYED",
    "shopOrderNumber": "P1728563684",
    "description": "",
    "receipt": "",
    "shopBillId": "1728563684"
  },
  "id": "1"
}

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

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

{
    "method": "paywith3ds",
    "params": {
        "data": {
            "login": "SHP_333",
            "password": "22222222",
            "payeeId": "30481",
            "shopOrderNumber": "test_0000001",
            "token": "203131393132332393039128CFE98552764426D1D5A285E4CF64130AB19CDB6336481E5878DA66F03BD7C807ABAE08464CFA7EFC6F56106E480F002669E7CDC901554499787573FFC6AC57",
            "description": "test",
            "billAmount": "1",
            "preauthFlag": "N",
            "billCurrency": "UAH",
            "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-form/"
            "attribute1":"",
			"attribute2":"",
			"attribute3":"",
			"attribute4":""
        }
    },
    "id": "1"
    }

4.7.1 Успішна відповідь, коли потрібно пройти 3Ds

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

{
  "result": {
    "shopBillId": "1191240800",
    "status": "CREATED",
    "shopOrderNumber": "test_0000001",
    "description": "test",
    "pdfUrl": "",
    "authCode": "",
    "isNeed3DS": "Y",
    "actionMPI": "https://portmone2.com/r3/tothreeds?data=2053A3B7BCF9347FF04F6B4D3E338F96FDC604F3F3C522D47EB43A50FAB904AC90AFCA2A5BB0E04171426F56D81DBFE7042E2A24FF3FC24A8F38A9B76116DF17319FE4FE028FD17660B322AE733D5A7"
  },
  "id": "1"
}

4.7.2 Відповідь після проходження 3Ds

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

shopBillId: 1191240666
status: PAYED
billAmount: 1
billNumber: test_0000001
payeeName: 333
authCode: 453750
commission: 0
pdfUrl: ""
payeeId: 30481
payDate: 15.06.2022 03:32:27
description: test
cardMask: 454788******1119
errorMessage:
errorCode: 0

4.7.3 Успішна відповідь, коли не потрібно проходити 3Ds

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

{
  "result": {
    "shopBillId": "1213000727",
    "status": "PAYED",
    "shopOrderNumber": "test_0000001",
    "description": "test_001",
    "pdfUrl": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/35375cadedf354dd63444c7a0dba795fb044b138f323b42c51309f05929d20198733ce5ca     85866a0512487643306b1b3143e0c07f93961e8c69fb06e5275d2e6426fea",
    "authCode": "158709",
    "isNeed3DS": "N",
    "actionMPI": ""
  },
  "id": "1"
}

4.7.4 Неуспішна відповідь

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

{
  "error": {
    "code": 10,
    "message": "Операція відхилена. Повторна транзакція",
    "data": {}
  },
  "id": "1"
}

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

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<?= $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Оплатити через Portmone.com" style={{ width:
  '350px' }} class="button_green" />
</form>

де $data - структура json наступного вигляду:

{
  "paymentTypes": {
    "token": "Y"
  },
  "priorityPaymentTypes": {
    "token": "1"
  },
  "payee": {
    "payeeId": "11344",
    "credentials": "3932b2bb0fb55509027abd365e0deab4e2ab149f419fa167a2441a3d289da1f48a2f16092c2300fa76d415a6e76fb8283e6c0e77305ce4622e10e5383f1030ceed470e9239ce4fc7ccccc442ea739123cb721f78a6dd0703beecfa0085e0eebfad6c36791268"
  },
  "order": {
    "description": "test",
    "shopOrderNumber": "",
    "billAmount": "1",
    "attribute1": "1",
    "attribute2": "2",
    "attribute3": "3",
    "attribute4": "4",
    "successUrl": "",
    "failureUrl": "",
    "preauthFlag": "N",
    "billCurrency": "UAH",
    "encoding": ""
  },
  "token": {
    "tokenFlag": "Y",
    "returnToken": "N",
    "token": "20313234333633313538391280E7B5BCFFAE793EA6226F02E9D1263AD5652E804EACC8A4F3C4852CFB2FB6BA6C7053E034427E3FEFFA985ACC331C6DA961D384C5E4914505DABDFF01840",
    "cardMask": "414949******2244",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "[email protected]",
    "showEmail": "N"
  }
}

До розділу 5 «Переказ з картки на картку»

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

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<? = $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Оплатити через Portmone.com" style={{ width:
  '350px' }} class="button_green" />
</form>

де $data – структура json наступного вигляду:

{
	"paymentTypes":
	{
		"card":"N",
		"portmone":"N",
		"token":"N",
		"createtokenonly":"Y"
	},
	"priorityPaymentTypes":
	{
		"card":"0",
		"portmone":"0",
		"token":"0",
		"createtokenonly":"1"
	},
	"payee":
	{
		"payeeId":"1185",
		"login":"",
		"dt":"",
		"signature":"",
		"shopSiteId":""
	},
	"order":
	{
		"description":"тест",
		"shopOrderNumber":"111145",
		"billAmount":"1",
		"attribute1":"1",
		"attribute2":"2",
		"attribute3":"3",
		"attribute4":"4",
		"successUrl":"",
		"failureUrl":"",
		"preauthFlag":"N",
		"billCurrency":"UAH",
		"encoding":""
	},
	"token":
	{
		"tokenFlag":"N",
		"returnToken":"Y",
		"token":"",
		"cardMask":"",
		"otherPaymentMethods":"N",
		"sellerToken":""
	},
	"payer":
	{
		"lang":"uk"
	},
	style":
	{
		"type":"portmone",
		"logo":"",
		"backgroundColorHeader":"",
		"backgroundColorButtons":"",
		"colorTextAndIcons":"",
		"borderColorList":""
	}
}

5.1 Відповідь на запит створення токену

'SHOPBILLID'      => '411587640',
'SHOPORDERNUMBER' => 'SHP-000000002792',
'APPROVALCODE'    => '366999',
'BILL_AMOUNT'     => '1',
'TOKEN'           => '1834303338393938313612886A7AFA1991D92FB81C2026D01EA263F9DE01644F3
9F009A3EDDEF992C6A5E220ACD01AE91D1CB491B645B530EDCE882C289778611A37D0D045D650DE3495E84',
'RESULT'          => '0',
'CARD_MASK'       => '516874******5179',
'ATTRIBUTE1'      => '49026347',
'ATTRIBUTE2'      => '2',
'ATTRIBUTE3'      => '3',
'ATTRIBUTE4'      => '4',
'RECEIPT_URL'     => 'https://portmone2.com/r3/services/receipts/get-receipts/
shop-bill-id/353554cd64a021ee646db40dc0c476283b57b9cfc1ce3570238a1148a63605af3e67
6f58cc92084b67c28ec5fc4fd6c73a394d712162df54c5d7799d60a11bf2eb',
'LANG'            => 'uk',
'DESCRIPTION'     => '516874******5179'

5.2 Запит на переказ коштів між токенами карток

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="bodyRequest" value="<? = $data ?>" />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Оплатити через Portmone.com" style={{ width:
  '350px' }} class="button_green" />
</form>

де $data - структура json наступного вигляду:

{
	"paymentTypes":
	{
		"card":"Y",
		"portmone":"Y",
		"token":"Y"
	},
	"priorityPaymentTypes":
	{
		"card":"1",
		"portmone":"2",
		"token":"2"
	},
	"payee":
	{
		"payeeId":"1185",
		"login":"",
		"dt":"",
		"signature":"",
		"shopSiteId":""
	},
	"order":
	{
		"description":"444433******1111",
		"shopOrderNumber":"SHP-0101000110002792",
		"billAmount":"1",
		"attribute1":"1",
		"attribute2":"2",
		"attribute3":"3",
		"attribute4":"4",
		"successUrl":"",
		"failureUrl":"",
		"preauthFlag":"N",
		"billCurrency":"UAH",
		"encoding":""
	},
	"token":
	{
		"tokenFlag":"Y",
		"returnToken":"N",
		"token":"183434303730373432331283F04364806355F5E7479D903A9518BC9DC4A23336E07B696BE09B713D6ADD71603966FCF9A4E40C88265E1180017127653EB541CF76176EF5FECC6B269B949DE",
		"cardMask":"111122******4444",
		"otherPaymentMethods":"N",
		"sellerToken":"18343430373037373330128746FED8954F0E0A83315F409D8BE23767C0573C9AFE796C2B403031F8B7379307B201DB7D3E7B5F32B2E33A8B7FC284999D47396CB8D1AE485D89A6452CC8B1D"
	},
	"payer":
	{
		"lang":"uk",
		"emailAddress":[email protected]
	},
	"style":
	{
		"type":"portmone",
		"logo":"https://i1.rozetka.ua/logos/0/99.png",
		"backgroundColorHeader":"#fff",
		"backgroundColorButtons":"#4bbe3f",
		"colorTextAndIcons":"#4bbe3f",
		"borderColorList":"#3e77aa"
	}
}

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

{
  "paymentTypes": {
    "token": "Y"
  },
  "priorityPaymentTypes": {
    "token": "1"
  },
  "payee": {
    "payeeId": "1185",
    "checkParams": "Y"
  },
  "order": {
    "description": "4444333322221111",
    "shopOrderNumber": "65",
    "billAmount": "1",
    "successUrl": "http://10.1.0.80:8082/api/v1/operations/p2p/success",
    "failureUrl": "http://10.1.0.80:8082/api/v1/operations/p2p/error",
    "encoding": "UTF-8",
    "attribute2": "",
    "attribute3": "",
    "attribute4": ""
  },
  "token": {
    "tokenFlag": "Y",
    "returnToken": "Y",
    "token": "18343836373232313531096EE3BB03559659C0F64E6BB61C642902AE0570EA189661F2CF59102681BC3D741E03540B292BB9A4D3B04D91496F0C8D9",
    "cardMask": "410232******5594",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "",
    "showEmail": "N"
  },
  "style": {
    "type": "",
    "bcMain": "",
    "backgroundColorButtons": "",
    "colorTextAndIcons": ""
  }
}

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

SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN:
183438363734343037351287D5A3C90A1880888F785B34726EA1A106E6F40C2C0C30930F904FE3AE66B
C5173AB6386E12C118F91F41A500F7756A1A39D0CA3DB0F0BA38138556083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-
receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037e
f335c52c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6
LANG: uk DESCRIPTION: 410232******5594

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

{
  "paymentTypes": {
    "token": "Y"
  },
  "priorityPaymentTypes": {
    "token": "1"
  },
  "payee": {
    "payeeId": "18930",
    "checkParams": "N"
  },
  "order": {
    "shopOrderNumber": "ttgyy1701090211",
    "billAmount": "1.23",
    "successUrl": "https://portmone2.com/r3/ecommerce/test/",
    "failureUrl": "",
    "preauthFlag": "N",
    "encoding": "UTF-8",
    "attribute2": "xtra"
  },
  "token": {
    "tokenFlag": "Y",
    "returnToken": "N",
    "token": "1834383438393836********DECB2DD7679AE245BD8E4B69C95C67401CA89",
    "cardMask": "516874******5179",
    "otherPaymentMethods": "N"
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "",
    "showEmail": "N"
  },
  "style": {
    "type": "light",
    "bcMain": "#fff",
    "backgroundColorButtons": "#0f51a6",
    "colorTextAndIcons": "#0f51a6"
  }
}

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

SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN: 18343836373434303735********6083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-
receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037ef335c52
c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6 LANG: uk
DESCRIPTION: null

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

{
  "method": "confirmp2p",
  "params": {
    "authData": {
      "login": "SHP_333333",
      "password": "333333"
    },
    "data": {
      "shopBillId": "484991476",
      "token": "183438343839383831391286A60BED7182634F41FC3DFC64D1713959E1B0DA3C05C7F18B6F474535FC554F02B78AD6C1F051616907E2F5D6E624B6746A163FFC64EF050B4907201AFA3D1CD"
    }
  },
  "id": "1"
}

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

SHOPBILLID: 486744075 SHOPORDERNUMBER: P486744075 APPROVALCODE: 365470
BILL_AMOUNT: 5 TOKEN: 18343836373434303735********6083F0383A9 RESULT: 0
CARD_MASK: 410232******5594 ATTRIBUTE1: 54635856 ATTRIBUTE2: 153 ATTRIBUTE3:
null ATTRIBUTE4: null RECEIPT_URL:
https%3A%2F%2Fwww.portmone.com.ua%2Fr3%2Fservices%2Freceipts%2Fget-receipts%2Fshop-bill-id%2F3535adc0ac7c6c332ddc05d9fd24aab907d5220833e1e1e20037ef335c52c428d7568906247e514ef35335ebdf6afdcbe9f456c36a30d17d7908819267c16aa5a6
LANG: uk DESCRIPTION: 410232******5594

До розділу 6 «Платежі з преавторизацією»

6.2.1 Процедура поставторизації. POST запит

<form action="https://www.portmone.com.ua/gateway/" method="post">
  <input type="hidden" name="method" value="preauth" />
  <input type="hidden" name="action" value="set_paid" />
  <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="postauth_amount" value="99.00" />
  <input type="hidden" name="encoding" value="utf-8" />
  <input type="hidden" name="lang" value="uk" />
</form>

6.2.1 Успішна відповідь для процедури поставторизації

<?xml version='1.0' encoding='windows-1251'?>
<portmoneresult lang='uk'>
    <request>
        <method>preauth</method>
        <action>set_paid</action>
        <login>shp_login</login>
        <password>******</password>
        <shop_bill_id>87834981</shop_bill_id>
        <postauth_amount>99.00</postauth_amount>
        <encoding>utf-8</encoding>
        <lang>uk</lang>
    </request>
    <order>
        <shop_bill_id>87834981</shop_bill_id>
        <shop_order_number><![CDATA[1234]]></shop_order_number>
        <description><![CDATA[Оплата замовлення №1234]]></description>
        <bill_date>15.11.2013</bill_date>
        <pay_date>15.11.2013 22:21:51</pay_date>
        <bill_amount>99.00</bill_amount>
        <auth_code>123456</auth_code>
        <status>PAYED</status>
        <error_code>0</error_code>
        <error_message><![CDATA[]]></error_message>
    </order>
</portmoneresult>

6.2.1 Неуспішна відповідь для процедури поставторизації

<order>
    <error_code>5</error_code>
    <error_message><![CDATA[Помилка підтвердження оплати рахунку
    [SHOP_BILL_ID = 87834981]ORA-20001:Помилка визначення реквізитів платіжного терміналу.
    [pay_terminal_id=]]]></error_message>
</order>

6.2.2 Процедура поставторизації. Запит у форматі JSON

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

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

{
    "0": {
        "payee_id": "3048",
        "shop_bill_id": "2205139404",
        "shop_order_number": "P2205139404",
        "description": "Описание заказа",
        "bill_date": "24.12.2025",
        "pay_date": "24.12.2025 16:13:52",
        "pay_order_date": null,
        "bill_amount": "2",
        "auth_code": "120299",
        "status": "PAYED",
        "bank_id": "5165",
        "terminal_id": "KIE00001",
        "merchant_id": "02001003DS00319",
        "rrn": "037002829857",
        "attribute1": null,
        "attribute2": null,
        "attribute3": null,
        "attribute4": null,
        "attribute5": null,
        "attribute6": "444111******7769",
        "error_code": "0",
        "error_message": null
    },
    "error_message": "",
    "error_code": "0"
}

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

<form action="https://www.portmone.com.ua/gateway/" method="post">
  <input type="hidden" name="method" value="preauth" />
  <input type="hidden" name="action" value="reject" />
  <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="encoding" value="utf-8" />
  <input type="hidden" name="lang" value="uk" />
</form>

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

<?xml version="1.0" encoding="utf-8"?>
<portmoneresult lang="uk">
    <request>
        <method>preauth</method>
        <action>reject</action>
        <login>SHP_FLOWERSQUICKER</login>
        <password>********</password>
        <shop_bill_id>421592544</shop_bill_id>
        <encoding>utf-8</encoding>
        <lang>uk</lang>
    </request>
    <order>
        <shop_bill_id>421592544</shop_bill_id>
        <shop_order_number>test_1nvnvnvbnvb15</shop_order_number>
        <description><![CDATA[Опис замовлення]]></description>
        <bill_date>17.10.2018</bill_date>
        <pay_date>17.10.2018</pay_date>
        <pay_order_date></pay_order_date>
        <bill_amount>1</bill_amount>
        <auth_code>523067</auth_code>
        <status>REJECTED</status>
        <attribute1></attribute1>
        <attribute2></attribute2>
        <error_code>0</error_code>
        <error_message><![CDATA[]]></error_message>
    </order>
</portmoneresult>

6.3.2 Запит скасування платежу з преавторизацією. Запит у форматі JSON

{
  "method": "rejectPreauth",
  "params": {
    "data": {
      "login": "SHP_333",
      "password": "22222222",
      "payeeId": "3048",
      "shopOrderNumber": "SHP-00000015",
      "shopbillId": 395587649
    }
  },
  "id": "1"
}

6.3.2 Успішна відповідь на запит скасування платежу з преавторизацією

[
    {
        "shop_bill_id": "2239987505",
        "bill_number": "order-fd61e84d-d727-4b95-97f7-5f74dc30c7db",
        "description": "Опис замовлення",
        "bill_amount": "1",
        "status": "REJECTED",
        "bank_id": "1042",
        "terminal_id": "20900208",
        "merchant_id": "20900037",
        "rrn": null,
        "auth_code": "TESTPM",
        "attribute1": null,
        "attribute2": null,
        "attribute3": null,
        "attribute4": null,
        "attribute6": "444433******1111",
        "commission": "0",
        "error_code": "0",
        "error_message": null,
        "token": ""
    }
]

До розділу 7 «Розщеплення платежу»

Приклад запиту на оплату з розщепленням платежу

<form
  action="https://www.portmone.com.ua/gateway/"
  method="post"
  target="_blank"
>
  <input
    type="hidden"
    name="bodyRequest"
    value='{
   "paymentTypes":{
      "card":"Y",
      "portmone":"N",
      "token":"N",
      "createtokenonly":"N"
   },
   "priorityPaymentTypes":{
      "card":"1",
      "portmone":"0",
      "token":"0",
      "createtokenonly":"0"
   },
   "payee":{
      "payeeId":"3048",
      "login":"",
      "dt":"",
      "signature":"",
      "shopSiteId":""
   },
   "order":{
      "description":"Test Payment",
      "shopOrderNumber":"",
      "billAmount":"3",
      "attribute1":"",
      "attribute2":"",
      "attribute3":"",
      "attribute4":"",
      "attribute5":"Water:3048;2;Souvenir:11344;1;",
      "successUrl":"",
      "failureUrl":"",
      "preauthFlag":"N",
      "billCurrency":"UAH",
      "encoding":"",
      "expTime":""
   },
   "token":{
      "tokenFlag":"Y",
      "returnToken":"Y",
      "token":"",
      "cardMask":"",
      "otherPaymentMethods":"Y",
      "sellerToken":""
   },
   "payer":{
      "lang":"uk",
      "emailAddress":"[email protected]",
      "showEmail":"N"
   },
   "style":{
      "type":"",
      "logo":"",
      "backgroundColorButtons":"",
      "colorTextAndIcons":"",
      "logoHeight":""
   }
}'
  />
  <input type="hidden" name="typeRequest" value="json" />
  <input type="submit" value="Portmone.com" style={{ width: '350px' }}
  class="button_green" />
</form>

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

8.2.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="1185" />
  <input type="hidden" name="login" value=" preauth_flag" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="shop_order_number" value="123456" />
  <input type="hidden" name="status" value="PAYED" />
  <input type="hidden" name="start_date" value="01.01.2016" />
  <input type="hidden" name="end_date" value="30.01.2016" />
</form>

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

<?xml version="1.0" encoding="utf-8"?>
<portmoneresult lang="ru">
    <request>
        <payee_id>1185</payee_id>
        <shop_order_number>7852547316_905992780_439915</shop_order_number>
        <status>%</status>
        <start_date>01.08.2025</start_date>
        <end_date>01.09.2025</end_date>
    </request>
    <orders type="list">
        <order>
            <shop_bill_id>2085828976</shop_bill_id>
            <shop_order_number>7852547316_905992780_439915</shop_order_number>
            <description>Telegram payment</description>
            <bill_date>01.09.2025</bill_date>
            <pay_date>01.09.2025 12:27:50</pay_date>
            <pay_order_date></pay_order_date>
            <bill_amount>40</bill_amount>
            <auth_code>TESTPM</auth_code>
            <status>PAYED</status>
            <attribute1></attribute1>
            <attribute2></attribute2>
            <error_code>0</error_code>
            <error_message></error_message>
        </order>
    </orders>
</portmoneresult>

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

{
  "method": "result",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "1185",
      "shopOrderNumber": "005311590_783211_29.01.2019.202527",
      "shopbillId": 455025419,
      "status": "",
      "startDate": "30.03.2019",
      "endDate": "31.03.2019"
    }
  },
  "id": "1"
}

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

[
  {
    "payee_id": "1185",
    "description": "",
    "status": "PAYED",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "attribute5": "Вода:3048;2;Сувенір:1185;1;",
    "commission": 0,
    "distribution_payee_id": "1185",
    "bank_name": "ГУ Ощадбанку м.Київ",
    "terminal_id": "4269955",
    "merchant_id": "20905416",
    "rrn": "0000000000",
    "pay_date": "20.08.2024 11:43:11",
    "payee_export_date": "27.08.2024 15:40:45",
    "payee_export_flag": "Y",
    "chargeback": "N",
    "payee_name": "ФОП WDISHOP",
    "payee_commission": ".07",
    "pay_order_date": "",
    "pay_order_number": "",
    "pay_order_amount": "",
    "shopBillId": "1750101779",
    "shopOrderNumber": "P1750101779",
    "billAmount": "1",
    "errorCode": "",
    "errorMessage": "",
    "authCode": "TESTPM",
    "cardMask": "444433******1111",
    "cardBankName": "TEST",
    "token": "20313735303130313737390965B1D7FB63513942C95B286B6DE2045B896B971395C9298E34926640CB6AEA6D8E70F63AFD84584ED9FDB668342E7762E",
    "payeeExportResult": "",
    "gateType": "Card",
    "cardTypeName": "Visa"
  }
]

8.2.2.1 Запит результатів авторизації при використанні розстрочки від Монобанку у форматі JSON

{
  "method": "result",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "",
      "shopOrderNumber": "",
      "shopbillId": 455025419,
      "status": "",
      "startDate": "30.03.2019",
      "endDate": "31.03.2019"
    }
  },
  "id": "1"
}

8.2.2.1 Приклад успішної відповіді на запит результатів авторизації при використанні розстрочки від Монобанку у форматі JSON

[
  {
    "description": "Оплата замовлення: 00000227 (Томілін Іван Петрович)",
    "status": "PAYED",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "commission": 0,
    "bank_name": "Монобанк (покупка частинами)",
    "terminal_id": "10029213",
    "merchant_id": "Х",
    "rrn": "9718583",
    "pay_date": "15.01.2019",
    "payee_export_date": "",
    "pay_order_date": "",
    "chargeback": "N",
    "payee_name": "ФОП WDISHOP",
    "payee_commission": "41.69",
    "shopBillId": "451192647",
    "shopOrderNumber": "00000227",
    "billAmount": "173.53",
    "errorCode": "",
    "errorMessage": "",
    "authCode": "TESTPM",
    "cardMask": "444433******1111",
    "token": "18343531313932363437192EA55717138A4B89FB558EDAD68FC2D6ABC882385C1759599421A631F08F69427556CBBDD1E43534833EA37844F64E951226F978DE9B19B74809E0A02A3F6F51688478593A83F897FB707882C06E45AA21C204488B6D8DB16BD9A404C1D33882D",
    "gateType": "Card"
  }
]

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

<?xml version="1.0" encoding="UTF-8"?>
<BILLS>
<BILL>
      <PAYEE>
          <NAME>Назва компанії</NAME>
          <CODE> Код компанії</CODE>
      </PAYEE>
      <BANK>
          <NAME> Назва банку відправника </NAME>
          <CODE> МФО банку відправника</CODE>
          <ACCOUNT> Рахунок банку відправника або IBAN</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>
      <DISTRIBUTIONS>
  <DISTRIBUTION>
    <DISTRIBUTION_ID>ID розподілення платежу</DISTRIBUTION_ID>
    <PAYEE>
      <NAME>Назва компанії одержувача розподілення</NAME>
      <CODE>Код компанії одержувача розподілення</CODE>
      <EDRPOU>ЄДРПОУ компанії одержувача розподілення</EDRPOU>
      <IBAN>Розрахунковий рахунок компанії одержувача розподілення</IBAN>
    </PAYEE>
    <AMOUNT>Сума розподілення</AMOUNT>
    <DESCRIPTION>Опис розподілення</DESCRIPTION>
  </DISTRIBUTION>
</DISTRIBUTIONS>
  </BILL>
</BILLS>

8.3 Приклад повідомлення 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>

8.3 Повідомлення про банківський платіж – 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>Р/р відправника або IBAN</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>

8.3 Приклад повідомлення 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>

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

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

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

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

8.4 Приклад виписки з результатами авторизації у форматі XML

<?xml version='1.0' encoding='windows-1251' standalone='yes'?>
  <portmoneresult>
  <request>
    <shopordernumber>305966</shopordernumber>
    <shop_id>7364</shop_id>
    <paymenttype>1</paymenttype>
    <startdate>18/03/2010</startdate>
    <enddate>18/03/2010</enddate>
    <success>1</success>
  </request>
  <orders>
    <order>
      <shopordernumber>305966</shopordernumber>
      <pay_date>18/03/2010</pay_date>
      <description>50908: покриття по платіжним карткам</description>
      <bill_amount>108.98</bill_amount>
      <error_code>000</error_code>
      <error_message></error_message>
      <status>PAYED</status>
      <pay_order_number></pay_order_number>
      <pay_order_date></pay_order_date>
    </order>
    </orders>
  </portmoneresult>

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

{
  "shopBillId": "",
  "shopOrderNumber": "",
  "description": "",
  "cardMask": "",
  "expDate": "",
  "billAmount": "",
  "status": "",
  "authCode": "",
  "token": "",
  "receiptUrl": "",
  "attribute1": "",
  "attribute2": "",
  "attribute3": "",
  "attribute4": "",
  "errorCode": "",
  "error": "",
  "notificationType": "",
  "cardType": "",
  "bank_name": "",
  "terminal_id": "",
  "merchant_id": "",
  "rrn": ""
}

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

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

8.7.1 Приклад запиту для методу отримання квитанцій

{
  "method": "getReceipt",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "shopOrderNumber": [
        "PO-1761042311987-f577587e",
        "PO-1761042438848-db8a99c2",
        "PO-1761042559012-a18c3e7d"
      ]
    }
  },
  "id": "1"
}

8.7.1 Приклад відповіді для методу отримання квитанцій

{
    "result": {
        "linkPdf": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/?documents=H4sIAAAAAAAAAw3NtxHAMAzAwJUYxFQy7j+S3T8OY7EDjsdOea1FrlHgTxvwrZWcefRjIuf8odsjrcyuOKtGjwOeGo906PWTF8gXVhQWNagXzwPbG8COxsZcKSaUk81ZsKvwncobJfnVX9FrZoZdBgGYE7RKXtRFpFbLymOL3nxCCVR3bvwTELYVHAdcrBdiBPMWqB9qgO9/Gq5zUETJjQRRVO9TypWF7maNLtgeR4qolp2JUjq5K226HMawERr4AGeqHqdAAQAA",
        "linkPdfReturn": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/?documents=H4sIAAAAAAAAAw3NtwHAQAjAwJXI8CVx/5HsVipuffwsa0ltrt6anzzrlwCi3cTrgHJ82OKNTqWCy971wkaGbsBl+b8CxDXhM1ZA4Ds5noqaI4DcCq9r73axi45ZbLhC2OQPJivUGZXz8HdgslcL4YAT1C8pXvz4sYrtWBpsp3Zgv6C0RQKkA4dritmw1/YBcdNd1eAAAAA="
    },
    "id": "1"
}

8.7.2 Приклад запиту для методу отримання квитанцій

{

   "method":"getReceipt",
   "params": {
       "data":{
           "billId":["2252120818","2257916986"],
           "credentials": "f4c071f8dc1933485c7a4135a9f3854c9cd41cc194ea41f3af0dcdc8d87e1f41ae250a1673045a58212ec6caa9336f64"
       }
   },

   "id": "1"
}

8.7.2 Приклад відповіді для методу отримання квитанцій

{
   "result": [
       {
           "id": "2252120818",
           "receipt": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/api-bill-id/571f7bdce02a1bf7c51c3020c7a7f415ea3d327afcc0e0e1356f1f3ca55673a32191049d0dffb3702bda8637cdfcbe6b628ee8b6dc55a7dfe681c4a4977dd0462e6da91f38c016384d7679c8b2b8c874b3b77073ae041edaf55bd2d2a93b706850460a2e3f63a56cc317b4594e0065fc"
       },
       {
           "id": "2257916986",
           "receipt": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/api-bill-id/9b50f2f7cab6b64c38fdbb81db4b83c05d4598d31feea7349b9a89a5099bd28e431992ff6735ce6d76e59d20359d8b7e7aa3ab272eaf1e294e90929ddc2ca263528164610436c7fb659e7e9413ac8f990cbe2df617c1d30533a652d5a2e11580436b6c85a91bf6cbc015e253b43eb4a7"
       }
   ],
   "id": "1"
}

До розділу 9 «Повернення коштів»

9.1.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>

9.1.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><![CDATA[1234]]></shop_order_number>
        <description><![CDATA[Оплата замовлення №1234]]></description>
        <bill_date>15.11.2013</bill_date>
        <pay_date>15.11.2013 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><![CDATA[]]></error_message>
    </order>
</portmoneresult>

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

<order>
    <error_code>5</error_code>
    <error_message><![CDATA[Помилка повернення за рахунком рахунку
    [SHOP_BILL_ID = 87834981]ORA-20001:Помилка визначення реквізитів платіжного терміналу.
    [pay_terminal_id=]]]> </error_message>
</order>

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

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

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

[
  {
    "description": "",
    "status": "RETURN",
    "bank_id": "1000",
    "terminal_id": "68611",
    "merchant_id": "AVAL_TEST",
    "rrn": "",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "commission": 0,
    "shopBillId": "1035983328",
    "shopOrderNumber": "P1029355342",
    "billAmount": "-.5",
    "errorCode": "0",
    "errorMessage": "",
    "authCode": "TESTPM",
    "cardMask": "444433******1111",
    "token": "",
    "gateType": ""
  }
]

9.2 Запит відміни оплати у форматі JSON

{
  "method": "reject",
  "params": {
    "data": {
      "login": "SHP_333",
      "password": "22222222",
      "payeeId": "3048",
      "shopbillId": 594890029,
      "returnAmount": "1",
      "message": "test return by shopbillId"
    }
  },
  "id": 1
}

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

[
  {
    "description": "",
    "status": "REJECTED",
    "bank_id": "1000",
    "terminal_id": "68611",
    "merchant_id": "AVAL_TEST",
    "rrn": "",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "commission": 0,
    "shopBillId": "1035983328",
    "shopOrderNumber": "P1029355342",
    "billAmount": "-.5",
    "errorCode": "0",
    "errorMessage": "",
    "authCode": "TESTPM",
    "cardMask": "444433******1111",
    "token": "",
    "gateType": ""
  }
]

До розділу 10 «Оплата рахунків»

10.2 Запит на оплату рахунку у форматі JSON

{
  "paymentTypes": {
    "card": "Y",
    "gpay": "Y"
  },
  "priorityPaymentTypes": {
    "card": "1",
    "gpay": "5"
  },
  "payee": {
    "shopSiteId": ""
  },
  "payer": {
    "emailAddress": "[email protected]",
    "lang": "uk"
  },
  "order": {
    "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-form"
  },
  "bill": {
    "id": "802655796",
    "billAmount": "84.16"
  },
  "style": {
    "type": "light",
    "bcMain": "#fff",
    "backgroundColorButtons": "#0f51a6",
    "colorTextAndIcons": "#0f51a6"
  },
  "credentials": "000186f6a4e33bf33625e9afdabc99afc7f701000de60fe53ac843d6be98e10ae86d67fae8144f6ca984c7c1374bc9959d023c7755ca123b16fb58cba889ddf946b022b62f43971f0145ccbb697c08fee6d523fe6e45ad92e3b71e68376b4a3fd713f276fafd5576ace1f6b5e9d7e2a35d2af0c4390fef4ce493279726bc55cbc1de5db8c6f7305a0d444192c7f9215ee64e2a5cf6f0145f8ef0bea7eb1849a54802fad190beacbd64df26f590e6391b207c7419cc6b74a08053b9420b7fa7dd9bb1364ee87b31bf395a73be178f508e8d4125bfeb72b762987aaade8d8fa02f441879cb0f036c468219078e8fc190e472b2b9d3401da3a0bf847062be0bfc00c9f29e92353bf8a3caaddc1f8584180a31e860fbc2fa99d9c8b64daacda49f441325cd3c"
}

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

<form enctype="application/x-www-form-urlencoded" action="successUrl" id="success-form" class="hide" method="POST">'
<input type="hidden" name="BILLID" value="" id="billId" />'
<input type="hidden" name="SHOPORDERNUMBER" value="" id="shopOrderNumber" />'
<input type="hidden" name="APPROVALCODE" value="" id="authCode" />'
<input type="hidden" name="BILL_AMOUNT" value="" id="billAmount" />'
<input type="hidden" name="RESULT" value="0" id="result" />'
<input type="hidden" name="CARD_MASK" value="" id="card_mask" />'
<input type="hidden" name="CONTRACTNUMBER" value="" id="description" />'
<input type="hidden" name="ATTRIBUTE1" value="" id="attribute1" />'
<input type="hidden" name="ATTRIBUTE2" value="" id="attribute2" />'
<input type="hidden" name="ATTRIBUTE3" value="" id="attribute3" />'
<input type="hidden" name="ATTRIBUTE4" value="" id="attribute4" />'
<input type="hidden" name="RECEIPT_URL" value="" id="receiptLink" />'
<input type="hidden" name="LANG" value="' + response.lang " id="lang" />'
</form>

10.3. Отримання посилання для сплати рахунку

{
  "method": "getLinkInvoice",
  "params": {
    "data": {
      "bill": {
        "id": "1223643041",
        "billAmount": "5"
      },
      "order": {
        "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-form"
      },
      "paymentTypes": {
        "card": "Y",
        "gpay": "Y"
      },
      "priorityPaymentTypes": {
        "card": "1",
        "gpay": "5"
      },
      "payee": {
        "shopSiteId": ""
      },
      "credentials": "000186f6a4e33bf33625e9afdac99afc7f7010090089ae9e5fa85bcbcdfee847d4a9db6367473d192305fce7c8deff958ab87db3c27cbbd0d6c6e634934fd8b4df5aa43006da2c104244c241e393591e485ffcd84882f787584185c069ffdfbb1e0fb28651e7890f8c90d9fa300e407fb96dbd3d8830320eab43c69135ac2e49287eeffce297ee736f1319a8a9fff2f657f3720c9445427a1b5bd60dfd1b7c111b7b6006cedc10cd4bbe02854ef3e1fc9797d4ced87e310d744f6fa7f86a82c3c3700bd9b22eaaad8bf5faa5d0b6558acea4bca3039b5bcf83ab29fa0f2154cb63fc40e67360cbf27c6ec7c238e8b09cd2522b9a37c2a6314d2a61a21674c14276b5a38f82553b5ed4cfd12dffe8829ff211bb76433e41417c967a3258736f2c342047b5a6142b36e6c0809870c6919048f"
    }
  },
  "id": "1"
}

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

Успішна:

{
  "result": {
    "linkInvoice": "https://prt.mn/EWcEZkIup7"
  },
  "id": "1"
}

Неуспішна:

{
  "error": {
    "code": 403,
    "message": "Wrong bill id value",
    "data": {}
  },
  "id": "1"
}

Відправка на email:

{
  "method": "invoiceEmail",
  "params": {
    "data": {
      "bill": {
        "id": "1223643040",
        "billAmount": "5"
      },
      "order": {
        "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-form"
      },
      "paymentTypes": {
        "card": "Y",
        "gpay": "Y"
      },
      "priorityPaymentTypes": {
        "card": "1",
        "gpay": "5"
      },
      "payee": {
        "shopSiteId": ""
      },
      "credentials": "000186f6a4e33bf33625e9afdabc99afc7f7010090089ae9e5fa85bcbcdfee847d4a9db6367473d192305fce7c8deff958ab87db3c27cbbd0d6c6e634934fd8b4df5aa43006da2c104244c241e393591e485ffcd84882f787584185c069ffdfbb1e0fb28651e7890f8c90d9fa300e407fb96dbd3d8830320eab43c69135ac2e49287eeffce297ee736f1319a8a9fff2f657f3720c9445427a1b5bd60dfd1b7c111b7b6006cedc10cd4bbe02854ef3e1fc9797d4ced87e310d744f6fa7f86a82c3c3700bd9b22eaaad8bf5faa5d0b6558acea4bca3039b5bcf83ab29fa0f2154cb63fc40e67360cbf27c6ec7c238e8b09cd2522b9a37c2a6314d2a61a21674c14276b5a38f82553b5ed4cfd12dffe8829ff211bb76433e41417c967a3258736f2c342047b5a6142b36e6c0809870c6919048f",
      "emailData": {
        "email": "[email protected]",
        "namePayer": "Костянтин",
        "comment": "test"
      }
    }
  },
  "id": "1"
}

Відправка на телефон:

{
  "method": "invoicePhone",
  "params": {
    "data": {
      "bill": {
        "id": "1223643040",
        "billAmount": "5"
      },
      "order": {
        "successUrl": "https://portmone2.com/r3/ecommerce/test/master-test-form"
      },
      "paymentTypes": {
        "card": "Y",
        "gpay": "Y"
      },
      "priorityPaymentTypes": {
        "card": "1",
        "gpay": "5"
      },
      "payee": {
        "shopSiteId": ""
      },
      "credentials": "000186f6a4e33bf33625e9afdabc99afc7f7010090089ae9e5fa85bcbcdfee847d4a9db6367473d192305fce7c8deff958ab87db3c27cbbd0d6c6e634934fd8b4df5aa43006da2c104244c241e393591e485ffcd84882f787584185c069ffdfbb1e0fb28651e7890f8c90d9fa300e407fb96dbd3d8830320eab43c69135ac2e49287eeffce297ee736f1319a8a9fff2f657f3720c9445427a1b5bd60dfd1b7c111b7b6006cedc10cd4bbe02854ef3e1fc9797d4ced87e310d744f6fa7f86a82c3c3700bd9b22eaaad8bf5faa5d0b6558acea4bca3039b5bcf83ab29fa0f2154cb63fc40e67360cbf27c6ec7c238e8b09cd2522b9a37c2a6314d2a61a21674c14276b5a38f82553b5ed4cfd12dffe8829ff211bb76433e41417c967a3258736f2c342047b5a6142b36e6c0809870c6919048f",
      "phoneData": {
        "number": "+380938211191",
        "namePayer": "Костянтин"
      }
    }
  },
  "id": "1"
}

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

{
  "result": {
    "status": "success",
    "errorCode": "0"
  },
  "id": "1"
}

До розділу 12 «Виставлення рахунків клієнтам по e-mail та SMS (е-invoicing)»

12.1 Форма для відправки рахунку по e-mail

<form
  action="https://www.portmone.com.ua/r3/services/invoice/email/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="login" value="shp_login" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="payeeId" value="1185" />
  <input type="hidden" name="shopOrderNumber" value="12345" />
  <input type="hidden" name="namePayer" value="Иванов И.И." />
  <input type="hidden" name="comment" value="Hello man!!!" />
  <input type="hidden" name="amount" value="150" />
  <input type="hidden" name="emailRecipient" value="[email protected]" />
  <input type="hidden" name="lang" value="uk" />
  <input type="hidden" name="cc_email" value="" />
  <input type="hidden" name="preauth_flag" value="N" />
  <input type="hidden" name="bill_currency" value="UAH" />
  <input type="hidden" name="expDate" value="20190122140200" />
</form>

12.2 Форма для відправки рахунку по SMS

<form
  action="https://www.portmone.com.ua/r3/services/invoice/sms/"
  method="post"
  target="_blank"
>
  <input type="hidden" name="login" value="shp_login" />
  <input type="hidden" name="password" value="******" />
  <input type="hidden" name="payeeId" value="1185" />
  <input type="hidden" name="shopOrderNumber" value="12345" />
  <input type="hidden" name="namePayer" value="Иванов И.И." />
  <input type="hidden" name="comment" value="Hello man!!!" />
  <input type="hidden" name="amount" value="150" />
  <input type="hidden" name="phoneRecipient" value="+380XXXXXXXXX" />
  <input type="hidden" name="lang" value="uk" />
  <input type="hidden" name="preauth_flag" value="N" />
  <input type="hidden" name="bill_currency" value="UAH" />
  <input type="hidden" name="expDate" value="20190122140200" />
</form>

12.3 Запит для масового виставлення рахунків

{
  "method": "invoices",
  "id": "1",
  "params": {
    "authData": {
      "login": "********",
      "password": "********",
      "payeeId": "1185"
    },

    "data": {
      "0": [
        "Петров Іван",
        "[email protected]",
        "123",
        "тест 1",
        "1",
        "UAH",
        "N",
        "uk",
        "20190208132000"
      ],
      "1": [
        "Тамара Миколаївна",
        "[email protected]",
        "124",
        "тест 2",
        "1.02",
        "UAH",
        "Y",
        "en",
        "20190208132000"
      ],
      "2": [
        "Олексій Петрович",
        "[email protected]",
        "125",
        "тест 3",
        "1.03",
        "EUR",
        "Y",
        "en",
        "20190208132000"
      ],
      "3": [
        "Іван Федорович",
        "+380930000000",
        "126",
        "тест 4",
        "1.04",
        "UAH",
        "Y",
        "",
        "20190208132000"
      ],
      "4": [
        "Микола Васильович",
        "+380930000000",
        "127",
        "тест 5",
        "1.05",
        "",
        "N",
        "uk",
        "20190208132000"
      ],
      "5": [
        "Олександра Сергіївна",
        "+380930000000",
        "128",
        "тест 6",
        "1.06",
        "",
        "N",
        "",
        "20190208132000"
      ],
      "6": [
        "Григорій Павлович",
        "[email protected]",
        "129",
        "тест 7",
        "10.07",
        "",
        "N",
        "",
        "20190208132000"
      ]
    }
  }
}

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

{
  "result": {
    "0": {
      "shopBillId": "448808680",
      "payeeId": "1185",
      "shopBillNumber": "123",
      "description": "тест 1",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1",
      "error": "",
      "errorCode": "0"
    },
    "1": {
      "shopBillId": "448808686",
      "payeeId": "1185",
      "shopBillNumber": "124",
      "description": "тест 2",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1.02",
      "error": "",
      "errorCode": "0"
    },
    "2": {
      "shopBillId": "448808698",
      "payeeId": "1185",
      "shopBillNumber": "125",
      "description": "тест 3",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": ".44",
      "error": "",
      "errorCode": "0"
    },
    "3": {
      "shopBillId": "448808699",
      "payeeId": "1185",
      "shopBillNumber": "126",
      "description": "тест 4",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1.04",
      "error": "",
      "errorCode": "0"
    },
    "4": {
      "shopBillId": "448808701",
      "payeeId": "1185",
      "shopBillNumber": "127",
      "description": "тест 5",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1.05",
      "error": "",
      "errorCode": "0"
    },
    "5": {
      "shopBillId": "448808703",
      "payeeId": "1185",
      "shopBillNumber": "128",
      "description": "тест 6",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "1.06",
      "error": "",
      "errorCode": "0"
    },
    "6": {
      "shopBillId": "448808704",
      "payeeId": "1185",
      "shopBillNumber": "129",
      "description": "тест 7",
      "linkInvoice": "",
      "billCurrency": "UAH",
      "billAmount": "10.07",
      "error": "",
      "errorCode": "0"
    }
  },
  "id": "1"
}

12.4 Запит для отримання платіжного посилання

{
  "method": "getLinkInvoice",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "1185",
      "amount": "15",
      "shopOrderNumber": "123ppps31",
      "emailRecipient": "[email protected]",
      "description": "test",
      "expDate": "20210217175959",
      "billCurrency": "USD",
      "preauthFlag": "N",
      "attribute1": "1",
      "attribute2": "2",
      "attribute3": "3",
      "attribute4": "4",
      "attribute5": "5",
      "goods": [
        {
          "internalCode": "123456",
          "manufacturerCode": "123456",
          "govClassificationCode": "123456",
          "name": "",
          "name_en": "",
          "description": "",
          "description_en": "",
          "price": "100",
          "quantity": "2",
          "uomCode": "",
          "amount": "200",
          "serviceFlag": "N",
          "taxRateCodes": "1",
          "descriptionUrl": "",
          "imageUrl": ""
        }
      ]
    }
  },
  "id": "1"
}

12.4 Запит для отримання платіжного посилання з розтермінуванням

{
    "method": "getLinkInvoice",
    "params": {
        "data": {
            "login": "",
            "password": "",
            "payeeId": "",
            "amount": "500",
            "installment": {
                "otp": {
                    "parts": "9"
                }
            },
            "shopOrderNumber": "",
            "emailRecipient": "",
            "description": "test",
            "preauthFlag": "N",
            "attribute1": "1",
            "attribute2": "2",
            "attribute3": "3",
            "attribute4": "4",
            "attribute5": ""
        }
    },
    "id": "1"
}

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

{
  "result": {
    "linkInvoice": "https://www.portmone.com.ua/r3/uk/i/3-CdQC",
    "shopBillId": "934904529"
  },
  "id": "1"
}

12.5 Запит для створення платіжного посилання

{
  "method": "createLinkPayment",
  "paymentTypes": {
    "createtokenonly": "N",
    "token": "N",
    "privat": "N",
    "gpay": "Y",
    "card": "Y"
  },
  "priorityPaymentTypes": {
    "token": "6",
    "gpay": "2",
    "privat": "5",
    "card": "1"
  },
  "payee": {
    "payeeId": "1185",
    "login": "",
    "dt": "",
    "signature": "",
    "displayMessage": "",
    "shopSiteId": ""
  },
  "autopayment": {
    "show": "Y",
    "edit": "N",
    "defaultCheckboxState": "N",
    "changeCheckboxState": "Y",
    "settings": {
      "period": "1",
      "payDate": "27",
      "startDate": "",
      "endDate": "01.01.2021",
      "amount": "1.22"
    },
    "credentials": "393433af5c5c46bb776878f8208fae4ad91f4ca450a28e4b558386e4c30325e3f5673522b2929adfe39655d5a530fc193094cb089a9bac58137c4533edcfa08a4c299d27a8fc060b2d671d1b63a32e66f8fc1db433185d0788fe145b93faaa75e60713d99673e4bd"
  "order": {
    "description": "",
    "shopOrderNumber": "578970",
    "billAmount": "44",
    "attribute1": "",
    "attribute2": "",
    "attribute3": "",
    "attribute4": "",
    "attribute5": "",
    "successUrl": "",
    "failureUrl": "",
    "preauthFlag": "N",
    "billCurrency": "UAH",
    "encoding": ""
  },
  "token": {
    "tokenFlag": "N",
    "returnToken": "Y",
    "token": "",
    "cardMask": "",
    "otherPaymentMethods": ""
  },
  "payer": {
    "lang": "uk",
    "emailAddress": "",
    "showEmail": "N"
  }
}

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

{
  "linkPayment": "https://prt.mn/KYbE_AKxyR",
  "error": "",
  "errorCode": "0"
}

12.6 Запит щоб закрити рахунок

{
  "method": "closeInvoice",
  "params": {
    "data": {
      "login": "wdishop",
      "password": "wdi451",
      "payeeId": "1185",
      "shopOrderNumber": "01907dfc-fd7b-7193-915c-ebae2613049a8"
    }
  }
}

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

[
    {
        "description": "",
        "status": "REJECTED",
        "attribute1": "",
        "attribute2": "",
        "attribute3": "",
        "attribute4": "",
        "commission": 0,
        "shopBillId": "1715616657",
        "shopOrderNumber": "01907dfc-fd7b-7193-915c-ebae2613049a8",
        "billAmount": "1459",
        "errorCode": "",
        "errorMessage": "Order payment time has expired or invoice was closed.  ",
        "authCode": "",
        "cardMask": "",
        "cardBankName": "",
        "token": "",
        "payeeExportResult": "",
        "gateType": ""
    }
]

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

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

{
  "description": "4444333322221111",
  "paymentType": "a2c_1",
  "attribute1": "",
  "attribute2": "\"client_id\":\"ДУДНИКИННА-\",\"taxes\":{\"income\":224,\"military\":19},\"identification\":{\"general\":{\"tax_id\":\"3472303794\"}}",
  "attribute3": "",
  "attribute": "",
  "billAmount": "3.21",
  "payeeId": "132076",
  "shopOrderNumber": "2130485714",
  "cvvVerifyFlag": "N",
  "token": "",
  "billCurrency": "UAH",
  "preauthFlag": "N",
  "shopSiteId": "",
  "cardData": "",
  "dt": "20231220155722",
  "signature": "82D0F7A4905890CC29B8FF70441C23D93296AB32CF1BCA4C169F2F88668277F0",
  "clientId": "",
  "mode": "1101",
  "cardNumber": "",
  "identification": {
    "sender": {
      "firstName": "yulia",
      "lastName": "vidpravnyk",
      "middleName": "",
      "account_number": "UA113348510000000000001919363"
    },
    "senderAddress": {
      "countryCode": "UKR",
      "city": "Kyiv",
      "address": "Obolonskiy prospekt 34v",
      "zipCode": ""
    },
    "recipient": {
      "dstFirstName": "отримувач",
      "dstLastName": "отримувач",
      "dstMiddleName": "",
      "tax_id": "3472303794"
    },
    "taxes": {
      "income": 224,
      "military": 19
    }
  }
}

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

{
  "status": "PAYED",
  "errorCode": "0",
  "error": "",
  "shopBillId": "1560011348",
  "billAmount": "3.21",
  "shopOrderNumber": "2130485714",
  "attribute1": "114599699",
  "attribute2": "\"client_id\":\"ДУДНИКИННА-\",\"taxes\":{\"income\":224,\"military\":19},\"identification\":{\"general\":{\"tax_id\":\"3472303794\"}}",
  "attribute3": null,
  "attribute4": null,
  "authCode": "000000",
  "payeeExportFlag": "Y",
  "payeeExportResultMsg": null,
  "receiptLink": "https://www.portmone.com.ua/r3/services/receipts/get-receipts/shop-bill-id/31daa0c2693575070ae7557316a26463d20e68874e2bb8b7bd5a9f9a93e706ccf898cf785ded73e280273f90b885f8a8af3ebd35da084d2a7302905087da5ef8c6d6bbd11c0adc4d7c3052f139e2471c",
  "billCurrency": "UAH",
  "transactionId": null
}