Skip to end of metadata
Go to start of metadata

Введение

С помощью API можно осуществить перевод денежных средств на банковскую карту. Существует два варианта передачи информации в запросе:

  • отправить запрос с токеном
  • отправить запрос с номером карты

Второй вариант можно реализовать быстрее, но первый вариант предпочтителен в том случае, если у магазина (МФО) нет сертификата PCI DSS. Далее описывается процесс проведения выплаты.

В запросе магазин (МФО) может высылать либо реквизиты карты, либо ранее сформированный токен. Если высланы оба типа данных, то возникнет ошибка.

Важно

  • Поля запросов этого API чувствительны к регистру!
  • Для API не предусмотрен тестовый режим.
  • Не рекомендуется вносить изменения в формы запросов API, например, вносить дополнительные события (напр., submit). Это приведет к нарушению расчета подписи и ошибке.

Запрос выплаты

Описание потока данных

  1. Магазин (МФО) направляет в систему PayU запрос (HTTP POST), содержащий данные о выплате.
  2. PayU принимает запрос и направляет второй запрос в Банк.
  3. Банк предпринимает попытку обработки запроса и направляет назад результаты выполнения операции.
  4. PayU регистрирует ответ и направляет магазину (МФО) результаты выполнения операции в формате JSON.

Поля запроса

Обязательные поля отмечены красным.

ПОЛЕ

ОПИСАНИЕ

ПРИМЕР

merchantCode

Код продавца. Это код можно посмотреть на странице https://secure.payu.ru/cpanel/account_settings.php. Обычно длинной 8 символов

codecode

currency

Валюта

RUB

amountСумма транзакции45.00

outerId

Идентификатор сделки в системе магазина (МФО). Можно передавать любой набор цифр

12365126

senderFirstName

Имя отправителя (можно передавать название юр лица)

Ivan

senderLastName

Фамилия отправителя (можно передавать название юр лица)

Ivanov

senderEmail

Адрес электронной почты отправителя

senderEmail@mail.com

senderPhone

Телефон отправителя (в числовом формате)

9998887766

clientEmail

Адрес электронной почты клиента

clientEmail@mail.com

clientFirstName

Имя клиента (если не известно, то можно передать Уважаемый Клиент)

Ivan

clientLastName

Фамилия клиента

Ivanov

clientCity

Город клиента

-

clientAddress

Адрес клиента

-

clientPostalCode

Индекс клиента

123123

clientCountryCode

Код страны клиента

RU

ccnumber

Номер кредитной карты

Запрос может содержать лишь один из параметров: ccnumber или token. Наличие обоих параметров приведет к возникновению ошибки.

4111111111111111

token

Токен, полученный при регистрации карты

Запрос может содержать лишь один из параметров: ccnumber или token. Наличие обоих параметров приведет к возникновению ошибки.

090312897KLHDOlkdsjklodsu

desc

Описание

Произвольный текст

timestamp

UNIX timestamp

1480062984

signature

Подпись запроса (формируется автоматически на стороне магазина)

adfbadb6072d4348dcbbcc9ee8f63623

Поля ответа на запрос выплаты

ПОЛЕ

ОПИСАНИЕ

ПРИМЕР

code

Код ответа (числовой)

-100

description

Описание

Error with sending the Payout to the bank

Пример запроса и ответа

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

Запрос выплаты
[merchantCode] => PWA
[amount] => 20
[currency] => RUB
[outerId] => 11117887
[senderFirstName] => senderFirstName
[senderLastName] => senderLastName
[senderEmail] => senderEmail@a.aa
[senderPhone] => 0764111111
[clientEmail] => spam19085138@devil.allegro.ru
[clientPhone] => 0764222222
[clientFirstName] => us_first_name19085138
[clientLastName] => us_last_name19085138
[clientCity] => clientCity
[clientAddress] => address
[clientPostalCode] => 123123123
[clientCountryCode] => RU
[ccnumber] => 4149605380309302
[token] => 
[merchantFee] => 2
[desc] => Description
[timestamp] => 1378803851
[paymentChannel] => paymentChannel
[signature] => d78571cfaa6f35c8ccbf79a3a9035239

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

