Page Comparison

Info
Этот функционал будет активирован после вашего запроса в групповом чате. Также обязательно сообщите IP адреса, с которых будут отправляться запросы для добавления в белый список.

Note
Ваш сайт должен работать по схеме HTTPS и поддерживать протокол TLS 1.2.

Table of Contents

Описание

Регулярный платеж позволяет проводить списание без участия плательщика.

В запросе используется ранее сохраненная карта в виде зашифрованого CARD_TOKEN, который можно получить из callback при первой Оплата картой или Верификации карты.

Дополнительно рекомендуем ознакомиться с разделом Особенности токенов

Требования

Уведомить клиентов об условиях подписки и регулярных списаниях
Получить согласие клиентов на регулярные списания
Получить согласие клиентов с условиями договора публичной оферты
Рекомендуем дать возможность отмены подписки клиентом на сайте или приложении
Согласно правил МПС разрешается 1 попытка списания в день
Разместить договор публичной оферты
Разместить логотипы платежных систем Visa и Mastercard
Добавить логотипы PSP Platon

API параметры запроса

HTTP METHOD:

Status

colour	Green
title	POST

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

Параметр

Значение

Описание

Особенности

Обязательно

action

SALE

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

Только одно значение

Status

colour	Green
title	да

async

Y
N

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

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

Status

colour	Yellow
title	нет

channel_id

String

Дополнительный платежный канал

Позволяет отправить платежи на другой банковский терминал

Status

colour	Yellow
title	нет

async_payment

Y

Очередь оплат для быстрой обработки

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

Status

colour	Green
title	да

client_key

String

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

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

Status

colour	Green
title	да

order_id

String

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

Max 32 символа

Status

colour	Green
title	да

order_amount

Number

Сумма платежа

Tip

Верный вариант

1000.00

Warning

Неверные варианты

1000
1000.0
1,000.0
1,000.00

Status

colour	Green
title	да

order_currency

UAH

Валюта платежа

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

Status

colour	Green
title	да

order_description

String

Описание платежа

Max 255 символов

Status

colour	Green
title	да

card_token

String

Токен карты

card_token из коллбека первичной транзакции

Status

colour	Green
title	да

payer_first_name

String

Имя плательщика

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

Status

colour	Yellow
title	нет

payer_last_name

String

Фамилия плательщика

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

Status

colour	Yellow
title	нет

payer_address

String

Адрес плательщика

Max 256 символа

Status

colour	Yellow
title	нет

payer_country

String

Страна плательщика

В формате "ХХ"
2 символа
Укажите NA, если нет данных

Status

colour	Yellow
title	нет

payer_state

String

Штат плательщика

В формате "ХХ"
2 символа
Укажите NA, если нет данных

Status

colour	Yellow
title	нет

payer_city

String

Город плательщика

Max 32 символа
Укажите NA, если нет данных

Status

colour	Yellow
title	нет

payer_zip

String

Почтовый индекс плательщика

Max 32 символа
Укажите NA, если нет данных

Status

colour	Yellow
title	нет

payer_email

String

Почта плательщика

Info

Указать значение из первоначального запроса на оплату, когда был получен токен.

Оставить пустое значение, если параметр был без значения.

Status

colour	Yellow
title	нет

payer_phone

Number

Номер телефона плательщика

В формате “380XXXXXXXXX”
Max 32 символа

Status

colour	Yellow
title	нет

payer_ip

Number

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

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

Status

colour	Green
title	да

customer_wallet

String

Номер електронного кошелька пользователя

Поле обязательно для типов бизнеса связаных с виртуальными активами

Status

colour	Yellow
title	нет

term_url_3ds

String

https://platon.ua

Status

colour	Green
title	да

auth

Y
N

Холдирование средств на карте плательщика

Y или N (по умолчанию N)

Status

colour	Yellow
title	нет

ext3

recurring

Признак регулярного платежа

Status

colour	Green
title	да

hash

String

Контрольная подпись

Code Block

language	php

md5(
  strtoupper(
    strrev($payer_email).
    $client_pass.
    strrev($card_token)
  )
)

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

Status

colour	Green
title	да

Примеры запроса

Для просмотра примера раскройте список

Expand

title	Пример запроса на PHP

Code Block

language	php

<?php
  $client_pass='***';
  $data['action']='SALE';
  $data['client_key']='***';
  $data['order_id']='458-3453';
  $data['order_amount']='1000.00';
  $data['order_currency']='UAH';
  $data['order_description']='test';
  $card_token = '*****';
  $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']='http://google.com';
  $data['ext3']='recurring';
  $hash = md5(
            strtoupper(
              strrev($data['payer_email']).
              $client_pass.
              strrev($card_token)
            )
          );
