Верифікація картки (Client-Server)

Зміст

Опис

Стандартно підключається нульова верифікація - це значить, що з картки клієнта не буде проведено фактичного списання.

Верифікація картки використовується для:

Підтвердження особистості власника картки.
Отримання токенів card_token для подальших виплат та списань.

Нульова верифікація працює на всіх існуючих картках.

Одну картку можна верифікувати багато разів. Всі card_token отримані при кожній верифікації будуть різні та активні для подальшого використання.

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

При нульовій верифікації в запиті вказується 0.40 грн, але фактичного списання з платника не відбувається. В банківській виписці буде вказано 0 грн.

Налаштування нульової верифікації:

Налаштування нульової верифіккації відбувається на боці PSP Platon.

Передавати в запиті amount = 0.00 заборонено.

При нульовій верифікації повернення проводити не потрібно.

Якщо ви використовуєте після успішної верифікації введення клієнтом суми списання, то таку перевірку необхідно прибрати.

Демо

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

Привести сайт / додаток відповідно до вимог.
Інтегрувати API метод.
Передати тех підтримці PSP Platon посилання для Callback.
Провести оплату використовуючи реальну карту.
Отримати Callback.

Вимоги

SSL сертифікат

У вашого сайту має бути валідний SSL сертифікат.

Для перевірки валідності та терміну дії вашого SSL сертифіката рекомендуємо скористатися сервісом за посиланням.

TLS 1.2

Обов'язкова підтримка протоколу TLS не нижче версії 1.2

Логотипи платіжних систем та PSP Platon

У футері вашого сайту необхідно розмістити логотипи платіжних систем та PSP Platon.

У випадку регулярних списань без участі платника

Повідомити платника про умови підписки та регулярних списань та отримати підтвердження про згоду з умовами
Розмістити договір публічної оферти та отримати підтвердження від платника про згоду з умовами
Надати платнику можливість відмінити підписку
Згідно правил МПС дозволена лише одна спроба списання коштів з платника за добу

API параметри

HTTP METHOD: POST

API ENDPOINT: https://secure.platononline.com/payment/auth

Параметр		Значення	Опис	Особливості
`key` ОБОВ'ЯЗКОВИЙ		String	API ключ мерчанта	Ключ надається на пошту мерчанту
`payment` ОБОВ'ЯЗКОВИЙ		`CC`	Код платіжного метода
`data` ОБОВ'ЯЗКОВИЙ	`amount` ОБОВ'ЯЗКОВИЙ	`1.00`	Сума оплати	Вказати 0.40 грн. Фактичног списання не відбудеться. Запрещено указывать 0.
	`currency` ОБОВ'ЯЗКОВИЙ	`UAH`	Валюта оплати	Верифікація лише в національній валюті гривні.
	`description` ОБОВ'ЯЗКОВИЙ	String	Опис оплати	Для кириличних символів необхідно використовувати формат UTF-8 Max 5000 символов
	`recurring` ОБОВ'ЯЗКОВИЙ	`Y`	Створення токену картки	Для отримання `rc_id` та `rc_token`
