Created by Кристина Курашова, last modified by Дмитрий Марин on May 04, 2022

Пользователям предоставляется возможность пополнения счета с непосредственным вводом данных карты. Помимо этого доступен «ребилл» (повторное списание произвольной суммы заказа с уже известной карты без какого-либо дополнительного ввода данных пользователем).
Работа осуществляется с использованием протокола https, все параметры передаются на сервер процессинга в кодировке UTF-8.
Работа ведется асинхронно:

  1. с сервера ЛитРес запрашивается URL для https-запроса и параметры этого запроса;
  2. от пользователя получается вся необходимая информация (если это не «ребилл»);
  3. посылается https-запрос на сервер карточного процессинга. Процессинг проверяет корректность введенных данных и возвращает «ок» (что не означает списание средств, но только факт приема транзакции «в обработку»);
  4. приложение проверяет статус транзакции, периодически опрашивая сервер ЛитРес. Как правило, транзакция закрывается (либо мы получаем отказ) в течение 5-30 секунд;
  5. после получения ответа от сервера ЛитРес о статусе транзакции пользователь уведомляется о результатах операции. Если транзакция не была закрыта (статус все еще pending, см. r_check_order) в течение 5 минут, следует сообщить пользователю об ошибке.

В случае, если в ответе процессинга получен ErrorCode со значением «6001», то это означает, что плательщик должен пройти дополнительную 3DS-авторизацию на сайте банка-эмитента. Для этого необходимо перенаправить плательщика на сайт банка-эмитента, дождаться авторизации, а затем корректно завершить процесс списания средств на стороне мобильного приложения. Документацию по 3DS-авторизации, описывающую, куда именно необходимо перенаправлять пользователя и с какими параметрами, можно получить в поддержке платежной системы PayOnline (http://www.payonline.ru/feedback/) или в технической поддержке ЛитРес.

ID функции

w_creditcard_init

Кто может вызывать

Авторизованный пользователь.
Авторизованное приложение.

Принимаемые параметры

sum – сумма (по умолчанию в рублях, не менее 10), на которую необходимо пополнить счет и которая будет размещена на счёте пользователя ЛитРес. Если передана сумма с «длинными» копейками, например, sum=100.315345345345, то при выполнении запроса происходит округление суммы вверх, например, 100.315345345345 → 100.32 и 100.31411111111214 → 100.32;
currency – валюта суммы (необязательно). Если не указана и валюта face'а отличается от валюты платежной системы, сумма будет сконвертирована в валюту платженой системы, для Blik по умолчанию принимает значение 'PLN';
operation – тип операции:

  • auth – ручной ввод номера карты и других реквизитов, подразумевается по умолчанию;
  • rebill – можно указывать пользователю, у которого были успешные операции по карте и возможен «ребилл»;
  • bind - запускает процесс привязки карты пользователя с минимально возможной суммой в sum=1 рубль;

preventrebill – необязательный параметр. Если передать его со значением 1, то система не сохранит данные платежа для «ребилла»;
cardnum – необязательный параметр. Последние 4 цифры номера карты для «ребилла». Если параметр не передан, будет использована последняя в порядке использования карта (работает только для PayOnline);
rebill_id – необязательный параметр. ID «ребилла» из ответа на запрос r_get_rebills. Используется вместо параметра cardnum при оплате «ребиллом» посредством MAP или BLIK;
authorization_code – только для descr=100 (BLIK), код авторизации Blik (несовместим с rebill_id)
descr – необязательный параметр. Номер платежной системы, используемый для процессинга карты. Если не указан, то дефолт определяется серверной стороной, исходя из таблицы payments_visible. В обычном использовании и не должен указываться, указывается только для отладки различных процессингов в приложениях:

  • 32 – PayOnline;
  • 64 – DMR;
  • 68 – PaymentWall;
  • 73 – MAP;
  • 100 – Blik;
  • 104 – QiwiPay;

offer – номер «предложения», представленный в виде хэш-массива из двух целых чисел. Например:

"offer" : {
  "campaign" : "4",
  "class" : "1"
}

где:

  • campaign – номер кампании;
  • class – номер класса.

cset – custom_set – идентификатор набора книг, полученный с помощью  метода w_create_custom_set (в настоящее время поддерживается только для QiwiPay).

Возвращаемые значения

url – https адрес сервера, на который следует отправлять запрос. Приложение обязано проверить, что URL указывает именно на HTTPS ресурс. Для каждого обращения к оплате следует заново совершать этот запрос и заново получать URL;
method – метод запроса. Может принимать значения:

  • POST – на url надо отправить POST запрос;
  • GET – на url надо отправить GET запрос;
  • Redirect – необходимо перенаправить пользователя на url для проведения оплаты;
  • Async – url вообще нет в ответе. Необходимо получить статус платежа с помощью r_async_order_status, передав ему order_id из ответа;

name – имя кредитного процессинга. Можно продемонстрировать пользователю вместе с доменом из URL;
homepage – домашняя страница кредитного процессинга;
order_id – номер заказа, к которому будет привязана данная транзакция;
term_url – (параметр используется при 3DS-авторизации) – это URL страницы на сервере ЛитРес, которая умеет обрабатывать результат авторизации плательщика на сайте банка-эмитента и выдавать результат в виде веб-формы с «автосабмитом» на адрес платежной системы;
threedsdata – (параметр используется при 3DS v2.0-авторизации) – это мета юзер-агента для платежной системы;
notificationurl – (параметр используется при 3DS v2.0-авторизации) – это URL страницы на сервере ЛитРес, которая умеет обрабатывать результат авторизации плательщика на сайте банка-эмитента и выдавать результат в виде веб-формы с «автосабмитом» на адрес платежной системы;
params – массив параметров для трансляции на процессинг-сервер:

  • name – имя параметра, которое следует передать на сервер процессинга. Обязательный атрибут;
  • substitute – необязательный атрибут, указывающий, что данный параметр приложению следует заполнить самостоятельно, используя введенные пользователем данные. Если атрибута substitute нет, приложению следует транслировать значение параметра на сервер процессинга (т .е. даже пустой параметр следует передать как пустой, а не пропускать, остальные передать, при необходимости кодируя в UTF-8). При запросе типа операции rebill параметров с атрибутом substitute быть не должно. Приложение при этом просто транслирует запрос на процессинг-сервер. Может принимать следующие значения:
    • name – имя владельца карты в том виде, как оно написано на карте, например «vasily pupkin»;
    • number – номер кредитной карты, 13-19 цифр, без пробелов и тире;
    • expires – дата истечения срока действия карты. Строка в формате MMYY – две цифры месяца и две цифры года;
    • cvv – cvv-код карты (печатается на обратной стороне);
    • bank – наименование банка, выдавшего карту;
    • mail – e-mail пользователя карты, передаваемый в процессинговый центр;
    • phone – телефон пользователя карты;
    • country – страна плательщика, 2 символа из ISO-3166, например, RU.

Перечисленные выше параметры обязательно будут присутствовать, если тип операции был auth. Для rebill мы возвращаем только токен, а также всякие служебные параметры, типа количества, ip, валюты и т. д. При этом, если не осуществить их передачу на сервер процессинга, то это приведет к ошибке. Помимо этого существует несколько параметров, которые могут отсутствовать даже в параметрах запроса auth, а могут присутствовать, в зависимости от текущих настроек безопасности. Приложению следует запрашивать их у пользователя и передавать на сервер только в том случае, если они присутствовали среди узлов param. Если сервер ЛитРес эти поля не потребовал, приложение их может не запрашивать у пользователя и точно не должно передавать на сервер. Возможные необязательные параметры:

    • city – город плательщика. Строка, максимальная длина – 50 символов;
    • address – адрес плательщика. Длина – до 150 символов;
    • zip – почтовый индекс, только если указали регион – США;
    • state – штат, только если указали регион – США;
    • security_key – (параметр используется при 3DS-авторизации) – открытый ключ, подтверждающий целостность параметров запроса.

Диаграмма наличия полей в ответе в зависимости от платежной системы

Платежка \ Полеurlmethodnamehomepageorder_idterm_urlparams
32 Payonline+++++++
64 DMR-*++-+--
68 Paymentwall+++-+--
73 MAP-*++-+--
100 Blik----+--

* - в ответе url отсутствует, его надо получить с помощью r_async_order_status

Возможные ошибки

error_code

error_message

Описание

101005Method not allowed to userМетод доступен только авторизованным пользователям и приложениям
101019Invalid descrНомер платёжного сервиса «descr» не передан или не является числом

101123

Указана недопустимая сумма

Введена сумма, не удовлетворяющая условиям запроса

101126

Неверное значение «operation»

Указано недопустимое значение параметра «operation»

101127

Ошибка «rebill»

Не найден токен для проведения «ребилл» платежа

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

{
  "app": "4",
  "time": "2014-11-07T16:21:02+03:00",
  "sha": "b79d8e9993d20da6abe78838d3c7fbf640a4c52956569bef3c685d3453316b5c",
  "sid": "f121e02084344f06da1a5213999e8fcG",
  "requests": [
          {
                "func": "w_creditcard_init",
                "id": "creditcard_init",
                "param": {
                  "sum": "1000",
                  "operation": "auth"
                }
          }
  ]
}

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

{
  "success": true,
  "time": "2014-11-07T16:21:02+03:00",
  "mcommerce_init": {
    "success": true,
		{
  		 "catalit-paycard-processing": {
    		"url": "https://secure.payonlinesystem.com/payment/transaction/auth/",
    		"method": "POST",
    		"name": "PayOnline",
  		    "homepage": "http://www.payonlinesystem.com/",
			"terms_url": "http://robot.litres.ru/pages/catalit_credit_card_3ds_result/862703672/",
    		"params": [
     		  {"name":"merchant_id","value":"666"},
      		  {"name":"order_id","value":"555"},
      		  {"name":"amount","value":"100500"},
     		  {"name":"currency","value":"RUR"},
     		  {"name":"security_key","value":"1bc29b36f623ba82aaf6724fd3b16718"},
     		  {"name":"email","value":"","substitute":"mail"},
     		  {"name":"cardholdername","value":"","substitute":"name"},
     		  {"name":"cardnumber","value":"","substitute":"number"},
      		  {"name":"cardexpdate","value":"","substitute":"expires"},
     		  {"name":"cardcvv","value":"","substitute":"cvv"},
    		  {"name":"country","value":"","substitute":"country"},
    		  {"name":"city","value":"","substitute":"city"},
    		  {"name":"zip","value":"","substitute":"zipcode"},
    		  {"name":"address","value":"","substitute":"address"},
    		  {"name":"state","value":"","substitute":"state"},
     		  {"name":"phone","value":"","substitute":"phone"},
 		      {"name":"issuer","value":"","substitute":"issuer"}
    	    ]
         }
        }
  } 
}


Пример ответа сервера в случае QiwiPay

Нужно открыть открывается post-форму (url) с параметрами (post_params)  в web-view. После оплаты пользователь редиректится на success_url или decline_url, в котором задан параметром ?success.

Закрытие ордера (id) можно проверять методом [r_check_order])

