1. Общие положения
После того как Ваше торговое предприятие (интернет-магазин) зарегистрировано в процессинге необходимо выбрать способ подключение и настроить взаимодействие вашего интернет-магазина с кассой. Помощь программиста для интеграции с Cash24 понадобится не всегда. Например, Вы можете формировать счета вручную и отправлять их на электронную почту клиенту из личного кабинета. Если Вам необходимо автоматизировать процесс оплаты заказа: выставлять счета клиентам для оплаты, получать автоматические уведомления об оплате, бронировать средства для будущей оплаты заказа на счете клиента, формировать отчеты по истории платежей в личном кабинете клиента на вашем сайте, а также, реализовать другие возможности процессинга, требуется работа программиста, который сможет настроить подключение интернет-магазина к процессингу с помощью внешнего API.
Инвойсинг
Такое взаимодействие интернет-магазина продавца с Cash24 не требует совсем какой-либо технической интеграции. Вы сможете использовать процессинг и выставлять электронные счета вашим клиентам сразу после регистрации аккаунта. Для этого зайдите в личный кабинет продавца, заполните форму счета и нажмите кнопку "Отправить". Ваш клиент получит электронный счет на e-mail и сможет оплатить счет любым удобным ему способом. О факте оплате счета Вы узнаете незамедлительно в личном кабинете. Подробнее о сервисе Инвойсинг
Готовые модули для систем управления сайтом (CMS)
На какой платформе сделан Ваш сайт? Скорее всего наши разработчики уже выполнили подключения Вашего интернет-магазина к Cash24! Загрузите готовое решение и настройте его для своей платформы управления сайтом, следуя шага за шагом по иллюстрированной инструкции. В настройках укажите регистрационные данные Вашего интернет-магазина, которые Вы получите при подключение: логин, пароль. Все! Ваш магазин настроен для приема платежей. Теперь, через корзину на Вашем сайте клиент сможет создать и оплатить заказ любым удобным ему способом. Заказ в системе управления Вашим сайтом автоматически меняет статус на Оплачен.
API + администратор интернет-магазина
Полуавтоматическое взаимодействие интернет-магазина с кассой. Для настройки такого взаимодействие требуется работа программиста. После настройки Ваш интернет-магазин "научится" выставлять счета в процессинг в автоматическом режиме. Покупатель в процессе оформления заявки нажмет кнопку "Оплатить" > перейдет на платежную страничку Cash24, где сможет оплатить заказ. На этом автоматическое взаимодействие с процессингом прекращается. Даже после уcпешной оплаты статус заказа в админке интернет-магазина не изменится на "Оплачен". Администратор или продавец интернет-магазина узнает об оплате заказа в личном кабинете на сайте процессинга и получит письмо на свой e-mail, о том что заказ был успешно оплачен. Недостаток очевиден! Администратор или продавец интернет-магазина "должен быть на чеку" для того чтобы оперативно обслужить клиента. Для тех продавцов чей бизнес не требует быстрой реакции на оплаченный клиентом заказ этого способа интеграции будет вполне достаточно. Например, существуют магазины, которым достаточно просматривать информацию об оплате заказов один раз в день.
API + автоматическое изменение статуса заказа в интернет-магазине
Полностью автоматическое взаимодействие интернет-магазина с процессингом. "Глубокая" интеграция программного обеспечения магазина с Cash24. Обычно, используется торговцами у которых уникальные системы управления продажами на сайте или торговцами которые хотят полной автоматизации процесса покупки. Имеется возможность реализовать сложные сценарии обслуживания клиентов. Для настройки такого взаимодействия требуется работа программиста. Безусловно, Вы получите ряд преимуществ, и главное, что заказ в админке Вашего интернет-магазина автоматически будет отмечен как оплаченный. Например, если у Вас интернет-магазин для продажи цифрового контента, Вы сможете настроить процесс таким образом, что сможете отправлять товар (работу, услугу) клиенту автоматически после успешной оплаты, без какого-либо вмешательства человека.
Кроме автоматического выставления счета в процессинг, на стороне интернет-магазина, необходимо настроить сервис, который в автоматическом режиме будет принимать уведомления от процессинга об изменение статуса заказа.
Выберите свой способ подключения:
|
Инвойсинг |
Готовые модули для систем управления сайтом (CMS) | API + администратор интернет-магазина |
API + автоматическое изменение статуса заказа в интернет-магазине |
| Работа в личном кабинете продавца на сайте Cash24. Для подключения не требуются какие-либо настройки и работа программистов по подключению. | Для подключения необходимо скачать готовый модуль и выполнить настройки в соответствие с инструкциями. Работа программиста не требуется. | Требуется работа программиста. | Требуется работа программиста. |
| Начинаете работать сразу после активации аккаунта - отправляете электронные счета клиентам на электронную почту из личного кабинета. | Требуется 10-60 минут для настройки модуля. | Требуется от 2 до 8 часов работы программиста. (Рекомендация: больше оплачивать не нужно, этого времени вполне достаточно для подключения). | Требуется от 4 до 8 часов работы программиста. (Рекомендация: больше оплачивать не нужно, этого времени вполне достаточно для подключения). |
| Используются минимальные возможности процессинга. | Возможности процессинга используются не полностью. | Возможности процессинга используются не полностью. | Могут быть задействованы любые сценарии работы с процессингом. Используются максимальные возможности процессинга. |
1.1. Фоновый и обычный режим работы
Взаимодействие предполагает два принципиально разных режима работы универсальной интернет-кассы Cash24: фоновый режим работы, при котором взаимодействие интернет-магазина с программно-аппаратным комплексом Cash24 (ПАК) происходит в невидимом для Плательщика режиме и обычный режим взаимодействия, при котором Плательщик перенаправляется на платежные страницы Cash24, где выбирает подходящий ему способ оплаты и производит другие действия нацеленные на оплату. В фоновом режиме Плательщик производит все действия на сайте Продавца, не подозревая о существование Cash24.
И в том и другом режиме Плательщик после оплаты или отмены счета должен иметь возможность вернуться на сайт магазина с сайта платежной системы. Для этого магазину необходимо подготовить две страницы, success и cancel. Возврат покупателя на сайт магазина осуществляется методом POST на страницы, указанные в параметрах запроса на создание счета: <success> и <cancel>. Список доступных параметров пост-запроса совпадает со списком параметров уведомления об изменении состояния счета.
Фоновый режим работы является более сложным с точки зрения реализации, как минимум потому, что требует от вебмастера самостоятельно реализовать бизнес-процессы взаимодействия с Плательщиком. Например, нужно создать форму для запроса у Плательщика платежных данных, форму с ожиданием оплаты, вывести на странице cancel текст с причиной отмены счета, пересоздать счет в случае отмены, для того, чтобы Плательщик смог оплатить его повторно или расформировать заказ в случае не успешной оплаты.
В обычном режиме работы вся логика взаимодействия с Плательщиком полностью реализована на стороне Cash24: Плательщик на сайте Cash24 видит более подробные описания причин ошибок при оплате, в любой момент может отказаться от оплаты или выбрать другой способ оплаты. Выставленный счет может иметь несколько попыток оплаты различными способами без создания нового счета.
| Фоновый режим | Обычный режим |
| Оплата происходит на сайте интернет-магазина, без перехода на сайт Cash24 | Оплата происходит на сайте Cash24 |
| Дизайн платежных страниц в стиле интернет-магазина | Дизайн платежных страниц Cash24 |
| Требуется больше времени вебмастера: страница для ввода платежных данных, страница ожидания оплаты, вывод причины отмены счета, возможны дополнительные бизнес-процессы, например пересоздание счета для заказа. | Все взаимодействие с Плательщиком происходит на сайте Cash24. Все необходимые страницы уже имеются. |
1.2. Цифровая подпись запросов
Взаимодействие между Магазином и Cash24, а также между Cash24 и Плательщиком осуществляется только по протоколу HTTPS для предотвращения перехвата и модификации трафика потенциальными злоумышленниками. Для предотвращения отправки запросов злоумышленниками от имени Магазина в Cash24 и наоборот все запросы подписываются. В запрос добавляется специальный параметр, представляющий хеш MD5 от значений других параметров запроса + секретный ключ, известный только администратору Магазина и Cash24. Зная ключ, можно рассчитать ожидаемое значение подписи и сравнить его с реально присланным в запросе. Если они совпадают - запрос пришел от доверенного адресата. В Cash24 мы используем 2 ключа: commandSecretKey для подписи команд (создание счета, отмена счета, завершение расчета и др.) и querySecretKey для подписи запроса Проверка состояния счета.
1.2.1. Пример вычисления подписи
Для операции Проверка состояния счета строка для подписи выглядит так:
get-invoice-{order}-{querySecretKey}, где order - это уникальный номер заказа, а querySecretKey - секретный ключ.
Предположим, их значения "123456789" и "super-puper-secret" соответственно. Тогда строка, от которой нужно считать подпись, выглядит так:
get-invoice-123456789-super-puper-secret
MD5 от нее равно "95BD2DC71E344A5456B78106EFB076A5". Это значение нужно записать в параметр envelope/sign запроса.
На C# код для вычисления подписи можно коротко записать так:
BitConverter.ToString(
MD5
.Create()
.ComputeHash(Encoding.UTF8.GetBytes(myStringToHash)))
.Replace("-", "")
.ToLower();
1.3. Схема взаимодействия
Для случаев базового взаимодействия с переходом Плательщика на сайт Cash24 для оплаты последовательность действий участников процесса можно пояснить на следующей диаграмме:
1. Процесс оплаты начинается с Плательщика. Плательщик на сайте интернет-магазина или другого сервиса, далее Магазин, формирует корзину покупок и нажимает кнопку "Оплатить";
2. Магазин формирует XML запрос на создание счета (create-invoice) на адрес https://api.cash24.ru/1.0/;
3. Cash24 проверяет корректность запроса, создает счет и оповещает об этом Магазин. В сообщение передается URL созданного счета;
4. Магазин перенаправляет Плательщика на страницу оплаты созданного счета;
5. На странице оплаты Плательщик видит параметры выставленного счет, выбирает подходящий ему способ оплаты и производит другие действия для оплаты счета;
6. Магазин получает от Cash24 уведомление об успешной оплате счета или ошибку оплаты;
7. После завершения процесса оплаты Cash24 отправляет Плательщика в Магазин на страницу отображающую состояние оплаты счета;
Действия 6 и 7 происходят параллельно. При возникновении проблем соединения между ПАК Cash24 и сервисом Магазина возможна ситуация, когда Плательщик вернется в Магазин до того, как Магазин узнает об оплате счета. В таком случае рекомендуется попросить Плательщика через несколько секунд обновить страницу, либо вызывать функцию проверки состояния счета до отображения страницы с состоянием оплаты Плательщику.
2. Базовые функции API
XML API системы предназначен для подключения сервисов Продавца к программно-аппаратному комплексу (ПАК) универсальной интернет-кассы Cash24 в целях автоматического взаимодействия сторон. Протокол позволяет выставлять в Cash24 счета к оплате, проверять состояния счетов, отправлять команды на возврат средств.
| URL для передачи запросов и команд | https://api.cash24.ru/1.0/ |
| Метод отправки запросов и команд | POST |
| Обязательный http-заголовок | Content-Type: text/xml |
| Протокол | HTTPS (SSL 128-бит) |
| Кодировка запросов | Только UTF-8. Должна быть корректно указана в параметрах запроса |
2.1. Создание счета (create-invoice)
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<request xmlns="http://api.cash24.ru/1.0/create-invoice/">
<amount>145.43</amount>
<currency>RUB</currency>
<email>client@mail.ru</email>
<description>За контекстную рекламу</description>
<order>154675-buy-12-01-2011</order>
<success>http://shop.ru/success.html</success>
<cancel>http://shop.ru/cancel.html</cancel>
<callback>http://shop.ru/interop/cb.html</callback>
<method>card-beeline</method>
<wallet>1231312</wallet>
<phone>79031234567</phone>
<expires>2013-05-01T07:34:42-5:00</expires>
</request>
<envelope>
<auth>C87B4A0C-7821-4F1B-84C6-C95D31B8E688</auth>
<sign>...</sign>
</envelope>
</cash24>
| Название | Назначение | Обязательный? | Примечание |
| amount | Сумма счета | Да | Положительное число, не более двух знаков после запятой, разделитель дробной части "." (точка), без разделителей тысяч. FormatProvider CultureInfo.InvariantCulture в случае программирования на .NET |
| currenсy |
Валюта счета | Да |
Валюта, в которой Продавец получает оплату за товары (работы, услуги). Буквенный код ISO 4217 |
| E-mail Плательщика | Да | Емейл на который Cash24 будет отправлять письма с информацией о состоянии счета |
|
| description |
Описание | Да | Описание назначения платежа в произвольной форме, до 500 символов. Этот текст будет показан Плательщику на странице оплаты на сайте Cash24 |
| order | Номер счета | Да | Уникальный в пределах магазина номер счета, не более 100 символов. Этот номер Cash24 будет передавать в коллбеках оповещающих магазин об изменении состояния счета. |
| success | Адрес страницы "Успешная оплата" | Да | URL на сайте Вашего магазина, куда будет перенаправлен Плательщик после успешной оплаты счета в Cash24 |
| cancel | Адрес страницы при отказе Плательщика от оплаты | Да | URL на сайте Вашего магазина, куда будет перенаправлен Плательщик в случае отказа от оплаты счета в Cash24 |
| callback | URL для отправки коллбеков | Да | URL на сайте Вашего магазина по которому Cash24 будет отправлять коллбеки об изменениях состояния счета |
| method | Способ платежа | Нет |
Способ оплаты счета. Продавец имеет возможность выбрать за Плательщика способ оплаты. Для этого, в этом поле, нужно передать параметр из справочника Параметры поля method * |
| wallet | Номер кошелька Плательщика | Нет |
Обрабатывается в том случае, если передан параметр method, в противном случае Cash24 вернет ошибку "10". см. Справочник с ошибками Для каждого способа платежа этот параметр необходимо передавать в определенном формате. Формат параметра определяется регулярным выражением в справочнике Параметры поля method |
| phone | Номер мобильного телефона Плательщика | Обязательный в некоторых случаях | Номер мобильного телефона Плательщика в международном формате. 11-15 цифр, возможен символ "+" впереди. ^\+?\d{11,15}$ |
| expires | Дата/время автоматической отмены счета | Нет | В формате вида 2013-05-01T07:34:42-5:00. Обратите внимание, что если не указана часовая зона (-5:00 в данном примере), то время считается UTC. Значение данного параметра должно быть не менее, чем на 5 минут больше текущего времени по Гринвичу (соответственно, нельзя указывать время в прошлом) |
| envelope/auth | Id магазина | Да | Уникальный параметр магазина продавца в Cash24. Выдается Продавцу при подключение к сервису |
| envelope/sign | Подпись запроса | Да | MD5 подпись запроса. Подписью запроса является HEX-строка для MD5 для набора байтов, представляющих следующую строку в UTF8 кодировке: create-invoice-{amount}-{currency}-{email}-{description}-{order}-{success}-{cancel}-{callback}-{method}-{wallet}-{commandSecretKey} ** |
* Этот функционал позволит Продавцу работать с Cash24 в фоновом режиме. В этом режиме Плательщик будет производить оплату на сайте Продавца без перехода на сайт Cash24. Также, с помощью этого параметра Продавец может разделить свои товары (работы, услуги) на группы и для каждой группы предопределить конкретный способ платежа. В таком случае, Покупатель, на сайте Cash24 не увидит страницу с выбором способа оплаты. Покупателю будет предложено оплатить счет способом, предопределенным Продавцом, например, банковской картой.
** commandSecretKey - секретный ключ для подписи команд. Выдается Продавцу при подключение к Cash24
2.1.1. Ответ
В случае успешного создания счета Cash24.ru возвращает ответ следующей структуры:
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<response xmlns="http://api.cash24.ru/1.0/create-invoice/">
<url>https://merchant.cash24.ru/5246093850/93idh3lxMdFQ9YtGAgbV9Q2</url>
<invoiceExpiresOn>30.01.2013 12:00:00</invoiceExpiresOn>
<redirectRequired>true</redirectRequired>
</response>
<envelope>
<error>0</error>
<text>Ok</text>
</envelope>
</cash24>
| Название | Назначение | Примечание |
| url | url созданного счета | Ссылка на страницу оплаты Cash24, на которую магазин должен отправить плательщика для оплаты счета |
| invoiceExpiresOn | Срок действия счета | UTC время в формате dd.MM.yyyy HH:mm:ss.fff . В это время счет будет автоматически отменен |
| redirectRequired | Требуется ли переадресация | Признак того, требуется ли переадресация Плательщика по переданному в ответе URL |
| error | Код ошибки | Значения параметра подробно описаны в Справочнике ошибок |
| text | Текст ошибки | Значения параметра подробно описаны в Справочнике ошибок |
2.2. Уведомление магазина о состояние счета
При изменении этапов обработки счета Cash24 посылает в магазин уведомления (коллбеки). Этапами обработки является переход счета по состояниям, указанным в Справочнике состояний счета. В каждом коллбеке содержится необходимая информация о текущем состоянии счета.
Cash24 отправляет уведомления на адрес callback указанный при создании счета. В целях безопасности мы рекомендуем всегда использовать https страницы для приема коллбеков.
Уведомления посылаются методом POST в виде стандартной формы (то есть в виде paramName1=value1¶mName2=value2&...).
Если уведомление не удается доставить в магазин (отсутствие соединения между серверами Cash24.ru и магазином, указан неверный адрес callback при создание счета, ошибка возвращаемая интернет-магазином и т.д.), Cash24 будет пытаться несколько раз повторно отправить коллбек с небольшими интервалами. Если все попытки закончатся неудачно, то магазин может узнать о состоянии счета принудительно, отправив команду Проверка состояния счета.
2.2.1. Параметры уведомления
| Название | Назначение | Примечание |
| amount | Сумма счета | Обычно используется для предотвращения потенциального мошенничества. Получив это уведомление, продавец должен сравнить сумму счета с суммой в запросе |
| status | Состояние счета | см. Справочник состояний счета |
| reason | Причина отмены/возврата | см. Справочник состояний счета |
| currency | Валюта счета | Буквенный код ISO 4217 |
| order | Номер счета | |
| url | URL для оплаты счета | Ссылка на мерчант cash24 |
| wallet | Кошелек/счет Плательщика | Кошелек/счет с которого был оплачен счет |
| method | Способ платежа | Способ платежа, которым был оплачен счет |
| reference | Идентификационный номер операции | Идентификационный номер операции в платежных системах |
| client-paid-amount |
Сумма заплаченная плательщиком | Сумма заплаченная плательщиком выбранным способом платежа. Это поле заполняется только в случае если счет оплачен. |
| status-changed-on |
Дата/время последнего изменения состояния счета | UTC время в формате dd.MM.yyyy HH:mm:ss.fff |
| invoiceExpiresOn | Срок действия счета | UTC время в формате dd.MM.yyyy HH:mm:ss.fff . В это время неоплаченный счет будет автоматически отменен. |
| available-for-refund | Сумма доступная для возврата | Если по счету были частичные возвраты, эта сумма будет рассчитана как Сумма счета - Сумма частичного возврата |
| refund-made-amount | Сумма на которую выполнены возвраты | Актуально для счетов, по котороым был возврат и ни как не используется для всех остальных случаев |
| salt | Salt | Уникальная строка для каждого callback |
| sign | Подпись уведомления | Служит для проверки отправителя |
2.2.2. Подпись уведомления
Подписью уведомления является HEX-строка для MD5 для набора байтов, представляющих следующую строку в UTF8 кодировке:
callback-{status}-{reason}-{amount}-{currency}-{order}-{url}-{wallet}-{method}-{available-for-refund}-{refund-made}-{salt}-{commandSecretKey} * детальный пример вычисления подписи
* commandSecretKey - ключ для подписи команд, указанный в настройках Вашего магазина в личном кабинете https://office.cash24.ru
2.3. Проверка состояния счета (get-invoice)
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<request xmlns="http://api.cash24.ru/1.0/get-invoice/">
<order>154675-buy-12-01-2011</order>
</request>
<envelope>
<auth>C87B4A0C-7821-4F1B-84C6-C95D31B8E688</auth>
<sign>...</sign>
</envelope>
</cash24>
| Название | Назначение | Обязательный? | Примечание |
| order | Номер счета | Да | Уникальный в пределах магазина номер счета, не более 100 символов. Это номер счета, который был передан в параметре order при Создании счета |
| envelope/auth | Id магазина | Да |
Идентификатор Вашего магазина. Уникальный параметр магазина продавца в Cash24, выдается Продавцу при подключение к сервису |
| envelope/sign | Подпись запроса | Да | MD5 подпись запроса. Подписью запроса является HEX-строка для MD5 для набора байтов, представляющих следующую строку в UTF8 кодировке: get-invoice-{order}-{querySecretKey}. см. Детальный пример вычисления подписи |
2.3.1. Ответ
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<response xmlns="http://api.cash24.ru/1.0/get-invoice/">
<status>20</status>
<reason>0</reason>
<amount>145.43</amount>
<currency>RUB</currency>
<order>154675-buy-12-01-2011</order>
<url>https://pay.cash24.ru/5246093850/</url>
<payment>
<method>card</method>
<clientPaidAmount>145.43</clientPaidAmount>
<wallet>4***********1234</wallet>
<reference>461351542</reference>
</payment>
<refund>
<available>105.43</available>
<made>40</made>
</refund>
</response>
<envelope>
<error>0</error>
<text>Ok</text>
</envelope>
</cash24>
| Название | Назначение | Примечание |
| amount | Сумма счета | Сравните сумму счета, которую вы передали в параметре amount с командой на создание счета с суммой в этом ответе |
| currency | Валюта счета | Сравните валюту счета, которую вы передали в параметре currency c командой на создание счета с значением валюты счета в этом ответе |
| status | Состояние счета | см. Справочник состояний счета |
| reason | Причина отмены/возврата | см. Справочник состояний счета |
| order | Номер счета | Уникальный в пределах магазина номер счета, не более 100 символов. Это номер счета, который был передан в параметре order при Создании счета |
| url |
URL для оплаты счета | Адрес страницы оплаты, на который магазин направляет плательщика для оплаты счета |
| payment/wallet | Кошелек/счет плательщика | |
| payment/method | Способ платежа | см. Таблицу с параметрами поля method |
| payment/reference | Reference Retrieval Number | Идентификационный номер операции в платежных системах. |
| payment/clientPaidAmount | Сумма с плательщика | Сумма заплаченная плательщиком выбранным способом платежа. Это поле заполняется только в случае если счет оплачен. |
| refund/available | Сумма доступная для возврата | |
| refund/made | Сумма на которую выполнены возвраты | |
| error | Код ошибки | Значения параметра подробно описаны в Справочнике ошибок |
| text | Текст ошибки | Значения параметра подробно описаны в Справочнике ошибок |
3. Дополнительные функции API
3.1. Двухстадийная авторизация платежа
Представленные в Cash24 способы оплаты можно условно подразделить три вида: платежи с двухстадийной авторизацией (банковские карты), с переходом Плательщика на страницу оплаты Платежной системы (Электронные деньги webmoney, яндекс деньги и т.д.), с выставлением счета на кошелек/счет Плательщика, без перехода на сайт Платежной системы (оплата в платежных терминалах, наличные в салонах связи, клиент-банк).
Платеж с двухстадийной авторизацией проходит через этап Холда, когда денежные средства на кошельке/счете Плательщика блокируются на сумму счета, а окончательный расчет происходит после списания. Это позволяет Продавцу реализовывать различные бизнес-процессы взаимодействия с Плательщиком. Показательным примером является сервис проката автомобилей, когда на счете Арендатора блокируется страховой депозит, а расчет происходит после возврата автомобиля Арендодателю. Страховой депозит может быть частично возвращен Арендатору, а расчет произведен на сумму остатка. Имеет смысл использовать Холд, когда Вы не уверены в том, что услуга будет оказана или товар будет куплен, например Покупатель заказал услугу и Вы заблокировали необходимые для оплаты средства на его карте. Если удалось оказать услугу Вы отправляете команду на Завершения расчета, не удалось - команду на Отмену Холда.
Возможность двухстадийной авторизации платежа активируется для Продавца индивидуально или включена в тарифный план обслуживания. Продавцу, для которого активирована двухстадийная авторизация доступны дополнительные команды XML API: Отмена Холда и Завершение расчета.
Важно понимать, что средства заблокированные на кошельке/счете Плательщика не учитываются на балансе Продавца, а отражаются на отдельном счете в личном кабинете Продавца. До тех пор, пока расчет по таким счетам не завершится денежные средства не будут перечислены в качестве выручки Продавцу. Расчет завершится автоматически по нормативам Cash24 через 5 календарных дней или раньше, если будет принудительно отправлена команда на Завершение расчета.
3.2. Отмена Холда (reversal)
Только для платежных систем с двухстадийной авторизацией платежа, например для банковских карт. Команда разблокирует зарезервированную на счете Плательщика сумму. Успешное выполнение данной операции НЕ означает, что деньги на счете плательщика были разблокированы (Холд отменен). Оно лишь означает, что Cash24 получил корректную заявку от магазина для отмены холда. О фактической отмене холда Cash24.ru уведомляет магазин с помощью колбеков, см. раздел Уведомление магазина о состояние счета.
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<request xmlns="http://api.cash24.ru/1.0/reversal/">
<order>154675-buy-12-01-2011</order>
</request>
<envelope>
<auth>C87B4A0C-7821-4F1B-84C6-C95D31B8E688</auth>
<sign>...</sign>
</envelope>
</cash24>
| Название | Назначение | Обязательный? | Примечание |
| order | Номер счета | Да | Уникальный в пределах магазина номер счета, не более 100 символов. Это номер счета который был передан в параметре order при Создании счета |
| envelope/auth | Id магазина | Да | Идентификатор Вашего магазина. Уникальный параметр магазина продавца в Cash24. Выдается Продавцу при подключение к сервису |
| envelope/sign | Подпись запроса | Да | MD5 подпись запроса. Подписью запроса является HEX-строка для MD5 для набора байтов, представляющих следующую строку в UTF8 кодировке: reversal-{order}-{commandSecretKey} см. Детальный пример вычисления подписи |
3.2.1. Ответ
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<envelope>
<error>0</error>
<text>all ok</text>
</envelope>
</cash24>
Значения параметров <error> и <text> подробно описаны в Справочнике ошибок
3.3. Завершение расчета (complete)
Только для платежных систем с двухстадийной авторизацией платежа, например, для банковских карт. Команда отправляет запрос в платежную систему на завершение расчета. Успешное выполнение данной операции НЕ означает, что расчет был завершен и средства были списаны со счета Плательщика. Оно лишь означает, что Cash24 принял команду завершить расчет. О фактическом списание средств на счете Плательщика Cash24.ru уведомляет магазин при помощью колбеков. В случае успешного списания средств Cash24 оповещает магазин статусом "Счет оплачен" (40). см. раздел Уведомление магазина о состояние счета.
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<request xmlns="http://api.cash24.ru/1.0/complete/">
<order>154675-buy-12-01-2011</order>
</request>
<envelope>
<auth>C87B4A0C-7821-4F1B-84C6-C95D31B8E688</auth>
<sign>...</sign>
</envelope>
</cash24>
| Название | Назначение | Обязательный? | Примечание |
| order | Номер счета | Да | Уникальный в пределах магазина номер счета, не более 100 символов. Это номер счета который был передан в параметре order при Создании счета |
| envelope/auth | Id магазина | Да | Идентификатор Вашего магазина. Уникальный параметр магазина продавца в Cash24. Выдается Продавцу при подключение к сервису |
| envelope/sign | Подпись запроса | Да | MD5 подпись запроса. Подписью запроса является HEX-строка для MD5 для набора байтов, представляющих следующую строку в UTF8 кодировке: complete-{order}-{commandSecretKey} см. Детальный пример вычисления подписи |
3.3.1. Ответ
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<envelope>
<error>0</error>
<text>Ok</text>
</envelope>
</cash24>
Значения параметров <error> и <text> подробно описаны в Справочнике ошибок
3.4. Возврат (refund)
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<request xmlns="http://api.cash24.ru/1.0/refund/">
<order>154675-buy-12-01-2011</order>
<amount>1003.23</amount>
</request>
<envelope>
<auth>13</auth>
<sign>...</sign>
</envelope>
</cash24>
| Название | Назначение | Обязательный? | Примечание |
| order | Номер счета | Да | Уникальный в пределах магазина номер счета, не более 100 символов. Это номер счета который был передан в параметре order при Создании счета |
| amount | Сумма возврата | Да | Сумма возврата. Не может быть больше суммы счета в случае полного возврата. Если по этому счету были частичные возвраты - не может превышать сумму остатка по счету, доступную для возврата |
| envelope/auth | Id магазина | Да | Идентификатор Вашего магазина. Уникальный параметр магазина продавца в Cash24. Выдается Продавцу при подключение к сервису |
| envelope/sign | Подпись запроса | Да | MD5 подпись запроса. Подписью запроса является HEX-строка для MD5 для набора байтов, представляющих следующую строку в UTF8 кодировке: refund-{order}-{amount}-{refundNumber}-{commandSecretKey} см. Детальный пример вычисления подписи |
3.4.1. Ответ
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<envelope>
<error>0</error>
<text>ok</text>
</envelope>
</cash24>
Значения параметров <error> и <text> подробно описаны в Справочнике ошибок
3.5. Проверка состояния магазина (get-shop-state)
Возвращается статус магазина в Cash24: зарегистрирован в системе, включен для приема платежей или отключен. В ответе, также, имеется информация о доступных для магазина способах платежей, их комиссии и другие параметры.
<?xml version="1.0" encoding="utf-8"?>
<cash24 xmlns="http://api.cash24.ru/1.0/">
<request xmlns="http://api.cash24.ru/1.0/get-shop-state/">
</request>
<envelope>
<auth>C87B4A0C-7821-4F1B-84C6-C95D31B8E688</auth>
<sign>...</sign>
</envelope>
</cash24>
| Название | Назначение | Обязательный? | Примечание |
| envelope/auth | Id магазина | Да | Идентификатор Вашего магазина. Уникальный параметр магазина продавца в Cash24. Выдается Продавцу при подключение к сервису |
| envelope/sign | Подпись запроса | Да | MD5 подпись запроса. Подписью запроса является HEX-строка для MD5 для набора байтов, представляющих следующую строку в UTF8 кодировке: get-shop-state-{querySecretKey} см. Детальный пример вычисления подписи |
3.5.1. Ответ
<cash24 xmlns="http://api.cash24.ru/1.0/">
<envelope>
<error>0</error>
<text>Ok</text>
</envelope>
<response xmlns="http://api.cash24.ru/1.0/get-shop-state/">
<name>Netexchange</name>
<url>Netexchange</url>
<active>true</active>
<canProcessInvoices>false</canProcessInvoices>
<twoStagesAuthorizationAvailable>false</twoStagesAuthorizationAvailable>
<currency>RUB</currency>
<paymentTypes>
<paymentType>
<method>wmr</method>
<isMerchantPaysFee>true</isMerchantPaysFee>
<feePercent>5</feePercent>
</paymentType>
<paymentType>
<method>card</method>
<isMerchantPaysFee>true</isMerchantPaysFee>
<feePercent>11</feePercent>
</paymentType>
</paymentTypes>
</response>
</cash24>
| Название | Назначение | Примечание |
| name | Название магазина | |
| url | Адрес магазина | |
| active | Статус магазина | true если магазин зарегистрирован и НЕ заблокирован в Cash24, false - магазин не найден или заблокирован |
| canProcessInvoices | Разрешено ли магазину создавать счета? | true - магазину разрешено создавать счета в Cash24, false - временная блокировка на создание счетов. Свяжитесь с Вашим менеджером |
| twoStagesAuthorizationAvailable | Доступна ли магазину 2-х стадийная авторизация платежей? | Возможность двухстадийной авторизации платежа активируется для Продавца индивидуально или включена в тарифный план обслуживания. Свяжитесь с вашим менеджеров для включения настройки |
| currency | Код валюты счета магазина | Валюта, в которой Продавец выставляет счета за товары (работы, услуги). Буквенный код ISO 4217 |
| paymentTypes | Способы платежа | Список способов платежей доступных магазину |
| paymentType/method | Код способа платежа | см. Таблицу с параметрами поля method |
| paymentType/isMerchantPaysFee | Кто оплачивает комиссию Cash24 | true, если комиссию платит Продавец, false - если Плательщик |
| paymentType/feePercent | Комиссия Cash24 | Значение комиссии с платежа в % |
| error | Код ошибки | Значения параметра подробно описаны в Справочнике ошибок |
| text | Текст ошибки | Значения параметра подробно описаны в Справочнике ошибок |
3.6. Справочник состояний счета
| Код статуса (status) | Описание | Примечание |
| 10 | Счет создан | |
| 20 | Выполнен Холд | Для платежных систем с двухстадийной авторизацией платежей, например, Банковские карты |
| 30 | Счет отменен | |
| 40 | Счет оплачен | |
| 50 | Выполнен возврат | Этот статус счет получает в случае успешной отмены Холда или при успешном завершение полного возврата. И то и другое означает, что деньги по счету были возвращены Плательщику в полном объеме |
| Код причины отмены счета или причины возврата по счету (reason) | Описание | Примечание |
| 0 | Не указано | |
| 10 | Плательщик отказался от оплаты | Намерено нажал кнопку "Отменить счет" |
| 20 | Вышло время на оплату счета | За отведенное время для оплаты счета Покупатель не произвел оплату и счет был отменен автоматически по таймауту |
| 30 | Невозможно выставить счет на указанный кошелек в платежной системе |
Платежная система не смогла выставить счет для оплаты, например, номер кошельк/счета Плательщика указан неверно |
| 40 | Ошибка при выставлении счета в платежную систему |
Платежная система не смогла выставить счет для оплаты, например, кошелек/счет заблокирован, Платежная система не отвечает и т.д. |
| 50 | Нарушены лимиты по выставлению счетов на указанный кошелек | Платежная система не смогла выставить счет для оплаты, например, для указанного кошелька/счета превышены лимиты |
| 60 | Отмена Холда | Для платежных систем с двухстадийной авторизацией платежа, например для банковских карт |
| 70 | Полный возврат | После списания средств был выполнены возвраты на всю сумму счета |
Reason код может быть использован Продавцом для отображения причины отмены счета, когда Продавец работает с Cash24 в фоновом режиме. В этом режиме Плательщик будет производить оплату на сайте Продавца или Платежной системы, т.е. без перехода на сайт Cash24. После отмены счета, по какой-либо причине, Плательщик будет перенаправлен на сайт Продавца. Используя эту информацию, Продавец на заранее подготовленной странице <cancel>http://shop.ru/cancel.html</cancel> сможет объяснить Плательщику причину отмены счета достаточно подробно.
3.7. Справочник ошибок
| Код ошибки | Описание | Примечание |
| 0 | Команда выполнена успешно, нет ошибки | |
| -100 | Ошибка разбора XML | |
| -200 | В одном запросе указано более 1 команды | |
| -1 | Магазин не найден или заблокирован. | Проверьте значение в поле envelope/auth. Если вы уверены, что оно корректное, значит магазин заблокирован! Свяжитесь с Вашим менеджером |
| -3 | Некорректная подпись запроса | Проверьте как вы формируете поле envelope/auth |
| -4 | У магазина не установлены ключи для подписи запросов или команд | Свяжитесь с Вашим менеджером |
| -5 | Некорректный идентификатор магазина | |
| -6 | Указано некорректное значение параметра method. | см. Таблицу с параметрами поля method |
| 2 | Некорректная сумма счета | Неправильная точность счета, формат записи числа или значение отрицательное |
| 3 | Ошибка в валюте счета | Валюта счета не указана или не совпадает с настройками магазина. Валюта счета устанавливается для магазина при подключение к Cash24. Свяжитесь с Вашим менеджером, чтобы изменить валюту счета |
| 4 | Email не указан или не верный формат поля | |
| 5 | Описание товара (работы, услуги) не указано или текст слишком длинный | |
| 6 | Не указан номер заказа в системе учета магазина, либо слишком длинный, либо заказ с таким номером уже был создан или не найден | |
| 7 | Для магазина не доступен ни один из способов платежа | Свяжитесь с Вашим менеджером |
| 8 | Магазину запрещено создавать счета | Свяжитесь с Вашим менеджером |
| 9 | Не установлен один из параметров URL (success/cancel/callback) | |
| 10 | Установлен параметр wallet, но не установлен параметр method | |
| 11 | Можно инициализировать возврат только для счета в статусе "Оплачен" (40) | cм. Справочник состояний счета |
| 12 | Некорректная сумма | Сумма, запрошенная к возврату, превышает максимально доступную сумму возврата для данного счета |
| 14 | Истек период для инициализации возврата по заданному счету | |
| 15 | По заданному счету существует не законченный возврат | Нельзя инициировать новый возврат пока не завершен предыдущий |
| 16 | Не корректный параметр поля wallet | Номер кошелька/счета передан в неверном формате. Не проходит проверку по маске в Cash24 или проверку в платежной системе. Формат параметра определяется регулярным выражением в справочнике Параметры поля method |
| 17 | Не корректный параметр поля expires | Значение для даты/времени автоматической отмены счета указано в неверном формате |
| 18 | Счет находится в состоянии отличном от Выполнен Холд (20) | Нельзя отправлять запрос на завершение расчета, если состояние счета отлично от Выполнен Холд (20). cм. Справочник состояний счета |
| 19 | Двухстадийная авторизация отключена | Возможность двухстадийной авторизации платежей отключена для Продавца или не разрешена для используемого тарифного плана. Свяжитесь с Вашим менеджером |
| 20 | Сумма счета не соотвествует лимитам выбранного способа платежа или для заданной суммы счета нет ни одного доступного способа платежа в магазине |
Указанная сумма счета превышает максимально возможную для любого из способов платежа доступных вашему магазину. Если способ платежа был указан в запросе на создание счета (параметр method) значит сумма счета превышает максимально допустимую именно для этого способа платежа |
| 21 | Некорректный номер мобильного телефона | Значение указано некорректно. Необходимо указать 11-15 цифр, возможен символ "+" впереди. ^\+?\d{11,15}$ |
| 22 | Не указан номер мобильного телефона Плательщика | Для выбранных настроек Продавца необходимо указать номер мобильного телефона Плательщика |
3.8. Параметры поля method
| Значение параметра | Описание | Поддерживает двухстадийную авторизацию? | Формат параметра method |
| card | Банковские карты Visa, MasterCard и др. | да | указывать wallet запрещено |
| card-beeline | Оплата со счета Билайн виртуальной картой Альфа банка | указывать wallet запрещено | |
| alfa-click | Оплата из интернет-банкинга Альфа-клик | да | 7 цифр, ^\d{7}$ |
| card-megafon | Оплата со счета Мегафон виртуальной картой | указывать wallet запрещено | |
| yandex | Яндекс деньги | начинается с 4100, дальше идёт 1 или 3, затем от 6 до 27 цифр. ^4100[13]\d{6,27}$ | |
| qiwi | Qiwi-кошелек | номер мобильного телефона. Начинается с +, и далее от 10ти до 14ти цифр. ^\+\d{10,14}$ | |
| wmr | WebMoney (Российский рубль) | начинается с R, затем 12 цифр | |
| wmz | WebMoney (Доллары США) | начинается с Z, затем 12 цифр | |
| wme | WebMoney (Евро) | начинается с E, затем 12 цифр | |
| wmu | WebMoney (Украинская гривна) | начинается с U, затем 12 цифр |
Хочу чтобы менеджер мне позвонил
Обратный звонок — это быстро и бесплатно!
