Платіжний шлюз 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. Технологія приймання оплат
Опис механізму приймання оплат платіжними картками на Інтернет-сайті магазину:
- Покупець обирає товар на сайті (або у мобільному додатку) Магазину, формує замовлення та обирає форму оплати за платіжними картками.
- Магазин переадресує Покупця на авторизаційний сервер системи Portmone.com, з передачею ряду необхідних параметрів (ідентифікатор партнера у системі Portmone.com, номер замовлення, його сума тощо).
- Авторизаційний сервер Portmone.com встановлює з Покупцем з'єднання за захищеним протоколом (TLS 1.2), перевіряє дані, що отримані від Магазину.
- Сайт Portmone.com приймає від Покупця параметри його платіжної картки та забезпечує авторизацію картки.
- При використанні верифікації Картки за технологією 3-D Secure Portmone.com спрямовує Клієнта на сайт банку-емітенту Картки для підтвердження транзакції.
- Запит на авторизацію передається через закриті банківські мережі банку-емітенту Карти Покупця або процесинговому центру, що уповноважений банком-емітентом.
- Банк передає авторизаційному серверу Portmone.com позитивний результат авторизації.
- Авторизаційний сервер Portmone.com перев іряє криптографічну цілісність інформації, що отримана, та вносить інформацію до бази даних.
- Portmone.com переадресовує Клієнта на сторінку Інтернет-магазину для підтвердження успішної оплати.
- Магазин перевіряє статус транзакції у системі Portmone.com та відпускає товар (надає послугу).
- Portmone.com у зазначені в договорі терміни здійснює перерахування коштів на рахунок Магазину (за мінусом комісії за еквайринг) одним платежем, що покриває всі транзакції за вказаний день.
- При неуспішній авторизації картки (відмові у авторизації):
- Банк передає авторизаційному серверу Portmone.com відмову від проведення платежу.
- Авторизаційний сервер Portmone.com перевіряє криптографічну цілісність інформації, що отримана, та вносить інформацію до бази даних.
- Portmone.com переадресовує запит на сторінку Інтернет-магазину для неуспішної оплати.
- При успішній оплаті на сторінку Інтернет-магазину передається методом POST номер сплаченого замовлення та дані платежу.
- Інтернет-магазин повинен додатково проконтролювати статус та суму замовлення одним з методів, що наведені у розділ і 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" і оплатити його неможливо | Ні | Заповнюється в секундах |
Структура відповіді:
Будь ласка, зверніться до "3.1 Приклад відповіді шлюзу у разі успішного здійснення платежу для запиту методом POST" для вивчення структури відповіді.
Опис параметрів відповіді:
Параметр | Опис |
---|---|
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.2. Запит у форматі JSON
Опис:
Для проведення оплати необхідно надіслати запит на URL: https://www.portmone.com.ua/gateway/.
Доступність і обмеження:
Немає обмежень.
Структура запиту:
Будь ласка, зверніться до "3.2 Запит оплати замовлення у форматі JSON" для вивчення структури запиту.
Параметри для формування JSON-структури запиту:
- payee – блок, що необхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
login | Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
dt | Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
signature | Підпис запиту | Так |
shopSiteId | Цифровий ідентифікатор каналу продажу | Ні |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
description | Опис платежу (коментар до замовлення/призначення оплати) | Ні |
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу | Так |
successUrl | Адреса Інтернет-магазину, н а яку буде спрямовано клієнта після успішної оплати | Ні |
failureUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати | Ні |
preauthFlag | Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації) | Ні |
preauthConfirm | Дата автоматичного списання заблокованих коштів для платежів з преавторизацією. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y . Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація підтверджується автоматично). Не може бути менше поточної дати. | Ні |
preauthReject | Дата автоматичного скасування преавторизації. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y . Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація скасовується автоматично). Не може бути менше поточної дати. | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
expTime | Встановлює інтервал, протягом якого замовлення може бути оплачене. Якщо значення параметру було передане, то з моменту виклику платіжної сторінки показується зворотний відлік, який видно Клієнту на сторінці оплати. По закінченню часу на оплату рахунок переходить в статус "REJECTED" і оплатити його неможливо | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute1 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute2 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute3 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute4 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute5 | Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу») | Ні |
- paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".
Параметр | Опис | Обов’язковий |
---|---|---|
card | Оплата Карткою | Ні |
portmone | Оплата через гаманець Portmone.com | Ні |
token | Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються) | Ні |
clicktopay | Оплата за допомогою Visa Click to Pay | Ні |
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 | Розстрочка платежу | Ні |
Зверніть увагу! Через внутрішні політики безпеки Google Pay та Apple Pay, при відкритті платіжної сторінки у WebView, гаманці
Google Pay
таApple Pay
можуть працювати нестабільно.
Для коректної роботи рекомендуємо пряму інтеграцію Google Pay та Apple Pay У разі наявності застосунку рекомендуємо інтегрувати SDKiOS, SDKAndroid
- installment – цей блок дозволяє керувати розстрочками платежів. Якщо параметри не задані, але в блоці
paymentTypes
переданий параметрinstallment=Y
, будуть відображені всі доступні типи розстрочки зі стандартними налаштуваннями.
Розстрочка від Приват Банку
Параметр | Опис | Обов’язковий |
---|---|---|
privat24 | Оплата частинами від ПриватБанку | Так |
parts | Дозволяє регулювати максимальну кількість місяців для розстрочки | Ні |
Приклад сторінки оплати розстрочки від ПриватБанк
Приклад оформлення оплати розстрочки від ПриватБанку
Для підключення даного методу у мерчанта має бути відкритий рахунок в Приват Банку, а у платника картка.
Розстрочка від Монобанку
Для відображення розстрочки на сторінці оплати потрібно в блоці paymentTypes
передавати параметр installment=Y
і в блоці priorityPaymentTypes
вказати порядок розташування методу, наприклад: "installment":"3"
Для можливості передачі номеру телефону платника потрібно в блоці payer
передавати параметр phoneNumber=635337143
у форматі 635337143
Приклад сторінки оплати розстрочки від Монобанку
- autopayment – цей блок дозволяє налаштувати функціонал автоматичних оплат.
Функціонал автоматичних оплат дає можливість Клієнтам підписатись на автоматичні списання коштів за графіком (щомісячно/щоквартально/щопівроку/щороку). Партнер може керувати параметрами підписки самостійно або надати можливість налаштування параметрів автоматичної оплати Клієнту.
Для початку роботи з автоматичними платежами Партнеру необхідно отримати credentials
в Особистому кабінеті.
Зверніть увагу! При зміні паролю необхідно сформувати
credentials
заново.
Після налаштування:
-
Буде створено підписку на виконання автоматичних оплат з Картки Клієнта. Portmone.com самостійно відстежує та проводить платіж. Клієнт може відключити послугу, звернувшись до підтримки Portmone.com або до співробітника Інтернет-магазину (Інтернет-магазин може самостійно видалити підписку Клієнта в Особистому кабінеті).
-
Всі наступні оплати будуть виконуватись на той же опис (
description
), що і при першій оплаті. -
Номер замовлення для автоматичних оплат буде формуватись наступним чином:
Номер замовлення при першій оплаті_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 – приклад відображення параметрів автоматичної оплати з можливістю редагування
- priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.
Важливо! У
paymentTypes
спосіб оплати повинен бути в значенні "Y", уpriorityPaymentTypes
– мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).
- token – налаштування для роботи з Токеном (див. розділ 4 «Оплата замовлення з використанням платіжного токену»)
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Обов’язковий параметр для оплати за Токеном |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Ні |
token | Значення Токену | Обов’язковий параметр для оплати за Токеном |
cardMask | Маска Картки | Обов’язковий параметр для оплати за Токеном |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Ні |
- 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 | валідний | Y | Відображається попередньо заповнене поле вводу e-mail з можливістю редагування |
3 | порожнє значення | N | Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною |
4 | валідний | N | Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною. Однак e-mail, що переданий у запиті, обробляється і на нього надсилається квитанція про сплат у |
- shipping – блок, що містить інформацію про доставку
Параметр | Опис | Обов’язковий |
---|---|---|
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 | Так |
- style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).
Структура відповіді:
Будь ласка, зверніться до "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 |
Інструкція з вбудовування платіжної сторінки у фрейм
Для запуску IFRAME на сайті необхідно:
- На сторінці партнера необхідно організувати можливість надсилання запиту на проведення оплати, наприклад, вставити форму наступного вигляду:
<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",
"clicktopay":"Y","createtokenonly":"N"},
"priorityPaymentTypes":{"card":"1","portmone":"2",
"token":"0","clicktopay":"1","createtokenonly":"0"},
"payee":{"payeeId":"3048","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").
- Додати у DOM-модель сторінки елемент IFRAME, вказавши йому парамeтр
name
зі значенням, ідентичним параметруtarget
форми з попереднього пункту.
<div>
<iframe name="myFrame" width="50%" height="70%" frameborder="0" ></iframe>
</div>
Параметри ширини та висоти фрейму можна налаштовувати за бажанням.
- Після надсилання запиту, відповідь буде відображено у вказаному фреймі.
Способи виведення сторінки оплати
Мал. 3 – стандартний стиль Portmone.com
Мал. 4 – повна стилізація сторінки для партнера
Мал. 5 – логотип партнера на сторінці наведений разом з логотипом Portmone.com
Мал. 6 – версія для відображення у вигляді фрейму на сайті Інтернет-магазину
3.4. Запит у форматі JSON для PaymentGatewayCheckout
Опис:
Дозволяє здійснювати виклик платіжного вікна без редиректу клієнта на сайт Portmone. При натисканні платіжної кнопки Portmone на сторінці оплати Мерчанта відкривається модальне вікно, в якому клієнт вводить платіжні дані.
Для розміщення платіжної кнопки Portmone на сторінці Мерчанта необхідно визначити місце розташування кнопки на сторінці та розмістити код 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>
Після завантаження скрипту pg.min.js платіжна кнопка буде розміщена в тому блоці, в якому розміщений код для завантаження скрипту.
Доступність і обмеження:
Немає обмежень.
Структура запиту:
Параметри для формування JSON-структури запиту:
Масив data
описує дані продавця, параметри замовлення та методи оплати (будь ласка, зверніться до "3.2 Запит оплати замовлення у форматі JSON" для вивчення структури масиву).
- payee – блок, що необхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
login | Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
dt | Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
signature | Підпис запиту | Так |
shopSiteId | Цифровий ідентифікатор каналу продажу | Ні |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
description | Опис платежу (коментар до замовлення/призначення оплати) | Ні |
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу | Так |
preauthFlag | Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації) | Ні |
preauthConfirm | Дата автоматичного списання заблокованих коштів для платежів з преавторизацією. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y . Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація підтверджується автоматично). Не може бути менше поточної дати. | Ні |
preauthReject | Дата автоматичного скасування преавторизації. Може використовуватись, якщо у запиті переданий параметр preauthFlag=Y . Передається у форматі: YYYYMMDDHH24MISS (дата та час, після якого преавторизація скасовується автоматично). Не може бути менше поточної дати. | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
expTime | Встановлює інтервал, протягом якого замовлення може бути оплачене. Якщо значення параметру було передане, то з моменту виклику платіжної сторінки показується зворотний відлік, який видно Клієнту на сторінці оплати. По закінченню часу на оплату рахунок переходить в статус "REJECTED" і оплатити його неможливо | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute1 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute2 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute3 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute4 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute5 | Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу») | Ні |
- paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".
Параметр | Опис | Обов’язковий |
---|---|---|
card | Оплата Карткою | Ні |
portmone | Оплата через гаманець Portmone.com | Ні |
token | Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються) | Ні |
clicktopay | Оплата за допомого ю Visa Click to Pay | Ні |
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") | Ні |
- priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.
Важливо! У
paymentTypes
спосіб оплати повинен бути в значенні "Y", уpriorityPaymentTypes
– мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).
- token – налаштування для роботи з Токеном (див. розділ 4 «Оплата замовлення з використанням платіжного токену»)
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Обов’язковий параметр для оплати за Токеном |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Ні |
token | Значення Токену | Обов’язковий параметр для оплати за Токеном |
cardMask | Маска Картки | Обов’язковий параметр для оплати за Токеном |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Ні |
- 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 | валідний | Y | Відображається попередньо заповнене поле вводу e-mail з можливістю редагування |
3 | порожнє значення | N | Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною |
4 | валідний | N | Поле вводу адреси електронної пошти не відображається на сторінці оплати. При відкритті сторінки оплати не перевіряється, чи передана Мерчантом адреса електронної пошти та чи є вона валідною. Однак e-mail, що переданий у запиті, обробляється і на нього надсилається квитанція про сплату |
- style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).
Масив brand
відповідає за брендування кнопки «Оплатити», при натистканні якої відбувається виклик вікна оплати.
Параметр | Опис | Обов’язковий |
---|---|---|
height | Встановлює висоту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці | Ні |
width | Встановлює ширину кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці | Ні |
buttoncolor | Встановлює колір кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сто рінці | Ні |
fontfamily | Встановлює тип шрифту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці | Ні |
textcolor | Встановлює колір шрифту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці | Ні |
lang | Встановлює мову для відображення тексту кнопки “Сплатити”/ “Завантажити квитанцію”. Якщо інше не було задане, приймає значення uk – українська | Ні |
padding | Встановлює значення полів навколо вмісту кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці | Ні |
border | Дозволяє одночасно встановити товщину, стиль і колір рамки навколо кнопки. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці | Ні |
fontsize | Встановлює розмір шрифту. Якщо інше не було задане, приймає стиль кнопки, встановлений на сторінці | Ні |
closemodal | Опція, що визначає, чи потрібно закривати модальне вікно після здійснення платежу клієнтом. При значенні "N" вікно не закривається, клієнту відображається повідомлення про успішну оплату у модальному вікні. При значенні "Y" – вікно закривається та виконується передача даних платежу до функції обробки мерчанта. Значення без задання: Y | Ні |
Службові функції:
-
PG.success – функція, що приймає об’єкт даних data, який описує проведений платіж. У випадку, якщо Мерчант не проводить обробку даних, платіжна кнопка змінює свій стан та назву, що дозволяє платнику завантажити квитанцію при натисканні на неї.
-
PG.brandButton – функція, що приймає об’єкт даних, який описує та стилізує платіжну кнопку.
-
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 – рядок, що характеризує вигляд модального вікна та може набувати наступних значень:
-
frame – відкриває вікно оплати у фреймі (див. мал. 7);
-
modal – відкриває вікно оплати у новому вікні браузера з заданими розмірами (див. мал. 8).
-
PG.create – функція, що створює платіжний фрейм на основі даних, що були передані у функцію PG. paymentData. Цю функцію можна використовувати у випадку, коли Мерчант створює власні механізми виклику платіжного фрейму. Не містить жодних аргументів.
-
PG.setButtonId – функція пропонується для випадків, коли Мерчан т сам проводить стилізацію кнопки виклику фрейму та ініціалізує власний текст на кнопці. Ця функція приймає в якості аргументу html-атрибут id кнопки Мерчанта. Наприклад:
PG.setButtonId('paymentButton');
. Після цього, у разі натискання на кнопку, Мерчанту буде відкриватися платіжний фрейм Portmone.
Цю функцію необхідно використовувати у комбінації с функцією PG.create.
Приклад:
- створення фрейму на основі налаштувань із функції PG. paymentData
PG.paymentData("gateway",data,"frame"); PG.create();
- встановлення id кнопки Мерчанта
PG.setButtonId('paymentButton');
Мал. 7 – приклад відкриття вікна оплати у фреймі на сайті Інтернет-магазину
Мал. 8 – приклад відкриття вікна оплати у новому вікні браузера з заданими розмірами
Структура відповіді:
Якщо Мерчант ініціалізує обробку даних після проведення платежу клієнтом на своїй стороні через службову функцію PG.success(), то для цього необхідно реалізувати обробку даних, що будуть передані до функції обробки.
Опис параметрів, що надійдуть до функції обробки:
Параметр | Опис |
---|---|
status | Статус транзакції. Приймає значення PAYED |
errorCode | Приймає значення 0 |
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 не був створений |
3.5. Підпис запиту
Формування поля signature
(приклад на PHP):
$login = 'wdishop';
$payeeId = '1185';
$password = 'wdi451';
$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 | Т ак |
password | Пароль Партнера | Так |
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу | Так |
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"
4. Оплата замовлення з використанням платіжного токену
4.1. Отримання токену для оплати
Опис:
Цей метод дозволяє отримати значення Токену та маски картки Клієнта. Після проведення цього методу оплати ви отримаєте значення Токену та маску Платіжної картки Клієнта, яку можете пропонувати Клієнтові в якості способу оплати на своєму ресурсі. У процесі виконання операції зі створення Токена, Portmone.com проведе авторизацію на 1 грн за карткою Клієнта, з наступним поверненням цієї суми на картку Клієнта.
Запит необхідно виконати на адресу: https://www.portmone.com.ua/gateway/
Доступність і обмеження:
Поле description
, що передається при виконанні цього методу, є ключовим для подальших оплат за Токеном. При зміні цього параметру у подальших оплатах за Токеном Клієнт буде отримувати повідомлення про помилку.
Структура запиту:
Будь ласка, зверніться до "4.1 Запит на створення Токену" для вивчення структури запиту.
Параметри для формування JSON-структури запиту:
- paymentTypes – блок дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).
Параметр | Опис | Обов’язковий |
---|---|---|
createtokenonly | Для створення Токену необхідно вказати значення "Y" для цього параметру | Так |
- priorityPaymentTypes – блок дозволяє керувати розміщенням способів проведення платежів на сторінці
Параметр | Опис | Обов’язковий |
---|---|---|
createtokenonly | Для створення Токену необхідно вказати значення "1" для цього параметру | Так |
- payee – блок, що не обхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
login | Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
dt | Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
signature | Підпис запиту | Так |
shopSiteId | Цифровий ідентифікатор каналу продажу | Ні |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
description | Опис платежу (коментар до замовлення/призначення оплати) | Обов’язковий, ідентифікує Токен у подальших оплатах |
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу (для отримання Токену необхідно встановити значення 1 грн) | Так |
successUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати | Ні |
failureUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати | Ні |
preauthFlag | Ознака преавторизації платежу. Обов’язкове значення при отриманні Токену – "N" (звичайна оплата без преавторизації) | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute1-4 | Службові поля, заповнюються на розсуд компанії | Ні |
- token – налаштування для роботи з Токеном
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Обов’язковий параметр для оплати за Токеном |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Ні |
token | Значення Токену | Залишити порожнім |
cardMask | Маска Картки | Залишити порожнім |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Обов’язкове значення "N" |
- payer – блок описує налаштування платника
Параметр | Опис | Обов’язковий |
---|---|---|
lang | Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська | Ні |
emailAddress | Адреса електронної пошти платника | Ні |
- 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 | Номер замовлення (рахунку), що сплачується, у Інтернет-магазині. До 120 символів |
bill_amount | Сума замовлення. Валюта – гривні. Дробова частина відокремлюється символом крапки “.” |
description | Коментар до замовлення/ опис призначення оплати. До 250 символів. |
application_url | Адреса додатку або Інтернет-магазину, на яку буде спрямований клієнт після успішної авторизації картки. Після успішної оплати замовлення на цю адресу методом POST Portmone.com надішле номер замовлення shop_order_number та дані платежу |
lang | Мова інтерфейсу платіжної системи. Можливі значення: uk – українська мова, en – англійська |
token | Необхідно встановити значення токену, що отриманий на попередньому етапі |
attribute1-4 | Службові поля, заповнюються на розсуд компанії |
attribute5 | Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу»). |
Структура відповіді:
Будь ласка, зверніться до "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:
- payee – блок, що необхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
login | Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
dt | Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
signature | Підпис запиту | Так |
shopSiteId | Цифровий ідентифікатор каналу продажу | Ні |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
description | Опис платежу (коментар до замовлення/призначення оплати) | Ні |
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу | Так |
successUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати | Ні |
failureUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати | Ні |
preauthFlag | Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації) | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute1 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute2 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute3 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute4 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute5 | Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу») | Ні |
- paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".
Параметр | Опис | Обов’язковий |
---|---|---|
card | Оплата Карткою | Ні |
portmone | Оплата через гаманець Portmone.com | Ні |
token | Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються) | Ні |
clicktopay | Оплата за допомогою Visa Click to Pay | Ні |
- priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.
Важливо! В
paymentTypes
спосіб оплати повинен бути в значенні "Y", вpriorityPaymentTypes
– мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).
- token – налаштування для роботи з Токеном
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Так |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Ні |
token | Значення Токену | Так |
cardMask | Маска Картки | Так |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Ні |
- payer – блок описує налаштування платника
Параметр | Опис | Обов’язковий |
---|---|---|
lang | Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська | Ні |
emailAddress | Адреса електронної пошти платника | Ні |
- 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" – звичайна оплата без преавторизації) |
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 | Код помилки. Якщо клієнт не знайдений, повернеться "404" |
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 | Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати | Ні |
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 Запит рекурентного платежу" для вивчення структури запиту.
Опис параметрів запиту:
- payee – блок, що необхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
credentials | Параметри авторизації ( можна отримати у вигляді хеш-рядку у кабінеті: прийом платежів -> автоплатежі https://business.portmone.com.ua/request/subscriptions | Так |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
description | Опис платежу (коментар до замовлення/призначення оплати) | Ні |
shopOrderNumber | Номер замовлення, що спла чується, у системі Партнера | Ні |
billAmount | Сума платежу | Так |
successUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати | Ні |
failureUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати | Ні |
preauthFlag | Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації) | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute1 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute2 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute3 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute4 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute5 | Використовується для передачі параметрів розщеплення платежу (див. розділ 7 «Розщеплення платежу») | Ні |
- paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".
Параметр | Опис | Обов’язковий |
---|---|---|
token | Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються) | Так |
- priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.
Важливо! В
paymentTypes
спосіб оплати повинен бути в значенні "Y", вpriorityPaymentTypes
– мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).
- token – налаштування для роботи з Токеном
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Так |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Ні |
token | Значення Токену | Так |
cardMask | Маска Картки | Так |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Ні |
- payer – блок описує налаштування платника
Параметр | Опис | Обов’язковий |
---|---|---|
lang | Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська | Ні |
emailAddress | Адреса електронної пошти платника | Ні |
showEmail | "Y" або порожнє значення – вмикає відображення поля "e-mail" на сторінці оплати, "N" – приховує поле "e-mail" на сторінці оплати (значення без задання – "Y") | Ні |
5. Переказ з картки на картку
Платіжна система Portmone.com дозволяє здійснювати переказ грошових коштів з Картки на Картку будь-якого банку України.
Переказ може здійснюватись:
1. Між Токенами Карток без вводу номерів Карток відправника та одержувача (попередньо разово створюються Токен Картки відправника та Токен Картки одержувача).
Схема взаємодії:
-
Відправник (Клієнт) разово реєструє свою картку у системі Portmome.com (здійснює транзакцію на 1 грн з наступним поверненням цієї суми на картку Клієнта протягом 30 хвилин. Інтернет-магазин отримує ідентифікатор (Токен) цієї Картки, який може зберігати у своїй системі (див. розділ 5.1 «Отримання Токену для картки»).
-
Одержувач (Клієнт або Мерчант) разово реєструє свою картку у системі Portmome.com (здійснює транзакцію на 1 грн з наступним її поверненням протягом 30 хвилин). Інтернет-магазин отримує ідентифікатор (Токен) цієї Картки, який може зберігати у своїй системі (див. розділ 5.1 «Отримання Токену для картки»).
-
Коли відправник бажає перерахувати гроші одержувачеві, Інтернет-магазин надсилає до системи Portmome.com запит у форматі json із зазначенням Токену та маски Картки відправника, Токену та маски Картки одержувача і суми платежу (див. розділ 5.2 «Створення запиту на переказ коштів між токенами карток»).
2. З Токену Картки відправника на номер Картки одержувача (див. розділ 5.3 «Запит на переказ коштів з токену на картку»).
3. З Токену Картки відправника на транзитний розрахунковий рахунок (р/р) еквайра та з розрхункового ра хунку на Токен Картки одержувача (див. розділ 5.4 «Розривний переказ коштів (з картки на рахунок + з рахунку на картку)»).
5.1. Отримання токену для картки
Опис:
Для отримання Токену (для будь-якого з учасників – як для відправника, так і для одержувача) необхідно виконати запит на адресу: https://www.portmone.com.ua/gateway/.
Доступність і обмеження:
Немає обмежень.
Структура запиту:
Будь ласка, зверніться до "5.1 Запит створення токену" для вивчення структури запиту.
Параметри для формування JSON-структури запиту:
- paymentTypes – блок дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).
Параметр | Опис | Обов’язковий |
---|---|---|
createtokenonly | Для створення Токену необхідно вказати значення "Y" для цього пара метру | Так |
- priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведения платежів на строрінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.
Важливо! У
paymentTypes
спосіб оплати повинен бути в значенні "Y", уpriorityPaymentTypes
– мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).
- payee – блок, що необхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
login | Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
dt | Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
signature | Підпис запиту | Так |
shopSiteId | Цифровий ідентифікатор каналу продажу | Ні |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
description | Залишити порожнім | Так |
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу (для отримання Токену необхідно встановити значення 1 грн) | Так |
successUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати | Ні |
failureUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute2-4 | Службові поля, з аповнюються на розсуд компанії | Ні |
- token – налаштування для роботи з Токеном
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Обов’язкове значення "N" |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Обов’язкове значення "Y" |
token | Значення Токену | Залишити порожнім |
cardMask | Маска Картки | Залишити порожнім |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Обов’язкове значення "N" |
sellerToken | Токен Картки отримувача | Залишити порожнім |
- payer – блок описує налаштування платника
Параметр | Опис | Обов’язковий |
---|---|---|
lang | Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська | Ні |
emailAddress | Адреса електронної пошти платника | Ні |
- 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 Запит на переказ коштів між токенами карток" для вивчення структури запиту.
Опис параметрів запиту:
- payee – блок, що необхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
login | Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
dt | Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
signature | Підпис запиту | Так |
shopSiteId | Цифровий ідентифікатор каналу продажу | Ні |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
description | Маска Картки одержувача | Так |
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу | Так |
successUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати | Ні |
failureUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати | Ні |
preauthFlag | Ознака преавторизації платежу (значення "Y" вказує на те, що ця оплата здійснюється з використанням процедури преавторизації (див. розділ 6 «Платежі з преавторизацією»), значення "N" – звичайна оплата без преавторизації) | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute2 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute3 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute4 | Службове поле, заповнюється на розсуд компанії | Ні |
- paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати). Якщо параметри не задані, тоді використовуються способи платежів, що закріплені за Інтернет-магазином у налаштуваннях Portmone.com, або вмикаються два основні способи проведення платежів: "card", "portmone".
Параметр | Опис | Обов’язковий |
---|---|---|
card | Оплата Карткою | Ні |
portmone | Оплата через гаманець Portmone.com | Ні |
token | Оплата за Токеном (у разі активації цього параметру, інші способи не відображаються) | Ні |
clicktopay | Оплата за допомогою Visa Click to Pay | Ні |
- priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.
Важливо! У
paymentTypes
спосіб оплати повинен бути в значенні "Y", уpriorityPaymentTypes
– мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).
- token – налаштування для роботи з Токеном
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Так |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Ні |
token | Значення Токену Картки відправника | Так |
cardMask | Маска Картки відправника | Так |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Ні |
sellerToken | Токен Картки одержувача | Так |
- payer – блок описує налаштування платника
Параметр | Опис | Обов’язковий |
---|---|---|
lang | Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська | Ні |
emailAddress | Адреса електронної пошти платника | Ні |
- style – налаштування стилів сторінки оплати (див. розділ 3.3 «Управління зовнішнім виглядом сторінки оплати»).
5.3. Запит на переказ коштів з токену на картку
Опис:
Метод дозволяє виконати переказ коштів з Токену Картки відправника на номер Картки одержувача.
Для здійснення переказу необхідно виконати запит на адресу: https://www.portmone.com.ua/gateway/.
Під час виклику методу відкривається сторінка оплати Portmone.com, на якій Клієнтові необхідно вказати номер Картки одержувача та CVV-код Картки відправника.
Доступність і обмеження:
Немає обмежень.
Структура запиту:
Будь ласка, зверніться до "5.3 Запит на переказ коштів з токену на картку" для вивчення структури запиту.
Опис параметрів запиту:
- payee – блок, що необхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
checkParams | Необхідно встановити значення "Y" | Так |
login | Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
dt | Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
signature | Підпис запиту | Так |
shopSiteId | Цифровий ідентифікатор каналу продажу | Ні |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу | Так |
successUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати | Ні |
failureUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute2 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute3 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute4 | Службове поле, заповнюється на розсуд компанії | Ні |
- paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).
Параметр | Опис | Обов’язковий |
---|---|---|
token | Переказ з Токену на Картку | Так |
- priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.
Важливо! У
paymentTypes
спосіб оплати повинен бути в значенні "Y", уpriorityPaymentTypes
– мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).
- token – налаштування для роботи з Токеном
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Так |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Ні |
token | Значення Токену Картки відправника | Так |
cardMask | Маска Картки відправника | Так |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Так |
- payer – блок описує налаштування платника
Параметр | Опис | Обов’язковий |
---|---|---|
lang | Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська | Ні |
emailAddress | Адреса електронної пошти платника | Ні |
- 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 Запит на переказ коштів з токену картки на рахунок" для вивчення структури запиту.
Опис параметрів запиту:
- payee – блок, що необхідний для ідентифікації партнера
Параметр | Опис | Обов’язковий |
---|---|---|
payeeId | Ідентифікатор Інтернет-магазину. Надається кожному Партнерові індивідуально при підключенні до системи Portmone.com | Так |
checkParams | Необхідно встановити значення "N" | Так |
login | Логін компанії. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
dt | Час створення запиту. Використовується при перевірці підпису (необхідний, якщо переданий параметр signature ) | Так |
signature | Підпис запиту | Так |
shopSiteId | Цифровий ідентифікатор каналу продажу | Ні |
- order – блок, що містить опис платежу
Параметр | Опис | Обов’язковий |
---|---|---|
shopOrderNumber | Номер замовлення, що сплачується, у системі Партнера | Ні |
billAmount | Сума платежу | Так |
successUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта після успішної оплати | Ні |
failureUrl | Адреса Інтернет-магазину, на яку буде спрямовано клієнта у разі скасування оплати | Ні |
billCurrency | Валюта проведення платежу. Значення без задання: UAH | Ні |
encoding | Кодування (кодує текст запиту з встановленого кодування у UTF-8) | Ні |
attribute2 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute3 | Службове поле, заповнюється на розсуд компанії | Ні |
attribute4 | Службове поле, заповнюється на розсуд компанії | Ні |
- paymentTypes – дозволяє обрати способи проведення платежів (Y – вмикати, N – не вмикати).
Параметр | Опис | Обов’язковий |
---|---|---|
token | Переказ з Токену на рахунок | Так |
- priorityPaymentTypes – цей блок дозволяє керувати розміщенням способів проведення платежів на сторінці. При значенні 0 навпроти методу оплати – вкладка з методом оплати не вмикається, інше по мірі зростання: 1 – до початку списку, 2 – на другій позиції, 3 – третя і т. д.
Важливо! У
paymentTypes
спосіб оплати повинен бути в значенні "Y", уpriorityPaymentTypes
– мати цифрове значення, що відмінне від 0 ("0" – вимикає відображення на сторінці оплати).
- token – налаштування для роботи з Токеном
Параметр | Опис | Обов’язковий |
---|---|---|
tokenFlag | Вмикає оплату за Токеном ("N" – не вмикати, "Y" – прийняти до уваги обробку даних) | Так |
returnToken | "Y" – вмикає опцію повернення Токена партнеру на сторінці успішної оплати, "N" або порожнє значення – не повертає Токен на сторінці успішної оплати партнера | Ні |
token | Значення Токену Картки відправника | Так |
cardMask | Маска Картки відправника | Так |
otherPaymentMethods | Дозволяє вмикати інші способи проведення платежу, коли переданий Токен ("N" – вимикає, "Y" – вмикає) | Так |
- payer – блок описує налаштування платника
Параметр | Опис | Обов’язковий |
---|---|---|
lang | Мова інтерфейсу платіжної сторінки. Можливі значення: uk – українська мова, en – англійська | Ні |
emailAddress | Адреса електронної пошти платника | Ні |
showEmail | "Y" або порожнє значення – вмикає відображення поля "e-mail" на сторінці оплати, "N" – приховує поле "e-mail" на сторінці оплати (значення без задання – "Y") | Ні |
- 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 | Маска Картки одержувача |
5.5. Переказ з картки відправника на токен отримувача
Опис:
Мерчанту потрібно зареєструватися в portmone.business за посиланням https://business.portmone.com.ua/signup (обрати розділ "для приватних осіб").
В особистому кабінеті зберегти картки, на які плануюєте о тримувати кошти.
Отримати список доступних карток для зарахування переказу.
Зробити запит на отримання посилання для переказу коштів.
5.5.1 Отримання списку доступних карток
Необхідно виконати запит на адресу: https://www.portmone.com.ua/r3/api/gateway/.
Структура запиту:
Будь ласка, зверніться до "5.5.1 Запит на отримання списку доступних карток" для вивчення структури запиту.
Опис параметрів запиту:
Параметр | Опис | Обов’язковий |
---|---|---|
method | Обов’язковий параметр для отримання спику доступних карток для зарахування переказу. Значення: getTokensForMoneyTransfer | так |
login | Логін Інтернет-магазину | так |
password | Пароль Інтернет-магазину | так |
id | Константа | так |
Структура відповіді:
Будь ласка, зверніться до "5.5.1 Відповідь на запит отримання списку доступних карток" для вивчення структури відповіді.
Опис параметрів відповіді:
Параметр | Опис |
---|---|
SHOPBILLID | Ідентифікатор транзакції (платіжного документу) у системі Portmone.com |
BILL_AMOUNT | Передана у запиті сума транзакції |
CARD_MASK | Маска Картки отримувача |
5.5.2 Отримання посилання для переказу коштів
Структура запиту:
Будь ласка, зверніться до "5.5.2 Запит на отримання посилання для переказу коштів" для вивчення структури запиту.
Опис параметрів запиту:
Параметр | Опис | Обов’язковий |
---|---|---|
method | Обов’язковий параметр для отримання посиллання на переказ коштів. Значення: getLinkMoneyTransfer | так |
login | Логін Інтернет-магазину | так |
password | Пароль Інтернет-магазину | так |
shopBillId | Номер замовлення у системі Portmone.com (повинен бути отриманий з відповіді на запит, що описаний у розділі 5.5.1 «Отримання списку доступних карток») | |
billAmount | Сума платежу | Так |
purpose | Призначення платежу | Так |
fullName | ПІБ відправника | Так |
phone | Номер телефону відправника | Ні |
commentSender | Коментар відправника | Ні |
id | Константа | так |
Структура відповіді:
Будь ласка, зверніться до "5.5.2 Відповідь на отримання посилання для переказу коштів" для вивчення структури відповіді.
Опис параметрів відповіді:
Параметр | Опис |
---|---|
result | посилання на переказ |
id | Константа |
5.5.3 Додавання картки в особистий кабінет без участі клієнта
Необхідно виконати запит на адресу: https://www.portmone.com.ua/r3/api/gateway/.
- Отримання credentials
Структура запиту:
Будь ласка, зверніться до "5.5.3 Запит на отримання значення credentials" для вивчення структури запиту.
Опис параметрів запиту:
Параметр | Опис | Обов’язковий |
---|---|---|
method | Обов’язковий параметр для отримання посиллання на переказ коштів. Значення: credentialser | так |
login | Логін Інтернет-магазину | так |
password | Пароль Інтернет-магазину | так |
id | Константа | так |
Структура відповіді:
Будь ласка, зверніться до "5.5.3 Відповідь на отримання значення credentials" для вивчення структури відповіді.
Опис параметрів відповіді:
Параметр | Опис |
---|---|
credentials | занчення для подальших запитів |
id | Константа |
- Збереження картки
Структура запиту: