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

Этот функционал будет активирован после вашего запроса в групповом чате.

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

Зміст

Опис

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

Увага! Повернення необхідно проводити в повному обсязі.

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

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

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

Вимоги

TLS 1.2

Необхідна підтримка протоколу TLS не нижче версії 1.2

API параметри

HTTP METHOD: POST

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

Параметр	Значення	Опис	Особливості
`action` ОБОВ'ЯЗКОВИЙ	`CREDITVOID`	Код платіжного метода
`client_key` ОБОВ'ЯЗКОВИЙ	String	API ключ мерчанта	Ключ надається на пошту мерчанту і має відповідати ключу по якому було проведено оплату.
`trans_id` ОБОВ'ЯЗКОВИЙ	String	ID оплати PSP Platon
`amount` ОБОВ'ЯЗКОВИЙ	Number	Сума повернення	Сума має дорівнювати сумі оплати. Вірний варіант 1000.00 Невалідні варіанти 1000 1000.0 1,000.0 1,000.00
`hash` ОБОВ'ЯЗКОВИЙ	String	Контрольний підпис	md5( strtoupper( $pass. $trans_id ) )

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

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

<?php
  $client_pass = '***';
  $data['client_key'] = '***';
  $data['action'] = 'CREDITVOID';
  $data['trans_id'] = '19848-26243-92097';
  $data['amount'] = '85.00';
  $data['hash'] = md5(
                    strtoupper(
                      $pass.
                      $trans_id
                    )
                  );
          
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://secure.platononline.com/post-unq/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $data,
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Callback и Response

Особенности работы с 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 на відповідність початкової суми та ордера у вашій базі даних, які були вказані при створенні замовлення.

Промежуточный ответ:

Response при успешной авторизации запроса на возврат

{
  "action":"CREDITVOID",
  "result":"ACCEPTED",
  "order_id":"27859-52747-0554",
  "trans_id":"27859-54289-00657"
}

При успешном возврате:

Callback при успешном возврате при оплате по протоколу https://secure.platononline.com/payment/auth

Callback отправляется через час после успешной авторизации

array (
  'id' => '27860-50312-05387',
  'order' => '27860-49622-7227',
  'status' => 'REFUND',
  'rrn' => NULL,
  'approval_code' => NULL,
  'card' => '**************',
  'description' => 'Оплата',
  'amount' => '500.00',
  'currency' => 'UAH',
  'name' => ' ',
  'email' => NULL,
  'country' => NULL,
  'state' => NULL,
  'city' => NULL,
  'address' => NULL,
  'date' => '2020-01-09 21:23:51',
  'ip' => '46.133.140.32',
  'sign' => '********************************'
)

Для проверки достоверности полученного callback, рекомендуем сверять подпись sign по формуле md5(strtoupper(strrev(email).client_pass.order.strrev(substr(card,0,6).substr(card,-4)))).

Внимание! Если при запросе на оплату не был указан email, то при проверке sing в подписи коллбека следует указать пустое значение для email.

Callback при успешном ПОЛНОМ возврате при оплате по протоколу https://secure.platononline.com/post-unq/

Callback отправляется через час после успешной авторизации

array (
  'action' => 'CREDITVOID',
  'result' => 'SUCCESS',
  'status' => 'REFUND',
  'order_id' => '7428404',
  'trans_id' => '30009-01494-16697',
  'amount' => '97.00',
  'creditvoid_date' => '2020-09-15 07:30:16',
  'hash' => '********************************',
)

Для проверки достоверности полученного callback, рекомендуем сверять подпись sign по формуле md5(strtoupper(strrev(email).client_pass.trans_id.strrev(substr(card,0,6).substr(card,-4)))).

Внимание! Если при запросе на оплату не был указан email, то при проверке sing в подписи коллбека следует указать пустое значение для email.

Callback при успешном ЧАСТИЧНОМ возврате при оплате по протоколу https://secure.platononline.com/post-unq/

Callback отправляется через час после успешной авторизации

array (
  'action' => 'CREDITVOID',
  'result' => 'SUCCESS',
  'status' => 'SETTLED',
  'order_id' => '7428404',
  'trans_id' => '30009-01494-16697',
  'amount' => '97.00',
  'creditvoid_date' => '2020-09-15 07:30:16',
  'hash' => '********************************',
)

Для проверки достоверности полученного callback, рекомендуем сверять подпись sign по формуле md5(strtoupper(strrev(email).client_pass.trans_id.strrev(substr(card,0,6).substr(card,-4)))).

Внимание! Если при запросе на оплату не был указан email, то при проверке sing в подписи коллбека следует указать пустое значение для email.

При ошибке запроса:

Response при неуспешной авторизации запроса на возврат

{
  "result":"ERROR",
  "error_message":"Transaction already refunded"
}

Дополнительная проверка возврата

Для получения информации о возврате в случае, если ваша система не смогла принять Callback, Response или по другой причине, можно воспользоваться дополнительными API запросами проверки:

Ошибки запросов

Список ошибок, их причин и возможных решений.

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 введено неправильний номер картки.

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

Связанные разделы

Другие методы возвратов:

Возвраты