Page Comparison

Info
Цей функціонал буде активовано після вашого запиту в груповому чаті.

Зміст

Table of Contents

minLevel	1
maxLevel	2
include
outline	false
indent	0px
style	circle
exclude
type	list
class
printable	false

Опис

Цей функціонал дозволить розмістити на вашому боці інтерфейс оплати частинами для клієнтів ПриватБанк.

Мінімальна сума - 300 грн.

Максимальна сума - 300 000 грн.

Чекліст интеграції

Привести сайт / додаток до відповідності вимогам.
Передати тех підтримці PSP Platon посилання для Callback.
Повідомити тех підтримці PSP Platon ваші IP адреси серверів сайта або про те, що буде використовуватись додаток (в цьому випадку обмеження по IP будуть зняті).
Провести інтеграцію цього API методу.
Створити і відобразити клієнту кнопку оплати частинами Приватбанк
Відобразити клієнту вибір кількості частин за необхідності в проміжку від 2 до 24 платежів (включно).
Відправити API запит з вашого сервера / додатку відповідно до цього API методу.
Редіректити платника на сторінку оформлення оплати частинами Приватбанк.
Отримати Response або Callback зі статусом платежа PSP Platon після проведення платником дій в додатку Приватбанк.
Повідомити клієнту про успішність / не успішність оплати частинами.

Вимоги до сайту

Include Page

	Вимоги до сайтів та додатків
	Вимоги до сайтів та додатків

API параметри

HTTP METHOD: POST

API ENDPOINT: https://secure.platononline.com/post/

Параметр

Значення

Опис

Особливості

action

Status

colour	Green
title	обов'язковий

SALE_PART

Код платіжного метода

client_key

Status

colour	Green
title	обов'язковий

String

API ключ мерчанта

Ключ надається на пошту мерчанта

order_id

Status

colour	Green
title	обов'язковий

String

ID оплати в системі мерчанта

Max 32 символи

order_amount

Status

colour	Green
title	обов'язковий

Number

Сума оплати

Info
Мінімальна сума оплати частинами Приватбанк - 300.00

Tip

Вірний варіант

1000.00

Warning

Невалідні варіанти

1000
1000.0
1,000.0
1,000.00

order_currency

Status

colour	Green
title	обов'язковий

UAH

Валюта

Info
Оплата можлива лише в національній валюті гривні

order_description

Status

colour	Green
title	обов'язковий

String

Опис

Note
Для кириличних символів необхідно використовувати формат UTF-8

Max 255 символів

payer_ip

Status

colour	Green
title	обов'язковий

Number

IP-адреса платника

В форматі "ХХХ.ХХХ.ХХХ.ХХХ"

Note
IPv6 на даний момент не підтримується та за наявності буде приводити до помилки.

term_url_3ds

Status

colour	Green
title	обов'язковий

String

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

Max 255 символів

payer_email

Status

colour	Green
title	обов'язковий

String

Пошта платника

Info
Обов'язково валідна пошта.

Info
Відсутність пробілів.

Max 255 символів

payer_phone

Status

colour	Green
title	обов'язковий

Number

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

Info
Обов'язковий формат телефону +380XXXXXXXXX

ext4

Status

colour	Green
title	обов'язковий

String

"{"available_parts_count":"n"}"

JSON з кількістю обраних частин від 2 до 24 (включно), наприклад "{"available_parts_count":"6"}"

channel_id

Status

colour	Blue
title	опція

String

hash

Status

colour	Green
title	обов'язковий

String

Контрольний підпис

Code Block

language	php

md5(
  strtoupper($pass).
  strrev($order_id)
)

async

Status

colour	Yellow
title	не обов'язковий

Y
N

Включити асинхронний режим

В асинхронному режимі обов'язкове використання коллбеків.
Стандартне значення N

payer_first_name

Status

colour	Yellow
title	не обов'язковий

String

Ім'я платника

Max 32 символи без пробілів

payer_last_name

Status

colour	Yellow
title	не обов'язковий

String

Прізвище платника

Max 32 символи без пробілів

payer_address

Status

