Skip to end of metadata
Go to start of metadata


Обзор

Токен-платежи ─ это новый способ оплаты покупок онлайн. По сути, они схожи с "рекуррентными" (периодическими), а присвоение токена новой сделке обеспечит автоматическую обработку последующих операции для того же клиента. Например, возможно внесение абонентской платы в автоматическом режиме, без участия владельца платежного инструмента (карты). Также возможно сохранение данных карты в системе, что позволяет владельцу не вводить ее параметры при повторных покупках. 

Если метод используется, первичные операции новых клиентов обозначаются как токен-платежи. Это позволяет запомнить клиента и автоматизировать последующие транзакции. Каждой такой операции система PayU присваивает отдельный идентификатор токена (переменная IPN_CC_TOKEN). С его помощью смогут обрабатывать будущие сделки этого же клиента (оплачиваемые той же картой), вне зависимости от суммы.

Метод доступен в рамках протокола LiveUpdate, но перед началом интеграции ТСП должен запросить предварительную настройку своей учетной записи, чтобы механизм функционировал.

Предварительные условия

Для использования токен-платежей необходимо гарантировать связь с платформой PayU через запросы HTTP POST/GET. Для этого предварительно должны быть внедрены следующие протоколы обмена данными (см. рис. ниже):

  1. LiveUpdate - HTTP POST с вебсайта ТСП на https://secure.payu.ru/order/lu.php с необходимыми данными для совершения сделки. В случае если данные приводятся в верном/ожидаемом формате, клиент перенаправляется на страницу оплаты платформы для ввода параметров банковской карты.
  2. IPN – Instant Payment Notification (мгновенное уведомление об оплате), запрос HTTP POST/GET, обеспечивающий связь PayU с URL продавца (конфигурация настраивается на панели управления PayU для каждого поставщика) и содержащий соответствующую информацию о сделке, для которой получены соответствующие разрешения и согласования. 

    По умолчанию информация о токене в IPN не передается. Чтобы начать использовать токен-платежи и передавать информацию о них через этот протокол, необходимо в настройках IPN активировать 4 поля (см. рис.). О настройках IPN см. также здесь.

  3. IDN – Instant Delivery Notification (мгновенное уведомление о доставке), обмен данными через запросы HTTP POST/GET между вебсайтом ТСП с https://secure.payu.ru/order/idn.php - Это обычная реакция ТСП, которая представляет собой сигнал PayU провести окончательные операции (списать, удержать) по счету клиента (в рамках предыдущего этапа денежные средства блокируются на счете клиента). 
    IPN и IDN обеспечивают двухступенчатую обработку платежа: сначала происходит блокировка средств на карте, затем, после подтверждения платежа, выполняется списание.
  4. IRN – Instant Reverse /Refund Notification (мгновенное уведомление об отмене сделки/возврате), обмен данными через запросы запросы HTTP POST/GET между вебсайтом ТСП и https://secure.payu.ru/order/irn.php. Это возможная реакция ТСП на IPN уведомление, в случае если сделка окончательно не проведена (по различным причинам: например, недостаточное количество продукции на складе).

 

Схема обработки первого токен-платежа через PAYU

 

Cхема обработки последующих токен-платежей 

Помимо перечисленных выше протоколов, PayU предоставляет отдельный интерфейс программирования приложений (API) для автоматического управления платежами (подробнее см. ниже).

Инициализация токен-платежей 

Для осуществления токен-платежа, интернет-магазин направляет данные в запросе HTTP POST/GET на адрес: http://secure.payu.ru/order/lu.php.

Информация о сделке должна быть представлена в формате, описанном в руководстве по реализации сервиса LiveUpdate.

В отличие от стандартного запроса LiveUpdate, каждый токен-блок должен включать в себя следующие обязательные переменные: BILL_FNAME, BILL_LNAME, BILL_EMAIL, BILL_EMAIL, BILL_PHONE, BILL_ADDRESS, BILL_CITY, DELIVERY_FNAME, DELIVERY_LNAME, DELIVERY_PHONE, DELIVERY_ADDRESS, DELIVERY_CITY (подробные описание переменных приведены ниже).

Дополнительные параметры токен-платежей приведены в таблице ниже. 

ПЕРЕМЕННАЯ

ЗНАЧЕНИЕ/Я

ОПИСАНИЕ

LU_ENABLE_TOKEN

1

Маркер сделки с использованием токена. Обеспечивает автоматическую будущих платежей через API

LU_TOKEN_TYPE

PAY_ON_TIME

Информационная переменная, в настоящее время не исползуется

Замечание

Обратите внимание, что исходная транзакция может быть выполнена и с использованием протокола ALU. Пример вида запроса для этого случая приведен ниже (также добавляется переменная LU_ENABLE_TOKEN cо значением "1").

Получение уведомлений об оплате (IPN)

После успешной авторизации каждого токен-платежа, PayU использует запросы HTTP POST/GET, чтобы направить уведомление на URL IPN, заданный продавцом в Панели управления, (вкладка Управление учетной записью > Настройки учетной записи > Настройки IPN).

Описание формата уведомления приводится в руководстве по реализации IPN. Ниже приведены параметры IPN для платежей с использованием токенов 

ПЕРЕМЕННАЯ

ОПИСАНИЕ

IPN_CC_TOKEN

Номер токена, фактически представляет собой идентификационный номер, указываемый в поле REF_NO

IPN_CC_MASK

Последние 4 цифры номера кредитной карты, используемой для осуществления платежа

IPN_CC_EXP_DATE

Срок действия кредитной карты, используемой для осуществления платежа

Поскольку в запросе передается меньше параметров, чем в протоколе LU, то и в соответствующем IPN параметров меньше.

API для токен-платежей

Специальный интерфейс API позволяет продавцам полностью контролировать токен-платежи. Функции API:

  • Новый токен-платеж
  • Отмена токен-платежа
  • Получение информации о токен-платеже

Интернет-приложение ТСП обращается к API через запросы HTTP GET  на https://secure.payu.ru/order/tokens/ 

Параметры API приведены в таблице ниже.

ПЕРЕМЕННАЯ

ОПИСАНИЕ

MERCHANT

Идентификатор продавца в PayU

REF_NO

Идентификационный номер исходного токен-платежа в системе PayU

EXTERNAL_REF

Идентификационный номер продавца по сделке

AMOUNT

Сумма нового заказа; целое число или десятичные доли, отделенные «.»

При способе TOKEN_NEWSALE поле обязательно!

CURRENCY

Валюта цены продукта (евро, российские рубли или доллары США)

При способе TOKEN_NEWSALE поле обязательно!

TIMESTAMP

Текущее время в формате универсального координированного времени (ГГГГММДДЧЧММСС)

METHOD

Один из перечисленных ниже способов, соответствующих необходимому действию:

МЕТОДОПИСАНИЕ
TOKEN_NEWSALE

Cоздание новой транзакции с существующим токеном

TOKEN_CANCEL

Отмена токена без изменения статуса самой транзакции

TOKEN_GETINFOЗапрос данных обо всех транзакциях с использованием определенного токена, включая первичную, в ходе которой он был получен

SIGN

Hash-код безопасности, аналогичный коду LiveUpdate, упорядоченный в алфавитном порядке по ключу

CANCEL_REASON

Причина отмены заказа. Заполняется в свободной форме.

Может использоваться только при значении METHOD равном TOKEN_CANCEL

Внимание!

Красным выделены обязательные поля.

При каждом обращении к API, система направляет ответ в формате JSON, который содержит две переменные: код и сообщение.

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

КОДСООБЩЕНИЕЗНАЧЕНИЕ

0

Operation successful

Успешное выполнение операции

300

Invalid transaction

Значение поля REF_NO не корректно

400

Unknown method

Переменная METHOD должна иметь одно из следующих значений: TOKEN_NEWSALE, TOKEN_CANCEL, TOKEN_GETINFO

500

Request expired

Значение переменной TIMESTAMP слишком сильно отличается от текущего времени. Проверьте системное время и убедитесь, что TIMESTAMP в зоне UTC

600

Invalid merchant

Некорректное значение переменной MerchantID. Сверьтесь со значением в Панели управления

601

Not sufficient funds

Недостаточно средств на карте

602

Expired card

Истек срок действия карты

603

Terminal is locked, please try again

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

604

Invalid Card

Используемая карта недействительна

605

Internal error

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

606

Transaction declined

Ошибка. Транзакция отклонена эмитентом карты

1200

Invalid signature

Некорректное значение переменной SIGN. Проверьте код

1300

Operation not permitted

Операция не разрешена. Недопустимое значение переменной REF_NO. Проверьте значение

1500

This token is invalid

Неверный токен. Ошибка команды для указанного значения REF_NO

1600

Invalid External Ref No