`url` ОБОВ'ЯЗКОВИЙ		String	Посилання по якому буде відправлено платника після успішної верифікації	Max 255 символів
`formid` ОБОВ'ЯЗКОВИЙ		`verify`	Ознака верифікації
`email` ОБОВ'ЯЗКОВИЙ		String	Пошта платника
`req_token` ОБОВ'ЯЗКОВИЙ		`Y`	Створення токену картки	Для отримання `card_token`
`sign` ОБОВ'ЯЗКОВИЙ		String	Контрольний підпис	md5( strtoupper( strrev($key). strrev($payment). strrev($data). strrev($url). strrev($pass) ) )
`lang` НЕ ОБОВ'ЯЗКОВИЙ		`UK` `EN`	Мова відображення форми	В пріорітеті налаштування мови браузера клієнта
`first_name` НЕ ОБОВ'ЯЗКОВИЙ		String	Ім'я платника	Max 32 символи
`last_name` НЕ ОБОВ'ЯЗКОВИЙ		String	Прізвище платника	Max 32 символи
`phone` НЕ ОБОВ'ЯЗКОВИЙ		Number	Номер телефону платника	Обов'язковий формат телефону 380…
`address` НЕ ОБОВ'ЯЗКОВИЙ		String	Адреса платника	Max 32 символи
`zip` НЕ ОБОВ'ЯЗКОВИЙ		String	Поштовий код платника	Max 32 символи
`city` НЕ ОБОВ'ЯЗКОВИЙ		String	Місто платника	Max 32 символи
`country` НЕ ОБОВ'ЯЗКОВИЙ		String	Код країни	Стандарт ISO 3166-1 alpha-2
`state` НЕ ОБОВ'ЯЗКОВИЙ		String	Код штату, провінції або області платника	Стандарт ISO 3166-2
`customer_wallet` НЕ ОБОВ'ЯЗКОВИЙ		String	Номер електронного гаманця користувача	Поле обов'язкове для типів бизнесу пов'язаних з віртуальими активами
`order` НЕ ОБОВ'ЯЗКОВИЙ		String	ID оплати в системі мерчанта	Max 32 символи
`error_url` НЕ ОБОВ'ЯЗКОВИЙ		String	Посилання по якому буде відправлено платника після 5 невдалих спроб оплати	При відсутності посилання помилка буде відображена на платіжній формі
`ext1`, `ext2`, `ext3`, `ext4`, `ext5`, `ext6`, `ext7`, `ext8`, `ext9`, `ext10` НЕ ОБОВ'ЯЗКОВИЙ		String	Додаткові поля	Max 1024 символи в кажному ext полі
`bank_id` НЕ ОБОВ'ЯЗКОВИЙ		`yes`	Включення Bank ID	/wiki/spaces/docs/pages/1326186578
`payer_id` НЕ ОБОВ'ЯЗКОВИЙ		`yes`	Включення Payer ID	/wiki/spaces/docs/pages/1324909182

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

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

Запит має відправлятися з браузера платника Client - Server, а не з сервера мерчанта Server - Server.

Content-Type: form-data або x-www-form-urlencoded

<?php
  $pass = '***';
  $data['key'] = '***';
  $data['url'] = 'http://google.com';
  $data['data'] = base64_encode(
                    json_encode(
                      array(
                        'amount' => '1.00',
                        'description' => 'Payment',
                        'currency' => 'UAH',
                        'recurring' => 'Y'
                      )
                    )
                 );
  $data['payment'] = 'CC';
  $formid = 'verify';
  $req_token = 'Y';
  $sign = md5(
            strtoupper(
              strrev($data['key']).
              strrev($data['payment']).
              strrev($data['data']).
              strrev($data['url']).
              strrev($pass)
            )
          );
?>

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Payment</title>
  </head>
  <body onload="javascript:document.forms[0].submit()">
    <form action="https://secure.platononline.com/payment/auth" method="post">
    <input type="hidden" name="payment" value="<?=$data['payment']?>" />
    <input type="hidden" name="key" value="<?=$data['key']?>" />
    <input type="hidden" name="url" value="<?=$data['url']?>" />
    <input type="hidden" name="data" value="<?=$data['data']?>" />
    <input type="hidden" name="formid" value="<?=$formid?>" />
    <input type="hidden" name="req_token" value="<?=$req_token?>" />
    <input type="hidden" name="sign" value="<?=$sign?>" />
    </form>                                         	
  </body>
</html>

Тестування

Тестування нульової верифікації відбувається лише реальною карткою.

Час платіжної сесії

Стандартно у платника буде 15 хв для проведення оплати. Це означає, що на 15 хвилину та 1 секунду оплата стане не доступною та приведе до помилки. Відлік починається з моменту відкриття платіжної форми.

Альтернативний час платіжної сесії

Стандартний проміжок часу 15 хв є результатом багатоьох тестів та більш чим необхідно достатній для проведення оплати.

Якщо у вас є потреба в іншому проміжку, по вашому запиту можна налаштувати час платіжної сесії з наявних варіантів:

10 хв
30 хв
75 хв

Callback

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

URL для Callback

Для отримання Callback відправте URL на ваш обробник в груповий чат з вказанням API ключа для якого потрібно прописати посилання. Посилання для Callback вказується на боці PSP Platon.

Очікувана відповідь на Callback

Після відправки Callback у відповідь PSP Platon має отримати HTTP код 200.

Помилки при відправці Callback

Якщо Callback не вдалося відправити або було отримано не HTTP код 200, будуть проведені додаткові повторні спроби відправки в проміжках часу 1 хв, 5 хв, 10 хв, 15 хв, 30 хв, 60 хв.

Перевідправка Callback

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

Безпека

Увага! Рекомендації цього розділу допоможуть забезпечити безпеку від шахрайських дій пов'язаних з вашим сайтом та транзакціями.

Секретність API доступів