{
   "success" : true,
   "time" : "2022-05-04T13:33:52+03:00",
   "creditcard_init" : {
      "descr" : "104",
      "id" : "1142780456",
      "method" : "AsyncRedirect",
      "post_params" : {
         "amount" : "123.00",
         "callback_url" : "https%3A%2F%2Fwww.fbhub.ru%2Fprocess_qiwi_pay%2F",
         "currency" : "643",
         "decline_url" : "http%3A%2F%2Fwww.fbhub.ru%2Fstatic%2Ferror_pages%2Fpayment_ok.html%3Forder%3D1142780456%26descr%3D104%26uilang%3Dru%26success%3D0",
         "email" : "ne%40dam1212.com",
         "merchant_site" : "2136051",
         "merchant_uid" : "1142779949",
         "opcode" : "1",
         "order_id" : "1142780456",
         "sign" : "FAE5BC63E30FEBBBFD9D000814EC90E972501876FE37BEF726C51813AAB50B1D",
         "success_url" : "http%3A%2F%2Fwww.fbhub.ru%2Fstatic%2Ferror_pages%2Fpayment_ok.html%3Forder%3D1142780456%26descr%3D104%26uilang%3Dru%26success%3D1"
      },
      "success" : true,
      "summ" : "123.00",
      "url" : "https://pay.qiwi.com/paypage/initial"
   }
}

Для примера выше форма должна запрашиваться по адресу: 

https://pay.qiwi.com/paypage/initial/?amount=123.00&callback_url=https%3A%2F%2Fwww.fbhub.ru%2Fprocess_qiwi_pay%2F&currency=643&decline_url=http%3A%2F%2Fwww.fbhub.ru%2Fstatic%2Ferror_pages%2Fpayment_ok.html%3Forder%3D1142780456%26descr%3D104%26uilang%3Dru%26success%3D0&email=ne%40dam1212.com&merchant_site=2136051&merchant_uid=1142779949&opcode=1&order-id=1142780451&sign=502CA1BA0A3F174EFD6E9A817A7B96D182055C038EB8831EDCCACB507B80C163&success_url=http%3A%2F%2Fwww.fbhub.ru%2Fstatic%2Ferror_pages%2Fpayment_ok.html%3Forder%3D1142780456%26descr%3D104%26uilang%3Dru%26success%3D1