Неверная внешняя ссылка

1900

Invalid amount type

Значением переменной AMOUNT должно быть положительное число (целое или дробное)

2000

Maximum amount exedeed

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

2100

Invalid currency

Недопустимое значение переменной CURRENCY

2200

This Token is disabled

Операция не может быть выполнена: токен отменен

2401

BILL_LNAME field is mandatory

Не заполнено поле BILL_LNAME

2402

BILL_FNAME field is mandatory

Не заполнено поле BILL_FNAME

2403

BILL_EMAIL field is mandatory

Не заполнено поле BILL_EMAIL

2404

BILL_EMAIL field is not a valid e-mail

Недопустимое значение поля BILL_EMAIL

2405

BILL_PHONE field is mandatory

Не заполнено поле BILL_PHONE

2406

BILL_ADDRESS field is mandatory

Не заполнено поле BILL_ADDRESS

2407

BILL_CITY field is mandatory

Не заполнено поле BILL_CITY

2408

DELIVERY_LNAME field is mandatory

Не заполнено поле DELIVERY_LNAME

2409

DELIVERY_FNAME field is mandatory

Не заполнено поле DELIVERY_FNAME

2410

DELIVERY_PHONE field is mandatory

Не заполнено поле DELIVERY_PHONE

2411

DELIVERY_ADDRESS field is mandatory

Не заполнено поле DELIVERY_ADDRESS

2412

DELIVERY_CITY field is mandatory

Не заполнено поле DELIVERY_CITY

2413

DELIVERY_EMAIL field is not a valid e-mail

Недопустимое значение поля DELIVERY_EMAIL

2414

BILL_COUNTRYCODE field is not a valid ISO 3166-1 alpha-2country code

Значение поля BILL_COUNTRYCODE не соответствует стандарту ISO 3166-1

2415

DELIVERY_COUNTRYCODE field is not a valid ISO 3166-1 alpha-2country code

Значение поля DELIVERY_COUNTRYCODE не соответствует стандарту ISO 3166-1

Пример успешного ответа
{
    "code": 0,
    "message": "Operation successful"
}
Пример неудачной операции
{
    "code": 1500,
    "message": "This token is invalid"
}

Примеры

Первичный платеж. Запрос

Запрос при оформлении первичного токен-платежа ─ это обычный запрос через протокол Live Update.

Формат платежа (см. пример ниже) сходен с операциями через Live Update, но в данном случае используется одна дополнительная переменная (LU_ENABLE_TOKEN), идентифицирующая токен-платеж.

Для примера использован URL Live Update: https://secure.payu.ru/order/lu.php  

Запрос для токен-платежа (LU)
<form name="live_update_form_prev" method="POST" action="https://secure.payu.ru/order/lu.php" target="_blank">
<input name="MERCHANT" type="hidden" value="demoshop" id="MERCHANT">
<input name="LU_ENABLE_TOKEN" value="1" type="hidden">
<input name="LU_TOKEN_TYPE " value="PAY_ON_TIME" type="hidden">
<input name="ORDER_REF" type="hidden" value="5441049" id="ORDER_REF">
<input name="ORDER_DATE" type="hidden" value="2014-07-07" id="ORDER_DATE">
<input name="ORDER_PNAME[]" type="hidden" value="Тестовый товар" id="ORDER_PNAME0">
<input name="ORDER_PNAME[]" type="hidden" value="Второй тестовый товар" id="ORDER_PNAME1">
<input name="ORDER_PCODE[]" type="hidden" value="123" id="ORDER_PCODE0">
<input name="ORDER_PCODE[]" type="hidden" value="321" id="ORDER_PCODE1">
<input name="ORDER_PRICE[]" type="hidden" value="2" id="ORDER_PRICE0">
<input name="ORDER_PRICE[]" type="hidden" value="1" id="ORDER_PRICE1">
<input name="ORDER_QTY[]" type="hidden" value="1" id="ORDER_QTY0">
<input name="ORDER_QTY[]" type="hidden" value="1" id="ORDER_QTY1">
<input name="ORDER_VAT[]" type="hidden" value="0" id="ORDER_VAT0">
<input name="ORDER_VAT[]" type="hidden" value="0" id="ORDER_VAT1">
<input name="PRICES_CURRENCY" type="hidden" value="RUB" id="PRICES_CURRENCY">
<input name="ORDER_HASH" type="hidden" value="3ef24f929865b273687f432e58ba1be1" id="ORDER_HASH">
<input name="BILL_FNAME" type="hidden" value="Теcтовый" id="BILL_FNAME">
<input name="BILL_LNAME" type="hidden" value="плательщик" id="BILL_LNAME">
<input name="BILL_EMAIL" type="hidden" value="test@test.ru" id="BILL_EMAIL">
<input name="BILL_PHONE" type="hidden" value="79101234567" id="BILL_PHONE">
<input name="LANGUAGE" type="hidden" value="ru" id="LANGUAGE">
<input type="submit" name="submit" value="Отправить">
</form>