?>

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>sale</title>
  </head>
  <body onload="javascript:document.forms[0].submit()">
    <form action="https://secure.platononline.com/post-unq/" method="post">
      <input type="hidden" name="action" value="<?=$data['action']?>" />
      <input type="hidden" name="client_key" value="<?=$data['client_key']?>" />
      <input type="hidden" name="order_id" value="<?=$data['order_id']?>" />
      <input type="hidden" name="order_amount" value="<?=$data['order_amount']?>" />
      <input type="hidden" name="order_currency" value="<?=$data['order_currency']?>" />
      <input type="hidden" name="order_description" value="<?=$data['order_description']?>" />
      <input type="hidden" name="card_token" value="<?=$card_token ?>" />
      <input type="hidden" name="payer_first_name" value="<?=$data['payer_first_name']?>" />
      <input type="hidden" name="payer_last_name" value="<?=$data['payer_last_name']?>" />
      <input type="hidden" name="payer_phone" value="<?=$data['payer_phone']?>" />
      <input type="hidden" name="payer_email" value="<?=$data['payer_email']?>" />
      <input type="hidden" name="payer_ip" value="<?=$data['payer_ip']?>" />
      <input type="hidden" name="term_url_3ds" value="<?=$data['term_url_3ds']?>" />
      <input type="hidden" name="ext3" value="<?=$data['ext3']?>" />
      <input type="hidden" name="hash" value="<?=$hash?>" />
    </form>                                            
  </body>
</html>

Тестирование

В целях тестирования используйте CARD_TOKEN полученный из коллбека при успешной транзакции с использованием наших тестовых реквизитов:

Проверка платежей

Получить информацию о платежах можно несколькими способами:

Используя Callback для автоматизации процесса зачисления в системе на вашей стороне
Нотификация в Telegram Bot об успешной оплате с деталями платежа сразу после списания
В вашем личном кабинете Platon
CSV файл с деталями платежей скачав в личном кабинете Platon
/wiki/spaces/docs/pages/2034926256
Банковский реестр на почту или ваш FTP
Дополнительная проверка статуса и деталей платежа по API

Работа с Callback

Info

Рекомендуем ознакомиться с разделами:

Callback и Response (

Синхронный режим)

Для просмотра примера раскройте список

Expand

title	Response при успешном списании

Code Block

language	json

{
  "action":"SALE",
  "result":"SUCCESS",
  "status":"SETTLED",
  "order_id":"4385302",
  "trans_id":"28261-34099-19648",
  "descriptor":null,
  "trans_date":"2020-02-25 06:50:09"
  "recurring_token":"01e00c2b39bb3b933723307c442efd02",
  "card_token":"8ef3111ac1093f6ccb817acef7f0845601d0994689a5f57949f94b0d086c7fe2"
}

Параметр

Описание

action

SALE

result

SUCCESS

status

SETTLED (PENDING, если в запросе было указано auth = Y)

order_id

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

trans_id

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

trans_date

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

descriptor

NULL

recurring_token

Зашифрованный токен карты для последующих транзакций по rc_token

card_token

Зашифрованный токен карты для последующих транзакций по card_token

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,
  'recurring_token' => '01e00c2b39bb3b933723307c442efd02',
  'card_token' => '8ef3111ac1093f6ccb817acef7f0845601d0994689a5f57949f94b0d086c7fe2',
  'hash' => '********************************',
)

Info

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

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

Параметр

Описание

action

SALE

result

SUCCESS

status

SETTLED (PENDING, если в запросе было указано auth = Y)

order_id

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

trans_id

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

trans_date

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

descriptor

NULL

recurring_token

Зашифрованный токен карты для последующих транзакций по rc_token

card_token

Зашифрованный токен карты для последующих транзакций по card_token

hash

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

Expand

title	Response при неуспешном списании

Code Block

language	json

{
  "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"
}

Параметр

Описание

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

Причина отмены транзакции

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' => '********************************',
)

Info

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

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

Параметр

Описание

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

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

Callback и Response (Асинхронный режим)

Данный режим активируется при передаче auth = Y или async_payment = Y В этом режиме обязательно необходимо принимать callback на ваш callback url.

Для просмотра примера раскройте список

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)

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,
  'recurring_token' => '01e00c2b39bb3b933723307c442efd02',
  'card_token' => '8ef3111ac1093f6ccb817acef7f0845601d0994689a5f57949f94b0d086c7fe2',
  'hash' => '********************************',
)

Info

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

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

Параметр	Описание
`action`	`SALE`
`result`	`SUCCESS`
`status`	`SETTLED` (`PENDING`, если в запросе было указано `auth = Y`)
`order_id`	Уникальный ордер ID транзакции в системе мерчанта
`trans_id`	Уникальный ордер ID транзакции в системе Platon
`trans_date`	Время проведения транзакции в формате UTC (YYYY-MM-DD HH-MM-SS)
`descriptor`	NULL
`recurring_token`	Зашифрованный токен карты для последующих транзакций по `rc_token`
`card_token`	Зашифрованный токен карты для последующих транзакций по `card_token`
`hash`	Зашифрованная подпись для проверки достоверности коллбека

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' => '********************************',
)