Ответ (сообщение об ошибке)
{"-100":"Error with sending the Payout to the bank"}

Регистрация карт (формирование запроса токена)

Описание потока данных

Процесс регистрации карты включает в себя два этапа:

  1. Магазин (МФО) направляет запрос на регистрацию карты, когда плательщик вводит ее реквизиты на безопасной странице системы PayU.
  2. PayU сохраняет данные карты в своей системе и формирует Токен.
  3. PayU направляет Токен на URL, который магазин (МФО) передала специалистам PayU. Уведомление с Токеном - это POST запрос, похожий на протокол IPN.

Запрос регистрации карты

  1. Магазин (МФО) направляет запрос в систему PayU и перенаправляет пользователя на страницу системы.
  2. На соответствующей странице плательщик вводит реквизиты карты..
  3. PayU перенаправляет плательщика на URL, заданный параметром back_url в составе запроса.

Поля запроса регистрации карты

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

ПОЛЕ

ОПИСАНИЕ

ПРИМЕР ЗНАЧЕНИЯ, ТИП ПОЛЯ

MerchID             

Идентификатор магазина (МФО). Специальный числовой идентификатор, который нужно запрашивать отдельно у специалистов PayU

6187 (число)

RequestID       

Уникальный идентификационный номер запроса, генерируемый ТСП

11117961 (число)

Email                    

Адрес электронной почты плательщика

test@test.com (строка)

FirstName         

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

Ivan (строка)

LastName          

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

Ivanov (строка)

Description       

Описание

Произвольный текст (строка)

CardOwnerId   

Значение, задаваемое системой магазина (МФО)

123123123   (число)

BackURL             

URL, на который перенаправляется плательщик после ввода данных кредитной карты на странице PayU

http://www.my-mfo-site.com/ (строка)

Timestamp        

UNIX timestamp

1480062984  (дата)

Signature           

Подпись запроса

2207a004fa9872be75eed9436961b1e9

Пример страницы регистрации карты

Это страницу можно открывать как в номом окне так и в Iframe. Внешний вид страницы нельзя изменить.

Уведомление о токене

  1. Система PayU направляет магазину (МФО) запрос, содержащий Токен и идентификатор исходного запроса. Отправляется на URL, который вы сообщили специалистам PayU.
  2. Магазин (МФО) подтверждает получение, отправляя строку "OK" . В случае не получения этого ответа, PayU переотправляет уведомление с Токеном (до 10).

Параметры уведомления, которое содержит Токен

ПОЛЕ

ОПИСАНИЕ

ПРИМЕР/ТИП

RequestID         

Идентификационный номер запроса на регистрацию карты.

11117961

token                

Токен, генерируемый для кредитной карты, полученный в рамках запроса CardRegister

090312897KLHDOlkdsjklodsu

CardMask          

Токен, генерируемый для кредитной карты, полученный в рамках запроса CardRegister

4111-xxxx-xxxx-1111 (строка)

Timestamp        

Дата и время запроса (формируется автоматически)

2013-08-19 12:19:36 (дата)

Signature

Подпись запроса (формируется автоматически)

7f1a0b2689e26d09e423602fd6d85af1

Примеры

Пример запроса на регистрацию карты
BackURL=http://payu2.ru.costinh 
CardOwnerId=123123123
Description=Description
Email=spam19085138@devil.allegro.ru 
FirstName=us_first_name19085138
LastName=us_last_name19085138
MerchID=6187
RequestID=11117127
Signature=211f583f04a2bae79763e47ee793f17c
Timestamp=1378717377
Пример уведомления о присвоении токена
     [RequestID] => 11116830
     [Token] => b54f37470b2bcfc554695e7cd28d564b
     [CardMask] => 4111-xxxx-xxxx-1111
     [Timestamp] => 1385634147
     [Signature] => 7f1a0b2689e26d09e423602fd6d85af1