Демо-пример

Для примера использован URL Automatic Live Update: https://secure.payu.ru/order/alu.php  

Пример запроса токена (ALU)
"MERCHANT" => "demoshop"
"LU_ENABLE_TOKEN" => "1"
"ORDER_REF" => "7305"
"ORDER_DATE" => "2013-03-11+13:00:04"
"ORDER_PNAME[0]" => "Ticket1"
"ORDER_PCODE[0]" => "TCK1"
"ORDER_PINFO[0]" => "Barcelona flight"
"ORDER_PRICE[0]" => "100"
"ORDER_QTY[0]" => "1"
"ORDER_PNAME[1]" => "Ticket2"
"ORDER_PCODE[1]" => "TCK2"
"ORDER_PINFO[1]" => "London flight"
"ORDER_PRICE[1]" => "200"
"ORDER_QTY[1]" => "1"
"PRICES_CURRENCY" => "RUB"
"PAY_METHOD" => "CCVISAMC"
"CC_NUMBER" => "435508XXXXXX4358"
"EXP_MONTH" => "01"
"EXP_YEAR" => "2016"
"CC_CVV" => "123"
"CC_OWNER" => "IVAN PETROV"
"BACK_REF" => "https://www.example.com/alu/3ds_return.php"
"CLIENT_IP" => "127.0.0.1"
"BILL_LNAME" => "John"
"BILL_FNAME" => "Doe"
"BILL_EMAIL" => "shopper@payu.ru"
"BILL_PHONE" => "1234567890"
"BILL_COUNTRYCODE" => "RU"

Ответ на приведенную форму также аналогичен по формату платежам через LiveUpdate. Разница сводится к трем переменным, приведенным в таблице ниже. 

ПЕРЕМЕННАЯ

ЗНАЧЕНИЕ (пример)

IPN_CC_TOKEN

6121191

IPN_CC_MASK

xxxx-xxxx-xxxx-1111

IPN_CC_EXP_DATE

2012-07-18

Обработка последующих токен-платежей

Этот тип операций предназначен для автоматической обработки последующих токен-платежей клиента через API. Для формирования нового токен-платежа, переменной METHOD присваивается значение  TOKEN_ NEWSALE.

Переменные AMOUNT  и CURRENCY  необязательны для этого типа запросов. Общий перечень переменных приведен в описании API выше.

URL для обработки действий с токенами с использованием интерфейса API: https://secure.payu.ru/order/tokens/

Ниже приведены переменные запросов для последующих токен-платежей клиента.

Внимание

Настоятельно рекомендуется при последующих платежах также передавать в запросе максимальное количество данных о плательщике.

ПЕРЕМЕННАЯ

ЗНАЧЕНИЕ/ПРИМЕР

AMOUNT2000
BILL_ADDRESS Россия
BILL_CITYСанкт-Петербург
BILL_EMAILtest@mail.ru
BILL_FNAMEtest
BILL_LNAMEtest
BILL_PHONE1234456656435

CURRENCY

RUB

DELIVERY_ADDRESSгде то
DELIVERY_CITYгород
DELIVERY_EMAILtest@mail.ru
DELIVERY_FNAMEtest
DELIVERY_LNAMEtest
DELIVERY_PHONE7 999 888 77 66
EXTERNAL_REF123456

METHOD

TOKEN_NEWSALE

MERCHANT

fdswfghz

REF_NO

1234567

TIMESTAMP

20140718144154

SIGN

c80ac04ea1c125250e19df983bb83ea4

Пример ответа
{"code":"0","message":"Operation successful","tran_ref_no":"6170429"}

tran_ref_no - это номер транзакции в системе PayU.

Чтение реквизитов токен-платежа

По каждому токен-платежу предоставляется полная история, где отображаются дата, сумма, валюта и идентификационный номер сделки. Чтобы запросить информацию о любой предыдущей сделке, переменной METHOD присваивается значение TOKEN_GETINFO.

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