Не тримайте у відкритому доступі API ключ та API пароль, а також не надавайте обидва ці параметри в групові робочі чати, в тому числі з нами. Для перевірки деталей представники PSP Platon можуть попросити у вас лише API ключ, пароль треба тримати в таємниці.

Секретність кабінету

Не розголошуйте логін та пароль від вашого особистого кабінету третім особам. У випадку якщо доступ був втрачений зверніться в груповий чат. Пароль від особистого кабінету діє 30 днів. Рекомендуємо оновлювати пароль до закінчення терміну дії в 30 днів.

Секретність посилання для Callback

Не залишайте посилання для Callback у відкритому доступі на вашому ресурсі.

Сторінка успішної оплати не гарантія успіху оплати

Не використовуйте факт переходу платника на сторінку успішної оплати як признак успішної оплати. Статус транзакції та деталі оплати необхідно отримати тільки в Callback або в особистому кабінеті PSP Platon.

Звірка даних в Callback

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

Для эквайера Приватбанк - в Callback в параметре amount будет не указано 0.00, а первоначальная сумма 1.00 из запроса верификации.

Для эквайера Аваль - в Callback в параметре amount будет указано 0.00, а не первоначальная сумма 1.00 из запроса верификации.

При успішній оплаті IA

Callback при успішній оплаті карткою, Google Pay, Apple Pay, оплата частинами (при оплаті с платіжної форми)

array (
  'id' => '27374-54220-93708',
  'order' => '11-22-33',
  'status' => 'SALE',
  'rrn' => NULL,
  'approval_code' => NULL,
  'card' => '411111****1111',
  'description' => 'Оплата триал версии',
  'amount' => '1.00',
  'currency' => 'UAH',
  'name' => 'Марина Иванова',
  'email' => 'platon@gmail.com',
  'phone'=> '+380962111111',
  'country' => NULL,
  'state' => NULL,
  'city' => NULL,
  'address' => NULL,
  'date'=> '2019-11-14 15:30:22',
  'ip' => '155.209.55.69',
  'sign' => '********************************',
  'rc_id' => '27374-54220-93708',
  'rc_token' => 'b2ef4d1061621ffc0ed12d00c155ec93',
  'card_token' => '85351eeec95ebc2fef8a210ab5c9818e64157460af4600ce1210508f08f87433',
  'fee_type' => 'TRANSACTION',
  'fee' => '0.5',
)

Параметр	Опис
`id` ОБ'ЯЗКОВИЙ	Унікальний ордер ID транзакції в Platon
`order` ОБ'ЯЗКОВИЙ	Ордер ID транзакції в системі мерчанта. Якщо параметр не передавався система Platon присвоїт його самостійно
`status` ОБ'ЯЗКОВИЙ	`SALE`
`rrn` ОБ'ЯЗКОВИЙ	Значення RRN транзакції
`approval_code` ОБ'ЯЗКОВИЙ	Значення approval_code транзакції
`card` ОБ'ЯЗКОВИЙ	Маска картки в форматі ХХХХХХ****ХХХХ, або маска телефону при оплаті частинами
`description` ОБ'ЯЗКОВИЙ	Опис
`amount` ОБ'ЯЗКОВИЙ	Сума оплати
`currency` ОБ'ЯЗКОВИЙ	`UAH`
`name` ОБ'ЯЗКОВИЙ	Сума переданих параметрів `first_name` та `last_name`
`email` ОБ'ЯЗКОВИЙ	E-mail платника
`country` ОБ'ЯЗКОВИЙ	Код країни платника (2-а знака)
`state` ОБ'ЯЗКОВИЙ	Код штата платника (2-х або 3-х значний код)
`city` ОБ'ЯЗКОВИЙ	Місто платника
`address` ОБ'ЯЗКОВИЙ	Адреса платника
`date` ОБ'ЯЗКОВИЙ	Час проведення транзакції в форматі UTC (YYYY-MM-DD HH-MM-SS)
`ip` ОБ'ЯЗКОВИЙ	IP адреса платника
`ext1`, `ext2`, `ext3`, `ext4`, `ext5`, `ext6`, `ext7`, `ext8`, `ext9`, `ext10` ОПЦІЯ	Додаткові поля
`rc_id` ОПЦІЯ	Ордер ID в системі Platon для наступних транзакцій по rc_token
`rc_token` ОПЦІЯ	Зашифрований токен картки для наступних транзакцій по rc_token
`card_token` ОПЦІЯ	Зашифрований токен картки для наступних транзакцій по card_token
`card_hash` ОПЦІЯ	Уникальне зашифроване значення номера картки. Цей параметр дасть вам можливість: Прив'язати картку під клієнта. Перевірити чи не використовував її інший клієнт. Перевірити які кредити, товари та послуги оплачували цією карткою. Відслідковувати шахрайство, коли клієнт використовує ту саму картку з іншого акаунта, наприклад, щоб повторно скористатися акцією. Активується додатково по вашому зверненню в груповий чат.
`fee_type` ОПЦІЯ	Ознака яким чином знімається комісія: `ACT` - по актам. `TRANSACTION` - потранзакційно. Активується додатково по вашому зверненню в груповий чат.
`fee` ОПЦІЯ	Сума комісії з мерчанта по транзакції в ГРН Активується додатково по вашому зверненню в груповий чат.
`issuing_bank` ОПЦІЯ	Назва банку емітентка картки клієнта. Активується додатково по вашому зверненню в груповий чат.
`brand` ОПЦІЯ	`'brand' => 'VISA'` `'brand' => 'MASTER'` `'brand" => 'PROSTIR'` Активується додатково по вашому зверненню в груповий чат.
`MID` ОПЦІЯ	Унікальний ідентифікатор банківського термінала PSP Paton. Підкожний платіжний метод та мерчанта свій ідентифікатор. Активується додатково по вашому зверненню в груповий чат.
`sign` ОБ'ЯЗКОВИЙ	Зашифрований підпис для перевірки достовірності коллбека. md5( strtoupper( strrev($email). $pass. $order. strrev( substr($card,0,6). substr($card,-4) ) ) ) Увага! Якщо в запиті на оплату не було вказано `email`, то при перевірці `sing` в підписі Callback варто вказати пусте значення `email`.