colour	Yellow
title	не обов'язковий

String

Адреса платника

Max 256 символи
ВказатиNA, якщо немає даних

payer_country

Status

colour	Yellow
title	не обов'язковий

String

Країна платника

Стандарт ISO 3166-1 alpha-2
В форматі "ХХ"
2 символа
Вказати NA, якщо немає даних

payer_state

Status

colour	Yellow
title	не обов'язковий

String

Штат платника

Стандарт ISO 3166-2
В форматі "ХХ"
2 символа
Вказати NA, якщо немає даних

payer_city

Status

colour	Yellow
title	не обов'язковий

String

Місто плателника

Max 32 символи
Вказати NA, якщо немає даних

payer_zip

Status

colour	Yellow
title	не обов'язковий

String

Поштовий індекс платника

Max 32 символи

ext1, ext2, ext3, ext5, ext6, ext7, ext8, ext9, ext10

Status

colour	Yellow
title	не обов'язковий

String

10 додаткових полів

Max 1024 символи в кажному ext полі

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

Expand

title	Приклад запиту на PHP

Code Block

language	php

<?php
  $client_pass = '***';
  $data['action'] = 'SALE_PART';
  $data['client_key'] = '***';
  $data['order_id'] = '546-4588';
  $data['order_amount'] = '1000.00';
  $data['order_currency'] = 'UAH';
  $data['order_description'] = 'test';
  $data['payer_first_name'] = 'Ivan';
  $data['payer_last_name'] = 'Ivanov';
  $data['payer_phone'] = '+380111111111';
  $data['payer_email'] = 'sale@gmail.com';
  $data['payer_ip'] = '213.186.115.164';
  $data['term_url_3ds'] = 'https://google.com';
  $data['ext4'] = '{"available_parts_count":"6"}';
  $hash = md5(
            strtoupper($client_pass).
            strrev($data['order_id'])
          );