URL обработки токен-платежей через API: https://secure.payu.ru/order/tokens/

 Переменные для получения реквизитов по платежу

ПЕРЕМЕННАЯ

ЗНАЧЕНИЕ (пример)

METHOD

TOKEN_GET_INFO

MERCHANT

demoshop

REF_NO

612191

SIGN

2542b849191cea1061203c96d99c5189

Пример ответа
{
    "TOKEN": "6121191",
    "TOKEN_STATUS": "ACTIVE",
    "EXPIRATION_DATE": "2013-07-18",
    "HISTORY": {
        "1": {
            "TOKEN_DATE": "2012-07-18 14:21:58",
            "REF_NO": "6121191",
            "AMOUNT": "2",
            "CURRENCY": "RUB"
        },
        "2": {
            "TOKEN_DATE": "2012-07-18 14:30:01",
            "REF_NO": "6170429",
            "AMOUNT": "2",
            "CURRENCY": "RUB"
        }
    }
}

Отмена токена

Внимание

Отмена токена не влияет на сделку или платеж; для отмены транзакций используется протокол IRN.

Чтобы отменить использование токена для платежа, следует присвоить переменной METHOD значение TOKEN_CANCEL. Переменная REF_NO при этом  должна содержать идентификационный номер отменяемого токена.

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

 URL обработки токен-платежей через API: https://secure.payu.ru/order/tokens/

Переменные для отмены токена: 

ПЕРЕМЕННАЯ

ЗНАЧЕНИЕ (пример)

METHOD

TOKEN_CANCEL

MERCHANT

demoshop

REF_NO

612191

SIGN

2542b849191cea1061203c96d99c5189

Пример вида ответа
{"code":0,"message":"Operation successful"}

Справочные ресурсы

Использование PHP 

Перейти к PHP-классу, используемому в примере ниже.  Скачать класс. 

Код на PHP
/**
 * Include library
 */
require 'src/TokenService.php';
 
/**
 * token code
 */
$code = '11930179';
 
/**
 * Initialize the service object with the URL, merchant code and Secret key
 */
$token = new \PayU\MerchantClientApi\TokenService('https://secure.payu.ru/order/tokens/', 'demoshop', 'demosecret');
 
/**
 * call TOKEN_GETINFO for the token
 */
$info = $token->getInfo($code);
var_dump($info);
/*
    the displayed result would be similar to:
 
  array (size=4)
  'TOKEN' => string '11930179' (length=8)
  'TOKEN_STATUS' => string 'ACTIVE' (length=6)
  'EXPIRATION_DATE' => string '2015-03-31' (length=10)
  'HISTORY' =>
    array (size=1)
      1 =>
        array (size=4)
          'TOKEN_DATE' => string '2014-04-01 17:49:52' (length=19)
          'REF_NO' => string '11930179' (length=8)
          'AMOUNT' => string '2' (length=1)
          'CURRENCY' => string 'RUB' (length=3)
*/
 
/**
 * call TOKEN_CANCEL for the token
 */
$cancel = $token->cancel($code, 'because');
var_dump($cancel);
 
/*
    the displayed result would be similar to:
 
  array (size=2)
  'code' => int 0
  'message' => string 'Operation successful' (length=20)
*/
 
$additionalData = array(
    'BILL_FNAME' => 'Smith',
    'BILL_LNAME' => 'John',
    'BILL_EMAIL' => 'john.smith@example.com',
    'BILL_PHONE' => '0040210000000',
    'BILL_ADDRESS' => '1337 Square Place',
    'BILL_CITY' => 'Moscow',
    'DELIVERY_FNAME' => 'Smith',
    'DELIVERY_LNAME' => 'Jane',
    'DELIVERY_EMAIL' => 'jane.smith@example.com',
    'DELIVERY_PHONE' => '0040210000001',
    'DELIVERY_ADDRESS' => '1337 Square Place',
    'DELIVERY_CITY' => 'Moscow',
);
 
/**
 * call TOKEN_NEWSALE for the token
 */
$new = $token->newSale($code, 1, 'RUB', 'abc1234', $additionalData);
var_dump($new);
/*
    the displayed result would be similar to:
 
  array (size=2)
  'code' => int 601
  'message' => string 'Not sufficient funds' (length=20)
*/

(В скачанном классе и примере не забудьте заменить идентификатор ТСП, секретный ключ и другие параметры, которые относятся к вашему проекту)