Внимание! Если вы используете CMS систему или любые другие торговые платформы, рекомендуем ознакомиться с готовыми решениями в разделе виджеты и модули.
Об интерфейсе оплаты
Интерфейс Robokassa, предлагает перейти к оплате, нажав одну кнопку. Предварительно магазин должен сохранить у себя передаваемую информацию (номер счёта, сумма, дата формирования и дополнительные параметры, если они используются).
Покупатель отправляется для оплаты в платёжный интерфейс Robokassa, выбирает способ оплаты и совершает платёж. После чего средства перечисляются на Ваш баланс в системе Robokassa, а на указанный вами ResultURL мы пришлём уведомление об оплате.
URL для запросов HTTP GET/POST:
https://auth.robokassa.kz/Merchant/Index.aspx
Готовый виджет для оплаты на сайте
Вы можете выбрать готовый виджет и кастомизировать его под ваши нужды в конструкторе или в личном кабинете в разделе Платежный виджет
В конструкторе выберите нужный виджет способа перехода к оплате, отредактируйте его внешний вид, проставте сумму оплаты и при необходимости дополнительные поля. Затем сгенерируемый готовый код скопируйте к себе на сайт.
По каждому магазину передается три параметра:
• Кнопка перехода на оплату;
• Форма с произвольной суммой оплаты;
• Ссылка перехода на оплату;
• Оплата с помощью QR-кода;
Пример кода виджета, для самостоятельной установки
Приведённые примеры предполагает, что в технических настройках магазина выбран алгоритм расчёта хэша MD5.
1 2 3 4 5 6 7 8 9 10 11 12<?php$merchant_login = "demo";$password_1 = "password_1";$invid = 0;$description = "Техническая документация по ROBOKASSA";$out_sum = "8.96";$signature_value = md5("$merchant_login:$out_sum:$invid:$password_1");print "<html><script language=JavaScript "."src='https://auth.robokassa.kz/Merchant/PaymentForm/FormMS.js?"."MerchantLogin=$merchant_login&OutSum=$out_sum&InvoiceID=$invid"."&Description=$description&SignatureValue=$signature_value'></script></html>";?>
1
2
3
4
5
6
7
8
9
10
11
12
<?php
$merchant_login = "demo";
$password_1 = "password_1";
$invid = 0;
$description = "Техническая документация по ROBOKASSA";
$default_sum = "10";
$signature_value = md5("$merchant_login::$invid:$password_1");
print "<html><script language=JavaScript ".
"src='https://auth.robokassa.kz/Merchant/PaymentForm/FormFLS.js?".
"MerchantLogin=$merchant_login&DefaultSum=$default_sum&InvoiceID=$invid".
"&Description=$description&SignatureValue=$signature_value'></script></html>";
?>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<?php
// регистрационная информация (Идентификатор магазина, пароль №1)
// registration info (Merchant ID, password #1)
$merchant_login = "demo";
$password_1 = "password_1";
// номер заказа
// number of order
$invid = 12345;
// описание заказа
// order description
$description = "Техническая документация по ROBOKASSA";
// сумма заказа
// sum of order
$out_sum = "8.96";
// Товарная номенклатура (Receipt) в url encode
// Product Nomenclature (Receipt) in url encode
// Before url encode - {"items":[{"name":"product","quantity":1,"sum":1,"tax":"none"}]}
$receipt = "%7B%22items%22%3A%5B%7B%22name%22%3A%22product%22%2C%22quantity%22%3A1%2C%22sum%22%3A1%2C%22tax%22%3A%22none%22%7D%5D%7D";
// предлагаемая валюта платежа
// default payment e-currency
$incurrlabel = "BANKOCEAN2R";
// язык
// language
$culture = "ru";
// кодировка
// encoding
$encoding = "utf-8";
// Адрес электронной почты покупателя
// E-mail
$Email = "[email protected]";
// Срок действия счёта
// Expiration Date
$ExpirationDate = "2029-01-16T12:00";
// Дополнительные пользовательские параметры
// Shp_item
$Shp_item = "Shp_oplata=1";
// формирование подписи
// generate signature
$signature_value =md5("$merchant_login:$out_sum:$invid:$receipt:$password_1:Shp_item=$shp_item");
// форма оплаты товара
// payment form
print
"<html>".
"<form action='https://auth.robokassa.kz/Merchant/Index.aspx' method=POST>".
"<input type=hidden name=MerchantLogin value=$merchant_login>".
"<input type=hidden name=OutSum value=$out_sum>".
"<input type=hidden name=InvId value=$invid>".
"<input type=hidden name=Description value='$description'>".
"<input type=hidden name=SignatureValue value=$signature_value>".
"<input type=hidden name=Shp_item value='$shp_item'>".
"<input type=hidden name=IncCurrLabel value=$incurrlabel>".
"<input type=hidden name=Culture value=$culture>".
"<input type=hidden name=Email value=$Email>".
"<input type=hidden name=ExpirationDate value=$ExpirationDate>".
"<input type=hidden name=Receipt value=$receipt>".
"<input type=submit value='Оплатить'>".
"</form></html>";
?>
Описание параметров
Параметр
Значение
Идентификатор магазина
Пароль, который вы указали в Технических настройках.
Номер счета в магазине. Необязательный параметр, но мы настоятельно рекомендуем его использовать. Значение этого параметра должно быть уникальным для каждой оплаты. Может принимать значения от 1 до 2147483647 (2 - 1).
Описание покупки, можно использовать только символы английского или русского алфавита, цифры и знаки препинания. Максимальная длина — 100 символов.
Требуемая к получению сумма (буквально — стоимость заказа, сделанного клиентом). Формат представления — число, разделитель — точка, например: 123.45. Сумма должна быть указана в рублях.
Контрольная сумма — хэш, число в 16-ричной форме и любом регистре (0-9, A-F), рассчитанное методом указанным в Технических настройках магазина. Рассчитывается по базе, содержащей следующие параметры, разделенные символом : с добавлением Пароль#1
База для расчёта контрольной суммы:
MerchantLogin:OutSum:InvId:Пароль#1
Если Вы хотите передавать нам пользовательские параметры, например:
Shp_login=
Vasya
;
,
Shp_oplata=
1
, то база для расчёта контрольной суммы должна выглядеть так:
MerchantLogin:OutSum:InvId:Пароль#1:Shp_login=
Vasya:Shp_oplata=1
Результат применения кода
Создание ссылки без перенаправления на оплату (CURL)
Запрос
Адрес для отправки запроса:
POST https://auth.robokassa.kz/Merchant/Indexjson.aspx?
Параметры запроса:
Используется стандартный набор необходимых параметров в соответствии с разделом параметры скрипта
Пример запроса:
Ответ
В ответе возвращается json из которого нам потребуется идентификатор платежа (invoiceID):
После чего подставляем полученный invoiceID
к урлу платёжной страницы —
https://auth.robokassa.kz/Merchant/Index/41734593-dc97-dc5f-d329-a73158e4cb29
После получения идентификатора счёта клиент должен быть перенаправлен на оплату как можно быстрее.
Оплата по сохраненной карте
При таком способе Робокасса не будет предлагать ввод карты или выбор способа оплаты, но будет требовать ввода cvc2/cvv2.
Работает при использовании карты которая ранее уже применялась для попытки оплаты операции.
Для старта оплаты необходимо указать OpKey другой операции (не обязательно успешной) при которой уже использовалась карта. OpKey в данном случае будет являться токеном для карты.
Схема реализации:
• В адрес магазина проводится первая оплата;
• На Result2 приходит OpKey операции. Так же его можно получить используя метод OpStateExt ;
• Происходит новый вызов платежной страницы с использовнием токена OpKey;
Адрес для отправки запроса:
GET/POST
https://auth.robokassa.kz/Merchant/Payment/CoFPayment?
Описание
параметров Параметр Значение
OpKey операции, карту которой мы хотим использовать для новых оплат. Обязательный параметр.
Параметр Token
участвует в расчёте подписи SignatureValue
в следующей позиции:
Расчет подписи:
Пример запроса:
Пример расчета подписи:
Оповещение об оплате на ResultURL
ResultURL предназначен для получения Вашим сайтом оповещения об успешном платеже в автоматическом режиме. В случае успешного проведения оплаты Robokassa делает запрос на ResultURL (см. раздел Технические настройки). Данные всегда передаются в кодировке UTF-8.
Ваш скрипт, находящийся по ResultURL, обязан проверить равенство полученной контрольной суммы и контрольной суммы, рассчитанной Вашим скриптом по параметрам, полученным от Robokassa, а не по локальным данным магазина.
Если контрольные суммы совпали, то Ваш скрипт должен ответить Robokassa, чтобы мы поняли, что Ваш скрипт работает правильно и повторное уведомление с нашей стороны не требуется. Результат должен содержать текст OK и параметр InvId. Например, для номера счёта 5 должен быть вот такой ответ: OK5.
Если контрольные суммы не совпали, то полученное оповещение некорректно, и ситуация требует разбора магазином.
Если в настройках в качестве метода отсылки данных был выбран E-Mail, то в случае успешного проведения оплаты Robokassa отправит Вам письмо на электронный адрес, указанный в поле ResultURL, со всеми выше перечисленными параметрами.
Внимание!
В случае, если вы используете фильтрацию входящих запросов, не забудьте прописать IP-адреса Робокассы в white-лист вашего сервера 185.59.216.0/24 (185.59.216.1 - 185.59.216.254)
Описание параметров
Параметр
Значение
Сумма платежа.
Номер счета в магазине.
Комиссия Robokassa за совершение операции. Комиссия удерживается согласно тарифу клиента. Таким образом из суммы, оплаченной покупателем (параметр OutSum) вычитается комиссия Robokassa, и на расчетный счет поступит сумма OutSum минус Fee.
EMail, указанный покупателем в процессе оплаты.
Контрольная сумма — хэш, число в 16-ричной форме и в верхнем регистре (0-9, A-F), рассчитанное методом указанным в Технических настройках магазина.
База для расчёта контрольной суммы:
если вы не передавали пользовательские параметры OutSum:InvId:Пароль#2
если вы передавали пользовательские параметры OutSum:InvId:Пароль#2:[Пользовательские параметры]
Например, вы передали нам параметры со значениями:
то база для расчёта контрольной суммы будет выглядеть так:
100.26:450009
:Пароль#2:Shp_login=
Vasya
:Shp_oplata=
1
Способ оплаты который использовал пользователь при совершении платежа.
Валюта, которой платил клиент.
Пользовательские параметры, которые возвращаюся вам, если они были переданы при старте платежа.
Дополнительное оповещение об оплате на ResultUrl2
Дополнительное оповещение об успешной оплате позволяет получить уведомление на альтернативный адрес, отличный от указанного в настройках магазина(Result URL). Для операций с холдами на этот адрес направляется уведомление об успешной предавторизации, и это единственный способ его получить.
Для получения уведомления, необходимо добавить параметр ResultUrl2 к стандартному запросу на оплату, значение которого будет содержать закодированный в адрес в формате UrlEncode, на который вы хотите получить уведомление. По своему усмотрению в каждой новой оплате вы можете использовать новый адрес, так как значение ResultUrl2 не обязательно должно быть статичным.
Пример запроса:
В этом примере инициируется старт оплаты на сумму 10 рублей с последующей отправкой уведомления на адрес https://test.test/robokassa
Расчет подписи:
Параметр ResultURL2 участвует в расчёте подписи SignatureValue в следующей позиции:
Пример строки для расчёта хэша:
Получение уведомления
На адрес указанный в параметре ResultUrl2 отправляется уведомление в формате JWS(JSON Web Signature), которое закодированно в base64.
Пример запроса:
В декодированном виде:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15{"header": {"type": "PaymentStateNotification","version": "1.0.0","timestamp": "1691186412",},"data": {"shop": "robokassa","opKey": "14D2B521-4EAB-492A-9D91-00D12FF24D57-1NvHQWRwf","invId": "1234829","paymentMethod": "BankCard","incSum": "10.00","state": "OK",}}
В массиве data
содержится вся необходимая информация о платеже: идентификатор магазина,
номер заказа, метод
оплаты, сумма и статус операции.
Описание параметров
Параметр
Значение
Идентификатор магазина.
Уникальный идентификатор операции.
Номер счета в магазине.
Способ оплаты который использовал пользователь при совершении платежа.
Сумма оплаченная клиентом.
Текущее состояние оплаты.
Проверка подписи
Если вам требуется дополнительный уровень безопасности, вы можете осуществить проверку подписи JWS при получении уведомления. Для этого потребуется использовать соответствующий сертификат. Вы можете скачать его по этой ссылке. Пожалуйста, обратите внимание, что данная проверка не является обязательной, но может быть полезной для обеспечения дополнительной аутентификации и целостности получаемых данных.
Ожидаемый ответ
При успешной обработке, получатель должен вернуть HTTP-код из диапазона 200-299. Если сообщение не удалось доставить или полученный код не из диапазона 200-299, то попытка доставки будет повторяться, но не более пяти раз.
Переадресация при успешной оплате на SuccessURL
В случае успешного исполнения платежа Покупатель сможет перейти по адресу, указанному вами в Технических настройках, там же вы указали метод (GET или POST).
Переход пользователя по данному адресу с корректными параметрами (правильной Контрольной суммой) означает, что оплата вашего заказа успешно выполнена.
Однако для дополнительной защиты желательно, чтобы факт оплаты проверялся скриптом, исполняемым при переходе на SuccessURL, или путем запроса XML-интерфейса получения состояния оплаты счета, и только при реальном наличии счета с номером InvId в базе данных магазина.
На самом деле, переход пользователя по ссылке SuccessURL – это формальность, которая нужна только для того, чтобы пользователь вернулся обратно к Вам и получил информацию о том, что он сделал всё правильно, и его заказ ждёт его там-то и там-то. Проводить подтверждение оплаты у себя по базе и все остальные действия, связанные с выдачей покупки, Вам нужно при получении уведомления на ResultUrl, потому что именно на него Robokassa передаёт подтверждающие данные об оплате в автоматическом режиме (т. е. в любом случае и без участия пользователя).
Передаваемые параметры
Параметр
Значение
Сумма, оплаченная покупателем (та самая, которую вы прислали в Robokassa, на страницу оплаты).
Номер счета в магазине.
Контрольная сумма — хэш, число в 16-ричной форме и в верхнем регистре (0-9, A-F), рассчитанное методом указанным в Технических настройках магазина.
База для расчёта контрольной суммы:
если вы не передавали пользовательские параметры OutSum:InvId:Пароль#1
Если вы передавали пользовательские параметры OutSum:InvId:Пароль#1:Shp
Пример с передачей пользовательских параметров:
то база для расчёта контрольной суммы будет выглядеть так:
100.26:450009
:Пароль#1:Shp_login=
Vasya
:Shp_oplata=
1
Определяет на каком языке была страница оплаты Robokassa у пользователя. Если параметр не передан, то используются региональные настройки браузера покупателя. Для значений отличных от ru или en используется английский язык.
Возможные значения:
– Английский
– Русский
Пользовательские параметры, которые возвращаюся вам, если они были переданы при старте платежа.
Переадресация при отказе от оплаты на FailURL
В случае отказа от исполнения платежа покупатель перенаправляется по данному адресу. Необходим для того, чтобы продавец мог, например, разблокировать заказанный товар на складе.
Переход пользователя по данному адресу, строго говоря, не означает окончательного отказа покупателя от оплаты, нажав кнопку «Назад» в браузере он может вернуться на страницу оплаты Robokassa. Поэтому в случае блокировки товара на складе под заказ, для его разблокирования желательно проверять факт отказа от платежа запросом XML-интерфейса получения состояния оплаты счета, используя в запросе номер счета InvId имеющийся в базе данных магазина/продавца.
Передаваемые параметры
Параметр
Значение
Сумма, оплаченная покупателем (та самая, которую вы прислали в Robokassa, на страницу оплаты).
Номер счета в магазине.
Язык, использовавшийся при совершении оплаты. В соответствии с ISO 3166-1.
Дополнительные пользовательские параметры (если были переданы).
Типовые ошибки интерфейса оплаты
код ошибки
значение
Магазин не активирован. Ошибка возникает в двух случаях:
1) Магазин действительно еще не активирован, а вы пытаетесь выставлять счета в "боевом"
режиме
2) В технических настройках на вашем сайте вы некорректно указали Идентификатор
магазина. Найти его можно в разделе "Мои магазины" вашего личного кабинета, открыв
нужный магазин. В закладке "Технические настройки" будет поле "Идентификатор магазина".
Значение данного поля нужно скопировать и корректно прописать в настройках вашего сайта.
Магазин не найден. Ошибка возникает в том случае, когда в технических настройках на вашем сайте вы некорректно указали Идентификатор магазина. Найти его можно в разделе «Мои магазины» вашего личного кабинета, открыв нужный магазин. В закладке «Технические настройки» будет поле «Идентификатор магазина».
Неверный параметр SignatureValue. Проверьте скрипт, отвечающий за инициализацию оплаты, а именно ту часть, которая формирует SignatureValue по формуле, состоящей из переменных. Самые распространенные неточности, из-за которых может неверно считаться данный параметр:
– Используется некорректный Идентификатор магазина (MerchantLogin)
– Используется некорректный Пароль 1 (MerchantPass1)
– Используются дополнительные пользовательские параметры (shp_), которые были добавлены, но не занесены в формулу подсчета, или наоборот, в формуле подсчета они указаны, а в коде нет. Если shp_ используются, то они должны быть переданы в алфавитном порядке как в параметрах на оплату, так и в формуле подсчета SignatureValue.
Внимание!
Если вы используете тестовую среду Robokassa, передавая параметр IsTest=1 или включив его галочкой в настройках вашего модуля/бота, то необходимо использовать только тестовую пару технических паролей (см. закладку «Технические настройки» в карточке магазина).
Неверный параметр счёта. Проверьте правильность передаваемых как обязательных, так и необязательных параметров счета.
Неверная сумма платежа. Ошибка возникает по причине того, что при переадресации клиента на платежную страницу сервиса Robokassa для выставления счета, вы не передаете нам сумму, на которую необходимо исполнить платеж. Либо передаете сумму равную 0.
Время отведённое на оплату счёта истекло. Ошибка показывает, что время отведённое на проведение платежа этим способом истекло. Ознакомиться с имеющимися временными ограничениями по способам оплаты вы можете здесь.
Услуга рекуррентных платежей не разрешена магазину. Функция проведения рекуррентных платежей сначала должна быть согласована и подключена для вашего магазина нашими менеджерами. В противном случае платежи с подобной настройкой работать не будут.
Неверные параметры для инициализации рекуррентного платежа. Некорректные параметры указаны при инициализации рекуррентного платежа. Сверьтесь с соответствующим разделом нашей технической документации и проверьте настройки рекуррентных платежей у себя на сайте.
Повторная оплата счета с тем же номером невозможна. В момент формирования запроса на инициализацию оплаты вы передаете нам значение параметра InvId (номер заказа/счета), которое использовалось вами прежде. Этот параметр должен принимать с каждой переадресацией в сервис Robokassa уникальное значение. Ошибка показывает, что один из клиентов уже оплатил данный номер заказа ранее, а сейчас вы переадресуете к нам другого плательщика, выставляя ему тот же номер счета. Оплаты при включенном параметре IsTest=1 не логируются и не могут спровоцировать возникновение этой ошибки.
Ошибка на старте операции. При инициализации оплаты в системе произошла внештатная ошибка, вследствие которой платеж был отменен, не стартовав. Просьба инициировать оплату еще раз. При неудаче обратитесь в нашу поддержку.
Внутренние ошибки сервиса. В случае возникновения данных ошибок, просьба обратиться в поддержку нашего сервиса Robokassa через раздел «Поддержка» вашего личного кабинета.
Рекомендации для разработчиков приложений под iOS
При разработке мобильного приложения, которое будет использовать нашу платёжную форму через встроенный браузер, мы настоятельно рекомендуем использовать компонент WkWebView. Подробнее про него можно прочитать здесь
Важно Начиная с iOS 8.0 и OS X 10.10 используйте WkWebView для добавления веб-контента в ваше приложение. Не используйте UIWebView или WebView.
Если же, Вы планируете разработку с компонентом UIWebView, то работоспособность нашей платёжной формы в вашем мобильном приложении мы гарантировать не можем.