Возможные коды ответа на запрос выплаты

КОД

ЗНАЧЕНИЕ КОДА

1

Успешно завершено

9PENDING (нужно запрашивать статус транзакции, пока он не изменится на COMPLETE или CANCELLED)

-1

ОШИБКА

-100

Ошибка при отправке выплаты в банк

-101

Поле MerchantCode не заполнено

-102

Неверное значение поля MerchantCode: информация о ТСП в системе отсутствует

-103

Неверное значение поля MerchantCode: информация о ТСП существует, но пакет выплат не активирован

-104

Ошибка поля Amount

-105

Ошибка поля OuterId

-106

Ошибка поля SenderEmail

-107

Сумма сделки меньше суммы комиссии

-108

Ошибка поля ClientCountry

-109

Ошибка поля CCnumber

-110

Ошибка в описании

-111

Ошибка подписи

-112

Информация по остатку отсутствует

-113

Ошибка поля SenderPhone

-114

Ошибка поля ClientEmail

-115

Ошибка поля ClientPhone

-116

Ошибка поля SenderFirstName

-117

Ошибка поля SenderLastName

-118

Ошибка поля ClientFirstName

-119

Ошибка поля ClientLastName

-120

Ошибка поля Currency

-121

Ошибка поля Timestamp

-122

Следует направить только один идентификатор получателя (токен или карту)

-123

Следует направить хотя бы один идентификатор получателя (токен или карту)

-124

Ошибка токена

-125

Ошибка поля ClientCountryCode

Примечание

Перед кодами ошибок ставится символ  "-"

Правила формирования подписей

Все запросы должны содержать подпись, сформированную по специальному алгоритму.

Этапы формирования подписи

  1. Сортировка всего запроса по имени параметров (исключая Signature). 
  2. Формирование базовой строки из значений всех полей (исключая Signature).
  3. Добавления секретного ключа в конце строки
  4. Применение метода MD5 для формирования подписи (также используется секретный ключ).

Пример

Запрос выплаты
[merchantCode] => PWA
[amount] => 20
[currency] => RUB
[outerId] => 11117887
[senderFirstName] => senderFirstName
[senderLastName] => senderLastName
[senderEmail] => senderEmail@a.aa
[senderPhone] => 0764111111
[clientEmail] => spam19085138@devil.allegro.ru
[clientPhone] => 0764222222
[clientFirstName] => us_first_name19085138
[clientLastName] => us_last_name19085138
[clientCity] => clientCity
[clientAddress] => address
[clientPostalCode] => 123123123
[clientCountryCode] => RU
[ccnumber] => 4149605380309302
[token] => 
[merchantFee] => 2
[desc] => Description
[timestamp] => 1378803851
[paymentChannel] => paymentChannel
[signature] => d78571cfaa6f35c8ccbf79a3a9035239

Поля сортируются, формируется базовая строка, к которой прибавляется секретный ключ (Secret_Key в примере).

204149605380309302addressclientCityUAspam19085138@devil.allegro.plus_first_name19085138us_last_name190851380764222222123123123UAHDescriptionPWA211117887paymentChannelsenderEmail@a.aasenderFirstNamesenderLastName07641111111378803851SECRET_KEY 

Применяется метод MD5 для формирования подписи:

d78571cfaa6f35c8ccbf79a3a9035239

Пример на PHP 

unset($params['signature']); 
ksort($params);                    
$builtSig = md5(implode($params) . $secretKey)

URL для запросов

Запросы выплаты

URL запроса выплаты

https://secure.payu.ru/order/prepaid/NewCardPayout

Регистрация карты

URL регистрации карты

https://secure.payu.ru/order/pwa/service.php/UTF/NewPayoutCard

 

Дополнительные материалы.

  1. Примеры на GitHub
  2. API для запрос баланса для выплат и статуса транзакции
  3. Пример страницы регистрации карты