Приклад GET параметрів

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

url = https://www.google.com/

order = 12345

Клієнта відправить після успішної оплати на https://www.google.com/?order=12345

При невдалій верифікації:

При невдалій верифікації Callback не відправляється.

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

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

Incorrect sign

Response: {"result":"ERROR","error_message":"Incorrect sign"}

Варіант 1

Невірно сформований зашифрований підпис.

Перевірте вірність сформованого підпису. Якщо помилку не знайшли зверніться до тих підтримки.

Варіант 2

Додані параметри, які не входять до цього запиту.

Перевірте список параметрів, що передаються. Якщо помилку не знайшли зверніться до тих підтримки.

Варіант 3

Неправильно зашифрована data.

Перевірити чи ви використовуєте UTF-8 і правильний формат параметрів.

Empty action

Response: {"result":"ERROR","error_message":"Empty action"}

Варіант 1

Параметр action заповнений неправильно, порожній, чи не першому місці у списку параметрів запиту.

Перевірте список параметрів, що передаються. Якщо помилку не знайшли зверніться до тих підтримки.

Варіант 2

Запит надсилається методом GET, а не POST.

Надіслати запит методом POST.

Order already exists

Response: {"result":"ERROR","error_message":"Order already exists"}

Значення order_id має бути унікальним. Ця помилка говорить про те, що у вас вже була успішна транзакція з таким order_id.

Замінити значення order_id на новий унікальний.

Service error

Response: {"result":"ERROR","error_message":"Service error"}

Ситуація потребує уваги співробітників Platon.

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

Previous transaction not completed

Response: {"result":"ERROR","error_message":"Previous transaction not completed"}

Ситуація потребує уваги співробітників Platon.

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

Recurring not supported

Response: {"result":"ERROR","error_message":"Recurring not supported"}

rc_token заблокований, докладніше про причини можна дізнатися у розділі /wiki/spaces/docs/pages/1323303006

Рекомендуємо видалити цей rc_token з вашої бази даних та повторити верифікацію карти для отримання rc_token та можливості проведення транзакцій за новим токеном.

Initial transaction too old

Response: {"result":"ERROR","error_message":"Initial transaction too old"}

card_token заблокований, докладніше про причини можна дізнатися у розділі /wiki/spaces/docs/pages/1323303006

Рекомендуємо видалити цей card_token з вашої бази даних та повторити верифікацію карти для отримання card_token та можливості проведення транзакцій за новим токеном.

Account error

Response: {"result":"ERROR","error_message":"Account error"}

Варіант 1

Ваша IP адреса не додана до нашого білого списку.

Зверніться до підтримки для додавання вашого IP в білий список.

Варіант 2

Цей функціонал вам не підключений.