Info

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

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

Параметр	Описание
`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`	Зашифрованная подпись для проверки достоверности коллбека

Просроченные токены

Note

Если в ответе на запрос вы получили одну из указанных ниже ошибок вам необходимо удалить токен как просроченный.

Invalid card_exp_month, card_exp_year
Invalid card_exp_month
Initial transaction too old

Warning
Данный CARD_TOKEN заблокированы и не подлежат восстановлению по причине блокировки / окончания действия банковской карты.

Tip
Необходимо получить новый CARD_TOKEN проведя верификацию или оплату.

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

В ходе проведения запрос вы можете получить разные ошибки. Пожалуйста, ознакомьтесь со списком возможных ошибок, их причин и возможности решения.

Для просмотра примера раскройте список

Expand

title	Список ошибок и их решение

Ошибка	Причины	Решение
`Response: {"result":"ERROR","error_message":"Account error"}`	Ваш IP адрес не добавлен в наш белый список.	Обратитесь в тех поддержку для добавления вашего IP в белый список.
	Данный функционал вам не подключен.	Обратитесь в тех поддержку для активации функционала.
	Запрос отправлен не на нужную ссылку.	Рекомендуем сверить ссылку для отправки запроса с указаной в нужном разделе документации.
`Response: {"result":"ERROR","error_message":"Card token not found for current client"}`	Отправка запроса по CARD_TOKEN отключена для данного API ключа так как CARD_TOKEN был получен на другом ключе.	Обратитесь в тех поддержку для решения данной ситуации.
`Response: {"result":"ERROR","error_message":"Incorrect hash"}`	Неверно сформирована зашифрованная подпись.	Проверьте верность сформированной подписи. Если ошибку не нашли обратитесь в тех поддержку.
	Добавлены параметры, которые не входят в данный запрос.	Проверьте список передаваемых параметров. Если ошибку не нашли обратитесь в тех поддержку.
	Запрос был отправлен не с того API ключа по которому был получен RC_TOKEN	Рекомендуем заменить API ключ на тот, по которому был получен RC_TOKEN
`Response: {"result":"ERROR","error_message":"Empty action"}`	Параметр `action` заполнен не верно, пуст, или не на первом месте в списке параметров запроса.	Проверьте список передаваемых параметров. Если ошибку не нашли обратитесь в тех поддержку.
`Response: {"result":"ERROR","error_message":"Order already exists"}`	Значение `order_id` должно быть уникальным. Данная ошибка говорит о том, что у вас уже был использован такой `order_id`.	Заменить значение `order_id` на новое уникальное.
`Response: {"result":"ERROR","error_message":"Recurring not supported"}`	Токен больше не активен по причине завершения срока действия карты, блокировки карты, или блокировки токена.	Рекомендуем плательщику провести провести повторную оплату/верификацию для получения нового токена. Токен по которому была получена данная ошибка необходимо удалить из вашей базы данных, использовать его для списаний больше невозможно по причине блокировки.
`Response: {"result":"ERROR","error_message":"Duplicate request"}`	За одну минуту в систему вами было отправлено несколько одинаковых запросов.	Рекомендуем проверить ваш механизм отправки запросов на наличие задвоения.
`Response: {"result":"ERROR","error_message":"Incorrect card_token value"}`	Запрос был отправлен менее чем через 10 минут после получения токена.	Рекомендуем настроить отправку запросов минимум через 10 минут после получения токена. Запрос по которому получена эта ошибка необходимо повторить.
	В параметр `card_token` внесено неверное значение.	Рекомендуем проверить верность внесенных данных в поле `card_token` полученного из коллбека ранее. Запрос по которому получена эта ошибка необходимо повторить.
`Response: {"result":"ERROR","error_message":"Not found card token"}`	Запрос был отправлен менее чем через 10 минут после получения токена.	Рекомендуем настроить отправку запросов минимум через 10 минут после получения токена. Запрос по которому получена эта ошибка необходимо повторить.
	В параметр `card_token` внесено неверное значение.	Рекомендуем проверить верность внесенных данных в поле `card_token` полученного из коллбека ранее. Запрос по которому получена эта ошибка необходимо повторить.
`Response: {"result":"ERROR","error_message":"Service error"}`	Ситуация требует внимания сотрудников Platon.	Рекомендуем обратиться в тех саппорт Platon для проверки причины.
`Response: {"result":"ERROR","error_message":"Previous transaction not completed"}`	Ситуация требует внимания сотрудников Platon.	Рекомендуем обратиться в тех саппорт Platon для проверки причины.

Versions Compared

Old Version 66

New Version 67

Key

Описание

Требования

API параметры запроса

Примеры запроса

Тестирование

Проверка платежей

Работа с Callback

Callback и Response (

Callback и Response (Асинхронный режим)

Просроченные токены

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