$url = 'https://secure.platononline.com/post/';
$crq = curl_init();
curl_setopt($crq, CURLOPT_URL, $url);
curl_setopt($crq, CURLOPT_HEADER, 0);
curl_setopt($crq, CURLOPT_POST, 1);
curl_setopt($crq, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($crq, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($crq, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($crq, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($crq);
if (curl_errno($crq)) {
  echo 'ERROR: '.curl_error($crq);
}else{
  echo $result;
}
curl_close($crq);

Info
Postman Collection

Тестування

Тестовий режим вмикається опціонально на боці PSP Platon.

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

Телефон - 988748970

Пароль - password8970

Info

Увага! При бойовому використанні, якщо було введено телефон який у клієнта підв'язано в Приватбанк і у нього є додаток на телефоні, то замість редіректа в браузер буде редірект в додаток. В інших випадках клієнту відкриється форма Приватбанка для авторизації в браузері.

Перевірка оплат

Expand

title	Список методів отримання результату транзакції

Include Page

	Отримання результату транзакції
	Отримання результату транзакції

Callback

Expand

title	Особливості роботи з Callback

Include Page

	Робота з Callback
	Робота з Callback

Expand

title	Безпека

Include Page

	Безпека
	Безпека

Синхронний режим:

Стандартний режим роботи. Передавати async = N не потрібно.

При успішному редіректі (синхронний режим) якщо вказано номер телефону який є у Приватбанк:

Info
В параметрі `redirect_url` вказано пусте значення. Приватбанк надішле запит на оформлення оплати частинами в додаток на телефоні платника.

Expand

title	Проміжний Response для редіректа на сторінку Приватбанк для оформлення оплати частинами

Code Block

language	json

{
  "action":"SALE",
  "result":"REDIRECT",
  "status":"REDIRECT",
  "order_id":"546-4588",
  "trans_id":"39649-42645-29973",
  "trans_date":"2023-10-05 08:24:24",
  "redirect_url":null,
  "redirect_params":null,
  "redirect_method":"GET"
}

Expand

title	Проміжний Callback для редіректа на сторінку Приватбанк для оформлення оплати частинами

Code Block

language	json

array (
  'action' => 'SALE',
  'result' => 'SUCCESS',
  'status' => 'REDIRECT',
  'order_id' => '546-45811465476r4367',
  'trans_id' => '36618-67917-29503',
  'trans_date' => '2022-10-19 13:39:51',
  'redirect_url' => null,
  'redirect_params' => null,
  'redirect_method" => 'GET',
)

При успішному редіректі (синхронний режим) якщо вказано номер телефону якого немає у Приватбанк:

Info
В параметрі `redirect_url` вказано посилання по якому треба перенаправити платника для авторизації на веб сторінці Приватбанк та оформлення оплати частинами.

Expand

title	Проміжний Response для редіректа на сторінку Приватбанк для оформлення оплати частинами

Code Block

language	json

{
  "action":"SALE",
  "result":"REDIRECT",
  "status":"REDIRECT",
  "order_id":"546-4588",
  "trans_id":"39649-42645-29973",
  "trans_date":"2023-10-05 08:24:24",
  "redirect_url":"https:\/\/payparts2.privatbank.ua\/ipp\/v2\/payment?token=172F1869B9954BE8BFF6FD493294EAD",
  "redirect_params":null,
  "redirect_method":"GET"
}

Expand

title	Проміжний Callback для редіректа на сторінку Приватбанк для оформлення оплати частинами

Code Block

language	json

array (
  'action' => 'SALE',
  'result' => 'SUCCESS',
  'status' => 'REDIRECT',
  'order_id' => '546-45811465476r4367',
  'trans_id' => '36618-67917-29503',
  'trans_date' => '2022-10-19 13:39:51',
  'redirect_url' => 'https:\/\/payparts2.privatbank.ua\/ipp\/v2\/payment?token=172F1869B9954BE8BFF6FD493294EAD',
  'redirect_params' => null,
  'redirect_method" => 'GET',
)

При успішній оплаті з HOLD (синхронний режим):

NoteУвага! Є випадки коли Приватбанк не повертає фінальний статус - в такому кейсі коллбеку з фінальним статусом не буде.

Info
HOLD активується на боці PSP Platon по запиту в чаті.

Expand

title	Callback при успішній оплаті

Code Block

language	php

array (
  'action' => 'SALE',
  'result' => 'SUCCESS',
  'status' => 'PENDING',
  'order_id' => '4385323',
  'trans_id' => '28261-47789-28578',
  'trans_date' => '2020-02-25 07:12:58',
  'descriptor' => NULL,
  'hash' => '********************************',
)

Параметр

Опис

action

SALE

result

SUCCESS

status

PENDING

order_id

Унікальний ордер ID транзакції в системі мерчанта

trans_id

Унікальний ордер ID транзакції в системі Platon

trans_date

Час проведення транзакції в форматі UTC (YYYY-MM-DD HH-MM-SS)

descriptor

NULL

hash

Зашифрований підпис для перевірки достовірності коллбека

Code Block
md5( strtoupper( strrev(email). client_pass. trans_id ) )

Info
Увага! Якщо в запиті на оплату не було вказано `email`, то при перевірці `sing` в підписі Callback варто вказати пусте значення `email`.

При успішній оплаті (синхронний режим):

NoteУвага! Є випадки коли Приватбанк не повертає фінальний статус - в такому кейсі коллбеку з фінальним статусом не буде.

Expand

title	Callback при успішній оплаті

Code Block

language	php

array (
  'action' => 'SALE',
  'result' => 'SUCCESS',
  'status' => 'SETTLED',
  'order_id' => '4385323',
  'trans_id' => '28261-47789-28578',
  'trans_date' => '2020-02-25 07:12:58',
  'descriptor' => NULL,
  'hash' => '********************************',
)

Параметр

Опис

action

SALE

result

SUCCESS

status

SETTLED

order_id

Унікальний ордер ID транзакції в системі мерчанта

trans_id

Унікальний ордер ID транзакції в системі Platon

trans_date

Час проведення транзакції в форматі UTC (YYYY-MM-DD HH-MM-SS)

descriptor

NULL

hash

Зашифрований підпис для перевірки достовірності коллбека

Code Block
md5( strtoupper( strrev(email). client_pass. trans_id ) )

Info
Увага! Якщо в запиті на оплату не було вказано `email`, то при перевірці `sing` в підписі Callback варто вказати пусте значення `email`.

При невдалій оплаті (синхронний режим):

Note
Увага! Є випадки коли Приватбанк не повертає фінальний статус при невдалій оплаті - в такому кейсі коллбеку з фінальним статусом не буде.

Expand

title	Callback при невдалій оплаті

Code Block

language	php

array (
  'action' => 'SALE',
  'result' => 'DECLINED',
  'status' => 'DECLINED',
  'order_id' => '4092002',
  'trans_id' => '28076-29879-99538',
  'trans_date' => '2020-02-03 20:49:47',
  'decline_reason' => 'Declined by processing',
  'hash' => '********************************',
)

Параметр

Опис

action

SALE

result

DECLINED

status

DECLINED

order_id

Унікальний ордер ID транзакції в системі мерчанта

trans_id

Унікальний ордер ID транзакції в системі Platon

trans_date

Час проведення транзакції в форматі UTC (YYYY-MM-DD HH-MM-SS)

descriptor

NULL

decline_reason

Причина невдалої оплати

hash

Зашифрований підпис для перевірки достовірності коллбека

Code Block
md5( strtoupper( strrev(email). client_pass. trans_id ) )

Info
Увага! Якщо в запиті на оплату не було вказано `email`, то при перевірці `sing` в підписі Callback варто вказати пусте значення `email`.

Асинхронний режим:

Цей режим активується при передачі async = Y. В цьому режимі є обов'язковим використання коллбеків.

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

Проміжна відповідь (асинхронний режим):

Expand

title	Response про прийняття запиту на обробку

Code Block

language	json

{
  "action":"SALE",
  "result":"ACCEPTED",
  "order_id":"4385302",
  "trans_id":"28261-34099-19648",
  "trans_date":"2020-02-25 06:50:09"
}

Параметр	Опис
`action`	`SALE`
`result`	`ACCEPTED`
`order_id`	Унікальний ордер ID транзакції в системі мерчанта
`trans_id`	Унікальний ордер ID транзакції в системі Platon
`trans_date`	Час проведення транзакції в форматі UTC (YYYY-MM-DD HH-MM-SS)

При успішному редіректі (aсинхронний режим):

Expand

title	Проміжний Response для редіректа на сторінку Приватбанк для оформлення оплати частинами

Code Block

language	json

{
  "action":"SALE",
  "result":"REDIRECT",
  "status":"REDIRECT",
  "order_id":"546-45811465476r4367",
  "trans_id":"36618-67917-29503",
  "trans_date":"2022-10-19 13:39:51",
  "redirect_url":"https:\/\/google.com",
  "redirect_params":null,
  "redirect_method":"GET"
}

Expand

title	Проміжний Response для редіректа на сторінку Приватбанк для оформлення оплати частинами

Code Block

language	json

array (
  'action' => 'SALE',
  'result' => 'REDIRECT',
  'status' => 'REDIRECT',
  'order_id' => '546-45811465476r4367',
  'trans_id' => '36618-67917-29503',
  'trans_date' => '2022-10-19 13:39:51',
  'redirect_url' => 'https:\/\/google.com',
  'redirect_params' => null,
  'redirect_method" => 'GET',
)

При успішній оплаті з HOLD (асинхронний режим):

Note
Увага! Є випадки коли Приватбанк не повертає фінальний статус - в такому кейсі коллбеку з фінальним статусом не буде.

Info
HOLD активується на боці PSP Platon по запиту в чаті.

Expand

title	Callback при успішній оплаті

Code Block

language	php

array (
  'action' => 'SALE',
  'result' => 'SUCCESS',
  'status' => 'PENDING',
  'order_id' => '4385323',
  'trans_id' => '28261-47789-28578',
  'trans_date' => '2020-02-25 07:12:58',
  'descriptor' => NULL,
  'hash' => '********************************',
)

Параметр

Опис

action

SALE

result

SUCCESS

status

PENDING

order_id

Унікальний ордер ID транзакції в системі мерчанта

trans_id

Унікальний ордер ID транзакції в системі Platon

trans_date

Час проведення транзакції в форматі UTC (YYYY-MM-DD HH-MM-SS)

descriptor

NULL

hash

Зашифрований підпис для перевірки достовірності коллбека

Code Block
md5( strtoupper( strrev(email). client_pass. trans_id ) )

Info
Увага! Якщо в запиті на оплату не було вказано `email`, то при перевірці `sing` в підписі Callback варто вказати пусте значення `email`.

При успішній оплаті (асинхронний режим):

NoteУвага! Є випадки коли Приватбанк не повертає фінальний статус - в такому кейсі коллбеку з фінальним статусом не буде.

Expand

title	Callback при успішній оплаті

Code Block

language	php

array (
  'action' => 'SALE',
  'result' => 'SUCCESS',
  'status' => 'SETTLED',
  'order_id' => '4385323',
  'trans_id' => '28261-47789-28578',
  'trans_date' => '2020-02-25 07:12:58',
  'descriptor' => NULL,
  'hash' => '********************************',
)

Параметр

Опис

action

SALE

result

SUCCESS

status

SETTLED

order_id

Унікальний ордер ID транзакції в системі мерчанта

trans_id

Унікальний ордер ID транзакції в системі Platon

trans_date

Час проведення транзакції в форматі UTC (YYYY-MM-DD HH-MM-SS)

descriptor

NULL

hash

Зашифрований підпис для перевірки достовірності коллбека

Code Block
md5( strtoupper( strrev(email). client_pass. trans_id ) )

Info
Увага! Якщо в запиті на оплату не було вказано `email`, то при перевірці `sing` в підписі Callback варто вказати пусте значення `email`.

При невдалій оплаті (асинхронний режим):

Note
Увага! Є випадки коли Приватбанк не повертає фінальний статус при невдалій оплаті - в такому кейсі коллбеку з фінальним статусом не буде.

Expand

title	Callback при невдалій оплаті

Code Block

language	php

array (
  'action' => 'SALE',
  'result' => 'DECLINED',
  'status' => 'DECLINED',
  'order_id' => '4092002',
  'trans_id' => '28076-29879-99538',
  'trans_date' => '2020-02-03 20:49:47',
  'decline_reason' => 'Declined by processing',
  'hash' => '********************************',
)

Параметр

Опис

action

SALE

result

DECLINED

status

DECLINED

order_id

Унікальний ордер ID транзакції в системі мерчанта

trans_id

Унікальний ордер ID транзакції в системі Platon

trans_date

Час проведення транзакції в форматі UTC (YYYY-MM-DD HH-MM-SS)

descriptor

NULL

decline_reason

Причина відміни транзакції

hash

Зашифрований підпис для перевірки достовірності коллбека

Code Block
md5( strtoupper( strrev(email). client_pass. trans_id ) )

Info
Увага! Якщо в запиті на оплату не було вказано `email`, то при перевірці `sing` в підписі Callback варто вказати пусте значення `email`.

Помилки запитів

Expand

title	Список помилок та рішень

Include Page

	Помилки та рішення при запитах
	Помилки та рішення при запитах

Versions Compared

Old Version 21

New Version 22

Key

Зміст

Опис

Чекліст интеграції

Рекомендації

Вимоги до сайту

API параметри

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

Тестування

Перевірка оплат

Callback

Синхронний режим:

При успішному редіректі (синхронний режим) якщо вказано номер телефону який є у Приватбанк:

При успішному редіректі (синхронний режим) якщо вказано номер телефону якого немає у Приватбанк:

При успішній оплаті з HOLD (синхронний режим):

При успішній оплаті (синхронний режим):

При невдалій оплаті (синхронний режим):

Асинхронний режим:

Проміжна відповідь (асинхронний режим):

При успішному редіректі (aсинхронний режим):

При успішній оплаті з HOLD (асинхронний режим):

При успішній оплаті (асинхронний режим):

При невдалій оплаті (асинхронний режим):

Помилки запитів