Versions Compared

Old Version 70

changes.mady.by.user Tech Platon

Saved on

compared with

New Version 71

changes.mady.by.user Tech Platon

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

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

Note

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

Table of Contents

Описание

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

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

Дополнительно рекомендуем ознакомиться с разделом Особенности токенов /wiki/spaces/docs/pages/1323303006

Требования

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

HTTP METHOD:

Status
colourGreen
titlePOST

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

Параметр

Значение

Описание

Особенности

Обязательно

action

SALE

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

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

Status
colourGreen
titleда

async

Y
N

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

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

Status
colourYellow
titleнет

channel_id

String

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

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

Status
colourYellow
titleнет

client_key

String

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

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

Status
colourGreen
titleда

order_id

String

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

Max 32 символа

Status
colourGreen
titleда

order_amount

Number

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

Tip

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

1000.00

Warning

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

1000
1000.0
1,000.0
1,000.00

Status
colourGreen
titleда

order_currency

UAH

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

Info

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

Status
colourGreen
titleда

order_description

String

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

Max 255 символов

Status
colourGreen
titleда

card_token

String

Токен карты

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

Status
colourGreen
titleда

payer_first_name

String

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

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

Status
colourYellow
titleнет

payer_last_name

String

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

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

Status
colourYellow
titleнет

payer_address

String

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

Max 256 символа

Status
colourYellow
titleнет

payer_country

String

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

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

Status
colourYellow
titleнет

payer_state

String

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

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

Status
colourYellow
titleнет

payer_city

String

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

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

Status
colourYellow
titleнет

payer_zip

String

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

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

Status
colourYellow
titleнет

payer_email

String

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

Валидная почта

Status
colourGreen
titleда

payer_phone

Number

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

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

Status
colourYellow
titleнет

payer_ip

Number

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

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

Status
colourGreen
titleда

customer_wallet

String

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

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

Status
colourYellow
titleнет

term_url_3ds

String

https://platon.ua

Status
colourGreen
titleда

auth

Y
N

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

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

Status
colourYellow
titleнет

ext3

recurring

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

Status
colourGreen
titleда

hash

String

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

Code Block
languagephp
md5(
  strtoupper(
    strrev($payer_email).
    $client_pass.
    strrev($card_token)
  )
)
Info

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

Status
colourGreen
titleда

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

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

Expand
titleПример запроса на PHP
Code Block
languagephp
<?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>

Iframe
scrollingno
srchttps://devplaton.com.ua/invoices/postman-test.html
frameborderhide
styleheight: 260px;

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

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

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

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

Работа с Callback

Info

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

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

Данный режим работает по умолчанию. Передавать async = N не нужно.

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

Expand
titleResponse при успешном списании
Code Block
languagejson
{
  "action":"SALE",
  "result":"SUCCESS",
  "status":"SETTLED",
  "order_id":"4385302",
  "trans_id":"28261-34099-19648",
  "descriptor":null,
  "trans_date":"2020-02-25 06:50:09"
}

Параметр

Описание

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

Expand
titleCallback при успешном списании
Code Block
languagephp
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 (PENDING, если в запросе было указано auth = Y)

order_id

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

trans_id

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

trans_date

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

descriptor

NULL

card_hash

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

Этот параметр даст вам возможность в вашей системе:

  • Привязать карту под клиента.

  • Проверить не использовал ли другой клиент эту же карту.

  • Проверить какие кредиты, товары и услуги погашаются данной картой.

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

Info

Если вы хотите использовать данный функционал, пожалуйста, сообщите нам для его включения.

hash

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

Code Block
md5(
  strtoupper(
    strrev(email).
    client_pass.
    trans_id.
    strrev(
      substr(card,0,6).
      substr(card,-4)
    )
  )
)
Info

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

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

Expand
titleResponse при неуспешном списании
Code Block
languagejson
{
  "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
titleCallback при неуспешном списании
Code Block
languagephp
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.
    strrev(
      substr(card,0,6).
      substr(card,-4)
    )
  )
)
Info

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

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

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

Промежуточный ответ (асинхронный режим):

Expand
titleResponse о принятии запроса в обработку
Code Block
languagejson
{
  "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
titleCallback при успешном списании
Code Block
languagephp
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
titleCallback при неуспешном списании
Code Block
languagephp
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 для проверки причины.