Зверніться до підтримки для активації функціоналу.

Варіант 3

Запит надіслано не на те посилання.

Рекомендуємо звірити посилання для надсилання запиту із зазначеною у потрібному розділі документації.

Варіант 4

У запиті вказано неправильне або неіснуюче значення параметра channel_id.

Перевірте значення channel_id на достовірність або уточніть у тех підтримки доступні у вас значення.

Card token not found for current client

Response: {"result":"ERROR","error_message":"Card token not found for current client"}

Надсилання запиту по цьому card_token відключена для цього API ключа так як card_token був отриманий на іншому API ключі.

Зверніться до тих підтримки для вирішення цієї ситуації.

Incorrect hash

Response: {"result":"ERROR","error_message":"Incorrect hash"}

Варіант 1

Неправильно сформовано зашифрований підпис.

Перевірте вірність сформованого підпису. Якщо помилка не знайдена зверніться до тех підтримки.

Варіант 2

Додані параметри, які не входять до цього запиту.

Перевірте список параметрів, що передаються. Якщо помилка не знайдена зверніться до тех підтримки.

Варіант 3

Запит був відправлений не з того API ключа, за яким був отриманий rc_token.

Рекомендуємо замінити API ключ на той, яким було отримано rc_token.

Duplicate request

Response: {"result":"ERROR","error_message":"Duplicate request"}

За одну хвилину в систему було відправлено кілька однакових запитів.

Рекомендуємо перевірити ваш механізм надсилання запитів на наявність задвоєння.

Incorrect card_token value

Response: {"result":"ERROR","error_message":"Incorrect card_token value"}

Варіант 1

Запит було надіслано менш ніж через 10 хвилин після отримання токена.

Рекомендуємо налаштувати надсилання запитів щонайменше через 10 хвилин після отримання токена. Запит, за яким отримана ця помилка, необхідно повторити.

Варіант 2

В параметр card_token внесено неправильне значення.

Рекомендуємо перевірити вірність внесених даних у поле card_token отриманого з колбека раніше. Запит, за яким отримана ця помилка, необхідно повторити.

Not found card token

Response: {"result":"ERROR","error_message":"Not found card token"}

Варіант 1

Запит було надіслано менш ніж через 10 хвилин після отримання токена.

Рекомендуємо налаштувати надсилання запитів щонайменше через 10 хвилин після отримання токена. Запит, за яким отримана ця помилка, необхідно повторити.

Варіант 2

В параметр card_token внесено неправильне значення.

Рекомендуємо перевірити вірність внесених даних у поле card_token отриманого з колбека раніше. Запит, за яким отримана ця помилка, необхідно повторити.

102: Token is not active

'decline_reason' => '102: Token is not active'

rc_token заблокований, докладніше про причини можна дізнатися у розділі /wiki/spaces/docs/pages/1323303006

Рекомендуємо видалити цей rc_token з вашої бази даних та повторити верифікацію карти для отримання rc_token та можливості проведення транзакцій за новим токеном.

Wrong credit_date

'error_message' => 'Wrong credit_date'

credit_date введено не відповідно до формату YYYY-MM-DD або вказано майбутню дату.

Рекомендуємо вказати в credit_date минулу дату чи поточну у форматі YYYY-MM-DD.

Invalid pan

'error_message' => 'Invalid pan'

Invalid pan введено неправильний номер картки.

Звірте номер картки. Рекомендуємо перевіряти номер картки на дійсність перед відправкою у запиті використовуючи алгоритм Луна.

Верифікація картки (Client-Server)

Зміст

Опис

Налаштування нульової верифікації:

Демо

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

Вимоги

PSP Platon

Visa

Mastercard

Простір

Оплата частинами Monobank

Оплата частинами ПриватБанк

PCI DSS

Apple Pay

Google Pay

Privat24

API параметри

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

Тестування

Час платіжної сесії

Callback

URL для Callback

Очікувана відповідь на Callback

Помилки при відправці Callback

Перевідправка Callback

Секретність API доступів

Секретність кабінету

Секретність посилання для Callback

Сторінка успішної оплати не гарантія успіху оплати

Звірка даних в Callback

При успішній оплаті IA

При невдалій верифікації:

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

Варіант 1

Варіант 2

Варіант 3

Варіант 1

Варіант 2

Варіант 1

Варіант 2

Варіант 3

Варіант 4

Варіант 1

Варіант 2

Варіант 3

Варіант 1

Варіант 2

Варіант 1

Варіант 2