NAV Navbar

Введение

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

Что дальше:

  1. Подключите свое ПО к нашей демо-зоне
  2. Проведите несколько тестовых платежей
  3. Выводите свое ПО в боевой режим

Основные понятия

Мерчант - получатель платежа. Например, в схеме подключения “Оплата поездки на кошелек водителя” мерчантом будет выступать водитель.

Рекуррентный платеж - платеж, созданный по ранее сохраненным данным банковской карты.

Поставщик услуг (Принципал, ПУ, провайдер услуг) - юридическое лицо или индивидуальный предприниматель, получающие денежные средства Плательщика за реализуемые Поставщиком Услуги, а также органы государственной власти и местного самоуправления, бюджетные учреждения, получающие денежные средства Плательщика в рамках выполнения ими функций, установленных законодательством РФ.

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

Банк - эмитент - банк, выпускающий в обращение (эмитирующий) денежные знаки или ценные бумаги и платёжно-расчётные документы (банковские карты, чековые книжки). В нашем случае, говоря простыми словами, это банк, имеющий доступ к денежным средствам на счете клиента.

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

Интернет эквайринг - технология, позволяющая принимать к оплате банковские карты, виртуальные карты и электронные кошельки.

Агрегатор - компании, предоставляющие программное обеспечение Поставщикам Услуг. Фактически, интеграция происходит в программном обеспечении Агрегатора.

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

Процессинг - это деятельность по обработке информации, используемой при совершении платёжных операций. Такую деятельность осуществляют процессинговые центры.

ОП - отдел продаж

Магазин -

Процесс интеграции

Мы работаем по типу подключения host-to-host

Обмениваемся сообщениями в формате JSON

Protocol не ниже TLSv1.2

При подключении обязательно необходимо пользоваться клиентским сертификатом для подписи всех своих сообщений серверу. Сертификат мы выдаем по запросу

Тестовые параметры:

Тестовая карта - 4000000000000002 exp 01/21 cvv 123

Shop name - любой

shopToken - bb9f850d-86f7-4bd7-957c-282b79037c5d

secKey - 534a63d0-2acb-4273-b4d4-25536f578483

dn - /C=RU/ST=Permskiy kray/L=Perm/O=OOO Billing Systems/OU=BS_CA/CN=59-BS-TERM-Test_ShopApi-001

pass - e9shpkwgyc

servCode и тестовый сертификат мы отправим вам после того, как будет выбран тип магазина, который будем тестировать

Текущие тестовые услуги для поездок:

ServCode Код услуги Тип услуги
18191 1000-13864-5 Зачисление на кошелек с удержанием комиссии из тела платежа
17528 1000-13864-4 Зачисление на кошелек без комиссии
17527 1000-13864-3 Зачисление на кошелек с комиссией с клиента
17526 1000-13864-2 Зачисление на р/с без комиссии
17525 0-13864-1 Зачисление на р/с с комиссией с клиента

Боевые параметры

Теперь, чтоб перейти в боевой режим, необходимо создать боевой магазин

Для этого авторизуемся в личном кабинете

Платеж с 3ds

Некоторые рекуррентные платежи невозможны без данной технологии. При этом будет сгенерировано исключение NeedPass3dsException (смотри код 2365 в разделе Разбор ошибок), которое содержит номер платежа regPayNum и securePageURL (URL - тот, на который необходимо перенаправить пользователя для прохождения 3ds методом GET)

Ислючение может быть получено на этапе создания рекуррента (описан в разделе "создание платежа"), а так же на этапе проверки статуса платежа (описан в разделе "Получение статуса платежа")

Параметр enableSMSConfirm

Параметр fiscalType

Значение данной опции определяет нужно ли отправлять фискальный чек. Возможные значения:

а) email - отправить фискальный чек на почту

б) none (по умолчанию) - фискальный чек не нужен

Если значение fiscalType - email, то добавляется следующий параметр userEmail - e-mail для отправки фискального чека

Параметр payType

Создана для того, чтоб указать тип оплаты в запросах. Возможные значения поля:

Параметр orderBestBefore

Данным параметром можно передать время истечения жизни заказа (в секундах). Время, до которого нужно оплатить заказ.

Значение параметра - абсолютная дата UTC, в секундах (сформировать абсолютную дату). Например:

Формирование подписи

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

Допустим, у нас есть запрос создания платежа. По указанному алгоритму строка формирования будет выглядеть так: 
  md5(md5(serviceCode+'&'+userToken+'&'+amount+'&'+comission+'&'+cardToken+'&'+payType+'&'+clientType+'&'+properties[0].name+'&'+properties[0].value+'&'+...+properties[N].name+'&'+properties[N].value+'&'+shopToken'&'+shopSecKey).ToUPPER()).ToUPPER()

1) Cоставляем строку, состоящую из всех полей запроса и добавляем в конце shopSecKey
  X = 109-5804-1&USER_TOKEN&10000&13300&CARD_TOKEN&card&web&Л/СЧЕТ&9503006477&ФИО&Иванов Н П&АДРЕС&Ленина 10&МЕСЯЦ&05.2015&СУММА_ПЕНИ&10000&SHOP_TOKEN&SEC_KEY

2) Расчитываем md5 от полученной строки
  md5(X) = 95b3d1279d161e65cf55b368b7753ca4

3) Применяем функцию ToUpper - перевод в верхний регистр
  ToUpper(md5(X)) = ToUpper(95b3d1279d161e65cf55b368b7753ca4) = 95B3D1279D161E65CF55B368B7753CA4

4) Считаем md5 от полученного результата
  md5(ToUpper(md5(X))) = md5(95B3D1279D161E65CF55B368B7753CA4) = ab6291b7642b14885d1a3e40038c683f

5)Применяем функцию ToUpper к полученному результату
  ToUpper(md5(ToUpper(md5(X)))) = ToUpper(ab6291b7642b14885d1a3e40038c683f) = AB6291B7642B14885D1A3E40038C683F

Одной строкой:
md5(md5('109-5804-1'+'&'+'USER_TOKEN'+'&'+'10000'+'13300'+'&'+'CARD_TOKEN'+'&'+'card'+'&'+'web'+'&'+'Л/СЧЕТ'+'&'+'9503006477'+'&'+'ФИО'+'&'+'Иванов Н П'+'&'+'АДРЕС'+'&'+'Ленина 10'+'&'+'МЕСЯЦ'+'&'+'05.2015'+'&'+'СУММА_ПЕНИ'+'&'+'10000'+'&'+'SHOP_TOKEN'+'&'+'SEC_KEY'

В результате sign:"AB6291B7642B14885D1A3E40038C683F" 
Если вы используете готовую библиотеку для php, то не нужно самостоятельно формировать подпись. 
Этот алгоритм уже предусмотрен в библиотеке.  

Пример формирования подписи для запроса статуса платежа

Запрос:
  md5(md5(regPayNum+'&'+shopToken'&'+shopSecKey).ToUPPER()).ToUPPER()

Подставляем данные:
  md5(md5('1310958041'+&+'SHOP_TOKEN'+'&'+'SEC_KEY').ToUPPER()).ToUPPER()

В результате sign:"F6217B7EE96969ECCDA81ABBB973E8C6"

Ответ:
  md5(md5(state+'&'+totalAmount+'&'+createdDate+'&'+providerServCode+'&'+providerName+'&'+error+'&'+message+'&'+procDate+'&'+shopSecKey).ToUPPER()).ToUPPER()

Подставляем данные:
  md5(md5('payed'+'&'+100000+'&'+'2012-10-06 03:02:01'+'&'+'serviceCode'+'&'+'providerName'+'&'+'error'+'&'+'message'+'&'+'2015-01-05 12:14:18'+'&'+'SEC_KEY').ToUPPER()).ToUPPER()

В результате sign:"98CBD963E52F64A2736BF5055B2E5F9B"

Если вы используете готовую библиотеку для php, то не нужно самостоятельно формировать подпись. 
Этот алгоритм уже предусмотрен в библиотеке.  

Сформировать подпись отдельно: 

$shop->getSign([
    'phone' => '79129999999'
]);

Строка для вычисления подписи составляется из значений всех полей запроса/ответа (за исключением параметра sign)

Все значения полей разделяются символом &, в конце добавляется значение поля shopToken и shopSecKey

Если параметр отсутствует (значение null), то он не участвует в формировании подписи

Алгоритм формирования следующий:

  1. Рассчитываем MD5 SUM от полученной строки
  2. Приводим результат к верхнему регистру
  3. Снова рассчитываем MD5 SUM от полученной строки
  4. Снова приводим результат к верхнему регистру
  5. Готово! Вы восхитительны!

Статусы платежей

Платеж - последовательная сущность. Он линейно переходит из одного статуса в другой. Если что-то пошло не так, есть альтернативный набор статусов, сигнализирующий о неуспешности оплаты.

Cтатусы c неуспешным результатом (платеж не достиг состояния "оплачен"):

Получение статуса платежа

Пример запроса статуса платежа

{
  "sign":"F6217B7EE96969ECCDA81ABBB973E8C6",
  "shopToken":"SHOP_TOKEN",
  "regPayNum":"1310958041"
}

$payment = $shop->getPaymentInfo('13795357436');

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

{
  'sign':'633411CA7D9EDEF678423898C8E5F399',
  'errorCode':'1001',
  'provisionServices':'true',
  totalAmount':'100000',
  'serviceCode':'serviceCode',
  'providerName':'providerName',
  'state':'payed',
  'createdDate':'2012-10-06 03:02:01',
  'error':'error',
  'message':'message',
  'procDate':'2015-01-05 12:14:18'
}

  Array
(
    [sign] => 449440BD888AEBEA201B167DC083ACE7
    [state] => rejected
    [totalAmount] => 2000
    [createdDate] => 2019-06-19 14:25:39
    [providerServCode] => 100-13864-4
    [providerName] => Такси, Перевод банковской картой
    [errorCode] => 205
    [error] => Insufficient funds, acq:Not sufficient funds
    [message] => Недостаточно средств
    [provisionServices] => 
    [procDate] => 
)

Отправляется несколько попыток с нарастающим интервалом

Наш API позволяет отправлять повторные уведомления для одного платежа, в таких случаях ожидается успешный ответ

При оплате рекуррентом с обязательным вводом 3ds (раздел Рекуррент с 3ds ) в ответе будет получено исключение:NeedPass3dsException(смотри код 2365 в разделе Разбор ошибок)

Для прохождения 3ds проверки необходимо перенаправить пользователя по ссылке в параметре securePageURL методом GET

Параметры запроса

Обязательные Параметры ответа:

Необязательные параметры ответа:

Уведомление об оплате

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

{
"sign":"ХХХХХХХХ",
"shopToken":"SHOP_TOKEN",
"regPayNum":"1310958041",
"amount":"100000",
"comission":"1000",
"state":"payed"
}

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


Ожидается любой ответ со статусом "200"

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

При неуспешном создании платежа уведомление не отправляется

Параметры запроса:

Параметр Обязательный Описание
regPayNum + номер платежа в системе ckassa
amount + сумма платежа в копейках
comission + сумма комиссии в копейках
state + статус платежа. Подробнее
errorCode - код ошибки
errorMsg - текст ошибки
shopToken + идентификатор организации
sign + подпись

Поездка с оплатой на кошелек

В этом разделе мы рассмотрим поддерживаемые запросы, их назначение, параметры, а так же примеры их использования.

Начало работы

Создание объекта MerchantShop

Только для php
$shop = new MerchantShop(
    'Секретный ключ',
    'Токен магазина',
    'Путь до сертификата .pem',
    'Пароль от сертификата'
);

Создание объекта MerchantShop в тестовом режиме

Только для php
$shop = new TestMerchantShop(
    'Секретный ключ',
    'Токен магазина',
    'Путь до сертификата .pem',
    'Пароль от сертификата'
);

Поля, используемые для идентификации:

Алгоритм работы

Для понимания изобразим логику прохождения транзакции в данном магазине:

img_magazin_kosh

Регистрация мерчанта

Пример запроса регистрации мерчанта


  {
    "sign":"FB1A57BB4DBF026E24375723D0BFE61D",
    "phone":"79020000000",
    "email":"assa@mail.ru",
    "name":"Name",
    "surName":"SurName",
    "middleName":"MiddleName",
    "docList":[{"type":"passport","number":"453543543"},{"type":"inn","number":"1231231"}]
}
  $merchant = $shop->createMerchant([
    'phone' => '79129999999'
]);

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


 {
  "sign":"E547AC5283ABF43E7FC3F1169F8829C3",
  "state":"active",
  "phone":"79020000000",
  "merchantToken":"MERCHANT_TOKEN"
} 
Ckassa\Model\Merchant Object
(
    [phone:Ckassa\Model\Merchant:private] => 79129999999
    [merchantToken:Ckassa\Model\Merchant:private] => Токен
    [state:Ckassa\Model\Merchant:private] => active
)

Параметры запроса:

Параметр Обязательный Описание
Phone

+

номер телефона с кодом, но без '+'. Например: 79020000000
email - e-mail
Name - имя
surName - фамилия
middleName - отчество
callName - позывной
region - регион, либо город мерчанта
docList - список документов (используется для идентификации)
shopToken + идентификатор организации
sign + подпись

Если используется параметр docList, необходимо указать номера удостоверяющего документа (либо нескольких документов) в формате:

type - тип документа

Параметры ответа:

Параметр Обязательный Описание
merchantToken + идентификатор мерчанта
state + статус
phone + номер телефона
sign + подпись

Возможные значения поля state:

Статус мерчанта

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

{
  "sign":"2ADD30013A2E5DD4FF870EC2833564DF",
  "login":"79150000000",
  "shopToken":"SHOP_TOKEN"
}

$shop->loadMerchant('79129999999');

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

{
"sign":"E547AC5283ABF43E7FC3F1169F8829C3",
"state":"active",
"phone":"79020000000",
"merchantToken":"MERCHANT_TOKEN"
}
Ckassa\Model\Merchant Object
(
    [phone:Ckassa\Model\Merchant:private] => 79129999999
    [merchantToken:Ckassa\Model\Merchant:private] => Токен
    [state:Ckassa\Model\Merchant:private] => active
)

Если мерчант не зарегистрирован, то будет сгенерировано исключение MerchantNotRegisteredForShop (код 2709 в разделе Разбор ошибок)

Параметры запроса (все параметры обязательные):

Создание платежа в пользу мерчанта

Пример запроса на создание платежа в пользу мерчанта

{
  "sign":"FD3649DF9D4B71C828ACD4D7FB64BF07",
  "shopToken":"SHOP_TOKEN",
  "serviceCode":"SERVICE_CODE",
  "userToken":"USER_TOKEN",
  "amount":"100000",
  "comission":"2000",
  "orderId":"OrderId",
  "description":"Desc",
  "cardToken":"CARD_TOKEN",
  "merchantToken":"MERCHANT_TOKEN"
}

$payment = $shop->createPayment([
    'serviceCode' => '100-13864-4',
    'amount' => '2000',
    'comission' => 0,
    'orderId' => '006',
    'userToken' => $user->getUserToken(),
    'cardToken' => $card->getCardToken(),
    'merchantToken' => $merchant->getMerchantToken()
]);

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

{
  "sign":"63444480E68FAA4ABAAD18CA2EC06438",
  'regPayNum':'1234567890',
  'methodType':'GET',
  'payUrl':'https://autopays.ru/payment/#!receipt=12345',
  'merchantToken':'MERCHANT_TOKEN',
  'userToken':'USER_TOKEN',
  'shopToken':'SHOP_TOKEN'
}

  Ckassa\Model\Payment Object
(
    [regPayNum:Ckassa\Model\Payment:private] => 13795357436
    [methodType:Ckassa\Model\Payment:private] => GET
    [userToken:Ckassa\Model\Payment:private] => Токен пользователя
    [userPhone:Ckassa\Model\Payment:private] => 
    [payUrl:Ckassa\Model\Payment:private] => https://ckassa.ru/ticket/123
    [merchantToken:Ckassa\Model\Payment:private] => Токен мерчанта
)

В ответ на данный запрос приходит номер платежа, URL со ссылкой на чек и способ перехода

Параметр Обязательный Описание
serviceCode + код провайдера
amount + сумма платежа в копейках, которая идет на счет пользователю. Должна быть минимум 1 рубль (значение - 1000)
comission + комиссия платежа в копейках (при отсутствии комиссии передается 0)
orderId + уникальный номер заказа на стороне ПО заказчика (вас)
description - дополнительные сведения до 255 символов. Например: город и адрес заказа для идентификации в случае обращения клиента
userToken + идентификатор пользователя
cardToken - идентификатор карты
gPayToken - Токен при оплате через Google Pay. Более подробно в разделе Google Pay
enableSMSConfirm - см. раздел Параметр EnableSMScnfirm
merchantToken + идентификатор мерчанта
callName - позывной мерчанта (используется для дополнительной идентификации)
extraPhone - дополнительный телефон мерчанта (используется для дополнительной идентификации)
holdTtl - время заморозки средств (в секундах). Минимум 10 минут, максимум 4 дня, по умолчанию 30 минут. Если услуга не будет подтверждена, произойдет автоматический возврат средств на карту клиента.
payType - Тип оплаты
fiscalType - нужно ли отправлять фискальный чек. Cмотри раздел Функция fiscalType
shopToken + идентификатор организации
sign + подпись

Параметры ответа:

Параметр Обязательный Описание
userToken + идентификатор пользователя
merchantToken + идентификатор мерчанта
shopToken + идентификатор организации
regPayNum + номер платежа
methodType + метод перехода по url для просмотра чека (GET/POST)
payUrl + url на страницу с чеком
sign + подпись

Бронирование суммы

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

{
  "sign":"9A3A896E5C835559846B35645SE41F12",
  "shopToken":"SHOP_TOKEN",
  "serviceCode":"SERVICE_CODE",
  "userToken":"USER_TOKEN",
  "amount":"100000",
  "comission":"2000",
  "orderId":"OrderId",
  "description":"Desc",
  "cardToken":"CARD_TOKEN"
}


$payment = $shop->reservePayment([
    'serviceCode' => '100-13864-4',
    'amount' => '2000',
    'comission' => 0,
    'orderId' => '007',
    'userToken' => $user->getUserToken(),
    'cardToken' => $card->getCardToken()
]);

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

{
  "sign":"9A3A896E5C835559846B35645SE41F12",
  'regPayNum':'1234567890',
  'methodType':'GET',
  'payUrl':'https://autopays.ru/payment/#!receipt=12345',
  'userToken':'USER_TOKEN',
  'shopToken':'SHOP_TOKEN'
}

  Ckassa\Model\Payment Object
(
    [regPayNum:Ckassa\Model\Payment:private] => 63030826
    [methodType:Ckassa\Model\Payment:private] => GET
    [userToken:Ckassa\Model\Payment:private] => Токен пользователя
    [userPhone:Ckassa\Model\Payment:private] => 
    [payUrl:Ckassa\Model\Payment:private] => https://ckassa.ru/ticket/123
    [merchantToken:Ckassa\Model\Payment:private] => 
)

Этот запрос бронирует сумму на карте вашего клиента без установки конечного получателя. Удобно использовать, когда вы хотите исключить риски, связаные с тем, что заказ не может быть оплачен по причине недостатка средств на счете клиента и т.п.

Для того, чтобы платеж был проведен, необходимо задать получателя (мерчанта) и подтвердить оказание услуги.

В ответ на данный запрос приходит информация с номером платежа, url со ссылкой на чек и способ перехода (GET/POST)

Параметры запроса:

Параметр Обязательный Описание
serviceCode + код провайдера
amount + сумма платежа в копейках, которая идет на счет пользователю
comission + комиссия платежа в копейках (при отсутствии комиссии передается 0)
orderId + уникальный номер заказа на стороне магазина
description - дополнительные сведения (до 255 символов)
userToken + идентификатор пользователя
cardToken - идентификатор карты
gPayToken - токен при оплате через Google pay
enableSMSConfirm - смотри Параметр EnableSMScnfirm
holdTtl - Время в секундах от исполнения заморозки. Минимум 10 минут, максимум 4 дня, по умолчанию 30 минут. Если услуга не будет подтверждена в заданный период времени, автоматически произойдет возврат средств на карту клиента.
payType - смотри раздел Функция payType
userEmail - e-mail для отправки фискального чека
fiscalType + Нужно ли отправлять фискальный чек
shopToken + идентификатор организации
sign - подпись

Параметры ответа

Все параметры ответа являются обязательными.

Создание платежа в пользу мерчанта, оплата с баланса мобильного

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

{
  "sign":"9A3A896E5C835559846B35645SE41F12",
  "shopToken":"SHOP_TOKEN",
  "serviceCode":"SERVICE_CODE",
  "userToken":"USER_TOKEN",
  "amount":"100000",
  "comission":"2000",
  "orderId":"OrderId",
  "description":"Desc",
  "cardToken":"CARD_TOKEN"
}


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

{
  "sign":"9A3A896E5C835559846B35645SE41F12",
  'regPayNum':'1234567890',
  'methodType':'GET',
  'payUrl':'https://autopays.ru/payment/#!receipt=12345',
  'userToken':'USER_TOKEN',
  'shopToken':'SHOP_TOKEN'
}

В ответ на данный запрос приходит информация с номером платежа, url со ссылкой на чек и способ перехода (GET/POST)

Дополнительная комиссия оплачивается пользователем и зависит от оператора сотовой связи

Окончательная сумма платежа будет отправлена клиенту по СМС с запросом подтверждения

В данный момент поддерживаются операторы МТС, Мегафон и Теле2

Параметры запроса

Параметр Обязательный Описание
serviceCode + код провайдера
amount + сумма платежа в копейках, которая идет на счет пользователю
comission + комиссия платежа в копейках (при отсутствии комиссии передается 0)
orderId + уникальный номер заказа на стороне магазина
description - дополнительные сведения (до 255 символов)
userToken + идентификатор пользователя. Если клиент ранее был зарегистрирован, то оплата будет произведена с телефона указаного при регистрации (параметр login)
merchantToken + идентификатор мерчанта
userPhone * Номер телефона для СМС платежа, с которого будет произведена оплата
userEmail - e-mail для отправки фискального чека
fiscalType - нужно ли отправлять фискальный чек. Cмотри раздел Функция fiscalType
shopToken + идентификатор организации
sign + подпись

* - если клиент ранее был зарегистрирован ожидается userToken, иначе userPhone. Обязателен только один из параметров, отправка сразу двух параметров не допускается.

Параметры ответа

Параметр Обязательный Описание
userPhone * номер телефона пользователя
userToken * идентификатор пользователя
merchantToken + идентификатор мерчанта
shopToken + идентификатор организации
regPayNum + номер платежа
methodType + метод перехода по url для просмотра чека (GET/POST)
payUrl + url на страницу с чеком
sign + подпись

* - если клиент ранее был зарегистрирован ожидается userToken, иначе userPhone. Обязателен только один из параметров, отправка сразу двух параметров не допускается.

Получение баланса мерчанта

Пример запроса баланса мерчанта

{
  sign":"21C3B7EF125C0163B423CBE387D7AFD3",
  "merchantToken":"MERCHANT_TOKEN",
  "shopToken":"SHOP_TOKEN"
}

$shop->getBalance($merchant->getMerchantToken());

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

{
  "sign":"7CB4C5F56717FA770BED533734966E2D",
  "balance":"1000",
  "walletCode":"WALLET_CODE",
  "merchantToken":"MERCHANT_TOKEN"
}

Array
(
    [sign] => CCD24CA2B87C43D6B47BD71C54EEE795
    [balance] => 7728
    [walletCode] => 123
    [merchantToken] => Токен мерчанта
)

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

Обновление получателя забронированных средств

Пример запроса смены получателя

{
  "regPayNum":"REG_PAY_NUM"
  "merchantToken":"MERCHANT_TOKEN",
  "shopToken":"SHOP_TOKEN",
  "sign":"21C3B7EF125C0163B423CBE387D7AFD3"
}

$payment = $shop->updatePaymentMerchant([
    'regPayNum' => '63032713',
    'merchantToken' => $merchant->getMerchantToken()
]);

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

{
  "regPayNum":"REG_PAY_NUM"
  "merchantToken":"MERCHANT_TOKEN",
  "shopToken":"SHOP_TOKEN",
  "sign":"21C3B7EF125C0163B423CBE387D7AFD3"
}

Ckassa\Model\Payment Object
(
    [regPayNum:Ckassa\Model\Payment:private] => 63032713
    [methodType:Ckassa\Model\Payment:private] => 
    [userToken:Ckassa\Model\Payment:private] => 
    [userPhone:Ckassa\Model\Payment:private] => 
    [payUrl:Ckassa\Model\Payment:private] => 
    [merchantToken:Ckassa\Model\Payment:private] => d29c9e81-82dc-4938-b675-53c570e01c43
)

Параметры запроса

Параметр Обязательный Описание
regPayNum + номер платежа
merchantToken + идентификатор мерчанта
callName - позывной
extraPhone - дополнительный телефон мерчанта (используется для дополнительной идентификации)
shopToken + идентификатор организации
sign + подпись

Параметры ответа (все обязательные)

Подтверждение оказания услуги

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

{
  "sign":"FE4416FBCCA4E928704E0C158262B568",
  "regPayNum":"1234567890",
  "orderId":"12345",
  "shopToken":"SHOP_TOKEN"
}

Внимание! 
При передаче суммы платежа в данном случае вычитается комиссия. 
Например, при начальной сумме платежа 1100 коп. передается 1063 коп.

$shop->confirmPayment('63032713', '007', 1063)

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

{
  "sign":"XXXXX",
  "resultState":"success",
  "desc":"Success update provision services to refund. RegPayNum:1234567890",
  "shopToken":"SHOP_TOKEN"
}

Array
(
    [sign] => FAC65394830793598877E24FF3ED9A01
    [shopToken] => Токен магазина
    [resultState] => success
    [desc] => Success update provision services to confirm. RegPayNum:63032713
    [userToken] => 
)

Необходимость подтверждения оказания услуги определяется настройками терминала с нашей стороны по вашему запросу

Подтвердить можно только платеж в статусе "Оплачен". Узнать статус платежа можно по запросу Получение статуса платежа

После получения подтверждения оказания услуги ckassa переводит денежные средства на кошелек мерчанта. Это значит, что услуга считается выполненной и оплаченной

В случае ошибки достаточно повторить запрос

Параметры запроса:

Параметр Обязательный Описание
regPayNum + номер платежа
merchantToken + идентификатор мерчанта
callName - позывной
extraPhone - дополнительный телефон мерчанта (используется для дополнительной идентификации)
shopToken + идентификатор организации
sign + подпись

Параметры ответа:

Параметр Обязательный Описание
regPayNum + номер платежа
merchantToken + идентификатор мерчанта
shopToken + идентификатор организации
sign + подпись

Отмена замороженных/забронированных средств

Пример отмены замороженных средств

{
  "sign":"FE4416FBCCA4E928704E0C158262B568",
  "regPayNum":"1234567890",
  "orderId":"12345",
  "shopToken":"SHOP_TOKEN"
}

$shop->refundPayment('63032432', '007');

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

{
  "sign":"XXXXX",
  "resultState":"success",
  "desc":"Success update provision services to refund. RegPayNum:1234567890",
  "shopToken":"SHOP_TOKEN"
}

Array
(
    [sign] => 3B9BD5E643326BCD1196D8C205762D3E
    [shopToken] => Токен магазина
    [resultState] => success
    [desc] => Success update provision services to refund. RegPayNum:63032432
    [userToken] => 
)

Отменить заморозку и вернуть деньги на карту клиента можно только если платеж находится в статусе hold (в котором заморозка денежных среств на карте клиента осуществлена, но еще не подтверждено оказание услуги)

После отмены заморозки ckassa откатывает деньги обратно на карту клиента

В случае ошибки достаточно повторить запрос

Параметры запроса (все обязательные):

Параметры ответа (все обязательные):

Поездка с оплатой на расчетный счет

В этом разделе мы рассмотрим поддерживаемые запросы для данного типа магазина, их назначение, параметры, а так же примеры использования.

Алгоритм работы

Пример создания объекта MainShop

только для библиотеки php
$shop = new MainShop(
    'Секретный ключ',
    'Токен магазина',
    'Путь до сертификата .pem',
    'Пароль от сертификата'
);

Пример создания объекта MainShop в тестовом режиме

только для библиотеки php
$shop = new TestMainShop(
    'Секретный ключ',
    'Токен магазина',
    'Путь до сертификата .pem',
    'Пароль от сертификата'
);
img_alg_rc

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

Пример запроса на регистрацию карты

{
"sign":"F8C4A945567047ACB55FEC5D222D4786",
"shopToken":"SHOP_TOKEN",
"userToken":"USER_TOKEN",
"clientType":"web"
}

При регистрации карты возвращается объект класса Payment, 
поскольку регистрация по факту является списанием и возвратом денежных средств с карты (платежом).

$payment = $shop->createCard([
    'userToken' => $user->getUserToken()
]);

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

{
"sign":"C622C723C2A4266340E4E87AADD6B82D",
'regPayNum':'1234567890',
'methodType':'GET',
'payUrl':'https://autopays.ru/payment/#!search_payment',
'userToken':'USER_TOKEN',
'shopToken':'SHOP_TOKEN'
}

Ckassa\Model\Payment Object
(
    [regPayNum:Ckassa\Model\Payment:private] => 
    [methodType:Ckassa\Model\Payment:private] => GET
    [userToken:Ckassa\Model\Payment:private] => Токен пользователя
    [userPhone:Ckassa\Model\Payment:private] => 
    [payUrl:Ckassa\Model\Payment:private] => https://acq.bisys.ru/cardpay/card?order=123
    [merchantToken:Ckassa\Model\Payment:private] => 
)

Во время регистрации карты будет списано до 5 рублей, после добавления карты деньги будут возвращены

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

Для тестового соединения нужно использовать тестовую карту, см. пункт Тестовые, боевые данные

В ответ на запрос приходит номер платежа, url регистрации и способ перехода.

Параметры запроса:

Параметр Обязательный Описание
clientType - тип клиента*
userToken + идентификатор пользователя

Параметры ответа (все параметры обязательные):

Регистрация пользователя

Пример запроса на регистрацию пользователя

{
"sign":"4A7F7A58BBB46D9B128F7DC4E9215C2A",
"login":"Login",
"email":"Email",
"name":"Name",
"surName":"SurName",
"middleName":"MiddleName",
"shopToken":"SHOP_TOKEN"
}

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

{
"sign":"A97650D73FD1EF71FBA67F5BBD3ECAD8",
"state":"active",
"login":"getLogin()",
"email":"getEmail()",
"name":"getName()",
"surName":"getSurName()",
"middleName":"getMiddleName()",
"userToken":"USER_TOKEN"
}

Параметры запроса:

Параметр Обязательный Описание
login + номер телефона с кодом, но без '+', например - 79020000000.
email - e-mail (на него отправляются чеки после оплаты)
name - имя
surName - фамилия
middleName - отчество
state + статус*
shopToken + идентификатор организации
sign + подпись

Параметры ответа:

Параметр Обязательный Описание
login + номер телефона с кодом, но без '+', например - 79020000000.
email - e-mail (на него отправляются чеки после оплаты)
name - имя
surName - фамилия
middleName - отчество
state + статус. Более подробно - Статус пользователя
userToken + идентификатор пользователя
sign + подпись

Получение списка карт

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

{
"sign":"41C1EF2481885FEB0E510CE71F0CAD1B",
"userToken":"USER_TOKEN",
"shopToken":"SHOP_TOKEN"
}

$cards = $shop->getCardsList($user->getUserToken());

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

{
"sign":"SIGN",
"userToken":"USER_TOKEN",
"shopToken":"SHOP_TOKEN",
"cards":[{"cardMask":"546949******9929","cardToken":"77a3adeb-1f50-400a-88a9-7127dc9ea9f3","cardType":"master_card","state":"active"}]
}

[0] => Ckassa\Model\Card Object
    (
        [cardMask:Ckassa\Model\Card:private] => 510060******5227
        [exp:Ckassa\Model\Card:private] => 062023
        [cardToken:Ckassa\Model\Card:private] => Токен карты
        [cardType:Ckassa\Model\Card:private] => master_card
    )

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

Для того что бы карта появилась в списке нужно произвести регистрацию карты см. пункт Регистрация карты

Параметры запроса (все параметры обязательные):

Параметры ответа (все параметры обязательные):

Деактивация/удаление карты

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

{
"sign":"301032A23C66C3A6F9F403147DDFDF52",
"userToken":"USER_TOKEN",
"cardToken":"CARD_TOKEN",
"shopToken":"SHOP_TOKEN"
}

$shop->deactivateCard($user->getUserToken(), $card->getCardToken());

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

{
"sign":"05A2BE11C2A9F41854688848A279747A",
"resultState":"success",
"desc":"descSuccess",
"userToken":"USER_TOKEN",
"shopToken":"SHOP_TOKEN"
}

Array
(
    [sign] => 2F13A670CACBB246878D4F2B89D7EAF7
    [shopToken] => 27eb5388-d2c2-48ba-beea-48afd5e5b644
    [resultState] => success
    [desc] => Success deactivate card with token:b4b0492f-3d2a-468f-8b32-6a804cd9a55d
    [userToken] => 6183163f-13e9-4c06-b209-281c908a3a2d
)

После исполнения запроса состояние карты становится inactive и карта будет недоступна для оплаты (необходимо будет провести повторную привязку карты, см пункт Регистрация карты

Параметры запроса (все параметры обязательные):

Параметры ответа (все параметры обязательные):

Уведомление о регистрации карты

Пример запроса создания уведомления

{
"sign":"ХХХХХХХХ",
"shopToken":"SHOP_TOKEN",
"userToken":"USER_TOKEN",
"cardMask":"546949******9929",
"cardToken":"77a3adeb-1f50-400a-88a9-7127dc9ea9f3",
"cardType":"master_card"
}

Должно быть реализовано на стороне клиента самостоятельно. 
В данном случае наша платежная система сама шлет уведомления на адрес {cb url}/card-reg исходя из настроек магазина.

Параметры запроса:

Параметр Обязательный Описание
userToken + идентификатор пользователя
cardToken + токен карты
cardMask + маскированый номер карты
cardType + тип карты. Подробнее см. п. Получение списка карт
clientInfo - идентификатор клиента (задается при создании/регистрации карты)
shopToken + идентификатор организации
sign + подпись

В ответ ожидается любой ответ со статусом 200

Создание платежа

Пример запроса создания платежа

{
"sign":"AB6291B7642B14885D1A3E40038C683F"
"serviceCode":'111-13658-1',
"userToken":'a2ea360d-0af3-409f-87d0-4ea69ee077e6',
"amount":12000,
"comission":480,
"cardToken":'00d7ec3b-403f-416b-80d9-83461f684701',
"enableSMSConfirm":null,
"payType":null,
"clientType":null,
"userPhone":null,
"userEmail":null,
"fiscalType":null,
"holdTtl":null,
"orderBestBefore":"1575362617720",
"properties":
[Property{name='ПОЗЫВНОЙ, value='7757513'}, Property{name='ДОП_ИНФ', value='(1) предв 10 Сентября 01:35 Секрет магазин.. (2) Октябрьская 20. длина маршрута:4.0 км. '}], shopToken=cbc66478-b8a2-4906-8e97-bc0d6fab3792
}

$payment = $shop->createPayment([
    'serviceCode' => '979-13689-15',
    'userToken' => $user->getUserToken(),
    'cardToken' => $card->getCardToken(),
    'amount' => 1000,
    'comission' => 40,
    'enableSMSConfirm' => 'true',
    'properties' => [
        ['name' => 'НОМЕР_ТЕЛЕФОНА', 'value' => '9129999999']
    ]
]);

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

{
"sign":"C622C723C2A4266340E4E87AADD6B82D",
'regPayNum':'1234567890',
'methodType':'GET',
'payUrl':'https://autopays.ru/payment/#!search_payment',
'userToken':'USER_TOKEN',
'shopToken':'SHOP_TOKEN'
}

400. {"sign":"37735A107689316C80D1893F6F34552E","message":"For recurrent need pass 3ds","userMessage":"Необходимо ввести 3ds код","code":2365,"regPayNum":"13816644044","securePageURL":"https://acq.bisys.ru/cardpay/3ds?key=38290a0e-d407-456b-91cb-7a316f46123c"}

В ответ приходит номер платежа, url для оплаты и способ перехода.

При рекурентном платеже - url со ссылкой на чек.

Параметры запроса:

Параметр Обязательный Описание
serviceCode + код провайдера
userToken + идентификатор пользователя
amount + сумма платежа в копейках, которая идет на счет пользователю
comission + комиссия платежа в копейках (при отсутствии комиссии передается 0)
cardToken - идентификатор карты (для рекуррентного платежа), см. пункт Получение списка карт
gPayToken - Токен при оплате через Google Pay. Более подробно в разделе Google Pay
enableSMSConfirm - более подробно: EnableSMScnfirm
payType - способ оплаты подробнее в п. Параметр payType
clientType - более подробно в п. Создание анонимного платежа
userEmail * e-mail для фискального чека, подробнее: Параметр fiscalType
fiscalType * отправлять ли фискальный чек. Подробнее: Параметр fiscalType
holdTtl - время заморозки средств (в секундах). Минимум 10 минут, максимум 4 дня, по умолчанию 30 минут. Если услуга не будет подтверждена, произойдет автоматический возврат средств на карту клиента.
orderBestBefore - Время истечения срока жизни заказа в секундах. Подробнее
properties + массив реквизитов. Более подробно в п. Создание анонимного платежа
shopToken + идентификатор организации
sign + подпись

Параметры ответа (все параметры обязательные):

Подтверждение оказания услуги (заморозки)

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

{
  "sign":"FE4416FBCCA4E928704E0C158262B568",
  "regPayNum":"1234567890",
  "orderId":"12345",
  "shopToken":"SHOP_TOKEN"
}

Внимание! При передаче суммы платежа в данном случае вычитается комиссия. 
Например, при начальной сумме платежа 1100 копеек передается 1063 копеек.

$shop->confirmPayment('63032713', '007', 1063)

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

{
  "sign":"XXXXX",
  "resultState":"success",
  "desc":"Success update provision services to refund. RegPayNum:1234567890",
  "shopToken":"SHOP_TOKEN"
}

Array
(
    [sign] => FAC65394830793598877E24FF3ED9A01
    [shopToken] => Токен магазина
    [resultState] => success
    [desc] => Success update provision services to confirm. RegPayNum:63032713
    [userToken] => 
)

Необходимость подтверждения оказания услуги определяется настройками терминала с нашей стороны по вашему запросу

Подтвердить можно только платеж в статусе "Оплачен". Узнать статус платежа можно по запросу Получение статуса платежа

После получения подтверждения оказания услуги ckassa переводит денежные средства на кошелек мерчанта. Это значит, что услуга считается выполненной и оплаченной

В случае ошибки достаточно повторить запрос

Параметры запроса:

Параметр Обязательный Описание
regPayNum + номер платежа
merchantToken + идентификатор мерчанта
callName - позывной
extraPhone - дополнительный телефон мерчанта (используется для дополнительной идентификации)
shopToken + идентификатор организации
sign + подпись

Параметры ответа:

Параметр Обязательный Описание
regPayNum + номер платежа
merchantToken + идентификатор мерчанта
shopToken + идентификатор организации
sign + подпись

Отмена замороженных средств

Пример отмены замороженных средств

{
  "sign":"FE4416FBCCA4E928704E0C158262B568",
  "regPayNum":"1234567890",
  "orderId":"12345",
  "shopToken":"SHOP_TOKEN"
}

$shop->refundPayment('63032432', '007');

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

{
  "sign":"XXXXX",
  "resultState":"success",
  "desc":"Success update provision services to refund. RegPayNum:1234567890",
  "shopToken":"SHOP_TOKEN"
}

Array
(
    [sign] => 3B9BD5E643326BCD1196D8C205762D3E
    [shopToken] => Токен магазина
    [resultState] => success
    [desc] => Success update provision services to refund. RegPayNum:63032432
    [userToken] => 
)

Отменить заморозку и вернуть деньги на карту клиента можно только если платеж находится в статусе hold (в котором заморозка денежных среств на карте клиента осуществлена, но еще не подтверждено оказание услуги)

После отмены заморозки ckassa откатывает деньги обратно на карту клиента

В случае ошибки достаточно повторить запрос

Параметры запроса (все обязательные):

Параметры ответа (все обязательные):

Магазин. Анонимный платеж

Онлайн магазин, в котором принимается к оплате банковская карта.

Под "Анонимным" платежом предполагается платеж без сохраненных ранее данных по банковской карте.

Алгоритм работы

img_magaz_anon

Создание анонимного платежа

Пример запроса на создание анонимного платежа

{
  "sign":"71308F2268DB7F9A51ADD93E2CD57A76",
  "clientType":"web",
  "payType":"card",
  "shopToken":"SHOP_TOKEN",
  "properties":[{"name":"Л/СЧЕТ","value":"9503006477"},{"name":"ФИО","value":"Иванов НП"},{"name":"АДРЕС","value":"Ленина10"},{"name":"МЕСЯЦ","value":"05.2015"},{"name":"СУММА_ПЕНИ","value":"10000"}],"serviceCode":"109-5804-1","amount":"10000","comission":"13300"
}

$payment = $shop->createAnonymousPayment([
    'serviceCode' => '979-13689-15',
    'amount' => 1000,
    'comission' => 40,
    'enableSMSConfirm' => 'true',
    'properties' => [
        ['name' => 'НОМЕР_ТЕЛЕФОНА', 'value' => '9129999999']
    ]
]);

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

{
  "sign":"C622C723C2A4266340E4E87AADD6B82D",
  'regPayNum':'1234567890',
  'methodType':'GET',
  'payUrl':'https://autopays.ru/payment/#!search_payment','userToken':'USER_TOKEN','shopToken':'SHOP_TOKEN'
}

Ckassa\Model\Payment Object
(
    [regPayNum:Ckassa\Model\Payment:private] => 13816643359
    [methodType:Ckassa\Model\Payment:private] => GET
    [userToken:Ckassa\Model\Payment:private] => 
    [userPhone:Ckassa\Model\Payment:private] => 
    [payUrl:Ckassa\Model\Payment:private] => https://acq.bisys.ru/cardpay/card?order=61321205730300
    [merchantToken:Ckassa\Model\Payment:private] => 
)

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

В ответ приходит номер платежа, URL и способ перехода.

Параметры запроса:

Параметр Обязательный Описание
serviceCode + код провайдера
amount + сумма платежа в копейках (сумма которая идет на счет пользователю)
comission + комиссия платежа в копейках (если нет комиссии - передается 0)
cardToken - идентификатор карты (для рекуррентного платежа), см. пункт Получение списка карт
gPayToken - Токен при оплате через Google Pay. Более подробно в разделе Google Pay
payType - способ оплаты
clientType - тип клиента*
userPhone - Номер телефона пользователя(для СМС платежа), с которого будет произведена полата
userEmail - e-mail для отправки фискального чека
fiscalType - Описание Параметра
orderBestBefore - Время истечения срока жизни заказа в секундах. Подробнее
properties + массив реквизитов**
shopToken + идентификатор организации
sign + подпись

Параметры ответа (все обязательные):

Магазин. Рекуррентный платеж

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

Алгоритм работы

img_rek

Регистрация пользователя

Пример запроса на регистрацию пользователя

{
"sign":"4A7F7A58BBB46D9B128F7DC4E9215C2A",
"login":"Login",
"email":"Email",
"name":"Name",
"surName":"SurName",
"middleName":"MiddleName",
"shopToken":"SHOP_TOKEN"
}

При использовании метода возвращается объект класса User, свойства которого можно использовать в дальнейшем.

$user = $shop->createUser([
    'login' => '79129999999',
    'email' => 'test@test.ru',
    'name' => 'Тест',
    'surName' => 'Тестовый',
    'middleName' => 'Тестович'
]);

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

{
"sign":"A97650D73FD1EF71FBA67F5BBD3ECAD8",
"state":"active",
"login":"getLogin()",
"email":"getEmail()",
"name":"getName()",
"surName":"getSurName()",
"middleName":"getMiddleName()",
"userToken":"USER_TOKEN"
}

Ckassa\Model\User Object
(
    [login:Ckassa\Model\User:private] => 79129999999
    [email:Ckassa\Model\User:private] => test@test.ru
    [name:Ckassa\Model\User:private] => Тест
    [surName:Ckassa\Model\User:private] => Тестовый
    [middleName:Ckassa\Model\User:private] => Тестович
    [state:Ckassa\Model\User:private] => active
    [userToken:Ckassa\Model\User:private] => Токен пользователя
)

Параметры запроса:

Параметр Обязательный Описание
login + номер телефона с кодом, но без '+', например - 79020000000.
email - e-mail (на него отправляются чеки после оплаты)
name - имя
surName - фамилия
middleName - отчество
state + статус*
shopToken + идентификатор организации
sign + подпись

Параметры ответа:

Параметр Обязательный Описание
login + номер телефона с кодом, но без '+', например - 79020000000.
email - e-mail (на него отправляются чеки после оплаты)
name - имя
surName - фамилия
middleName - отчество
state + статус. Более подробно - Статус пользователя
userToken + идентификатор пользователя
sign + подпись

Статус пользователя

Пример запроса статуса пользователя

{
"sign":"2ADD30013A2E5DD4FF870EC2833564DF",
"login":"79150000000",
"shopToken":"SHOP_TOKEN"
}

$shop->loadUser('79129999999')
Так же, статус пользователя можно получить повторным запросом createUser
Если пользователь уже создан, то метод возвращает информацию о нем.

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

{
"sign":"A97650D73FD1EF71FBA67F5BBD3ECAD8",
"state":"active",
"login":"getLogin()",
"email":"getEmail()",
"name":"getName()",
"surName":"getSurName()",
"middleName":"getMiddleName()"
,"userToken":"USER_TOKEN"
}

Ckassa\Model\User Object
(
    [login:Ckassa\Model\User:private] => 79129999999
    [email:Ckassa\Model\User:private] => test@test.ru
    [name:Ckassa\Model\User:private] => Тест
    [surName:Ckassa\Model\User:private] => Тестовый
    [middleName:Ckassa\Model\User:private] => Тестович
    [state:Ckassa\Model\User:private] => active
    [userToken:Ckassa\Model\User:private] => Токен пользователя
)

Если пользователь не зарегистрирован, то будет сгенерировано исключение UserNotRegisteredForShop (см. Разбор ошибок)

Параметры запроса (все параметры обязательные):

Параметры ответа:

Параметр Обязательный Описание
login + номер телефона
email - e-mail
name - имя
surName - фамилия
middleName - отчество
state + статус*
userToken + идентификатор пользователя
sign + подпись

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

Пример запроса на регистрацию карты

{
"sign":"F8C4A945567047ACB55FEC5D222D4786",
"shopToken":"SHOP_TOKEN",
"userToken":"USER_TOKEN",
"clientType":"web"
}

$payment = $shop->createCard([
    'userToken' => $user->getUserToken()
]);

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

{
"sign":"C622C723C2A4266340E4E87AADD6B82D",
'regPayNum':'1234567890',
'methodType':'GET',
'payUrl':'https://autopays.ru/payment/#!search_payment',
'userToken':'USER_TOKEN',
'shopToken':'SHOP_TOKEN'
}

Ckassa\Model\Payment Object
(
    [regPayNum:Ckassa\Model\Payment:private] => 
    [methodType:Ckassa\Model\Payment:private] => GET
    [userToken:Ckassa\Model\Payment:private] => Токен пользователя
    [userPhone:Ckassa\Model\Payment:private] => 
    [payUrl:Ckassa\Model\Payment:private] => https://acq.bisys.ru/cardpay/card?order=123
    [merchantToken:Ckassa\Model\Payment:private] => 
)

Во время регистрации карты будет списано до 5 рублей, после добавления карты деньги будут возвращены

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

Для тестового соединения нужно использовать тестовую карту, см. пункт Тестовые, боевые данные

В ответ на запрос приходит номер платежа, url регистрации и способ перехода.

Параметры запроса:

Параметр Обязательный Описание
clientType - тип клиента*
userToken + идентификатор пользователя

Параметры ответа (все параметры обязательные):

Получение списка карт

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

{
"sign":"41C1EF2481885FEB0E510CE71F0CAD1B",
"userToken":"USER_TOKEN",
"shopToken":"SHOP_TOKEN"
}

$cards = $shop->getCardsList($user->getUserToken());

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

{
"sign":"SIGN",
"userToken":"USER_TOKEN",
"shopToken":"SHOP_TOKEN",
"cards":[{"cardMask":"546949******9929","cardToken":"77a3adeb-1f50-400a-88a9-7127dc9ea9f3","cardType":"master_card","state":"active"}]
}

[0] => Ckassa\Model\Card Object
    (
        [cardMask:Ckassa\Model\Card:private] => 510060******5227
        [exp:Ckassa\Model\Card:private] => 062023
        [cardToken:Ckassa\Model\Card:private] => Токен карты
        [cardType:Ckassa\Model\Card:private] => master_card
    )

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

Для того что бы карта появилась в списке нужно произвести регистрацию карты см. пункт Регистрация карты

Параметры запроса (все параметры обязательные):

Параметры ответа (все параметры обязательные):

Деактивация/удаление карты

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

{
"sign":"301032A23C66C3A6F9F403147DDFDF52",
"userToken":"USER_TOKEN",
"cardToken":"CARD_TOKEN",
"shopToken":"SHOP_TOKEN"
}

$shop->deactivateCard($user->getUserToken(), $card->getCardToken());

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

{
"sign":"05A2BE11C2A9F41854688848A279747A",
"resultState":"success",
"desc":"descSuccess",
"userToken":"USER_TOKEN",
"shopToken":"SHOP_TOKEN"
}

Array
(
    [sign] => 2F13A670CACBB246878D4F2B89D7EAF7
    [shopToken] => 27eb5388-d2c2-48ba-beea-48afd5e5b644
    [resultState] => success
    [desc] => Success deactivate card with token:b4b0492f-3d2a-468f-8b32-6a804cd9a55d
    [userToken] => 6183163f-13e9-4c06-b209-281c908a3a2d
)

После исполнения запроса состояние карты становится inactive и карта будет недоступна для оплаты (необходимо будет провести повторную привязку карты, см пункт Регистрация карты

Параметры запроса (все параметры обязательные):

Параметры ответа (все параметры обязательные):

Cоздание рекуррентного платежа

Пример запроса создания рекуррентного платежа

{
"sign":"AB6291B7642B14885D1A3E40038C683F",
"cardToken":"CARD_TOKEN",
"value":"10000",
"shopToken":"SHOP_TOKEN",
"clientType":"web",
"payType":"card",
"properties":[{"name":"Л/СЧЕТ","value":"9503006477"},
{"name":"ФИО","value":"Иванов Н П"},
{"name":"АДРЕС","value":"Ленина10"},
{"name":"МЕСЯЦ","value":"05.2015"},
{"name":"СУММА_ПЕНИ","value":"10000"}],
"serviceCode":"109-5804-1",
"userToken":"USER_TOKEN",
"amount":"10000",
"comission":"13300"
}

$payment = $shop->createPayment([
    'serviceCode' => '979-13689-15',
    'userToken' => $user->getUserToken(),
    'cardToken' => $card->getCardToken(),
    'amount' => 1000,
    'comission' => 40,
    'enableSMSConfirm' => 'true',
    'properties' => [
        ['name' => 'НОМЕР_ТЕЛЕФОНА', 'value' => '9129999999']
    ]
]);

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

{
"sign":"C622C723C2A4266340E4E87AADD6B82D",
'regPayNum':'1234567890',
'methodType':'GET',
'payUrl':'https://autopays.ru/payment/#!search_payment',
'userToken':'USER_TOKEN',
'shopToken':'SHOP_TOKEN'
}

400. {"sign":"37735A107689316C80D1893F6F34552E","message":"For recurrent need pass 3ds","userMessage":"Необходимо ввести 3ds код","code":2365,"regPayNum":"13816644044","securePageURL":"https://acq.bisys.ru/cardpay/3ds?key=38290a0e-d407-456b-91cb-7a316f46123c"}

В ответ приходит номер платежа, url для оплаты и способ перехода.

При рекурентном платеже - url со ссылкой на чек.

Параметры запроса:

Параметр Обязательный Описание
serviceCode + код провайдера
userToken + идентификатор пользователя
amount + сумма платежа в копейках, которая идет на счет пользователю
comission + комиссия платежа в копейках (при отсутствии комиссии передается 0)
cardToken - идентификатор карты (для рекуррентного платежа), см. пункт Получение списка карт
gPayToken - Токен при оплате через Google Pay. Более подробно в разделе Google Pay
enableSMSConfirm - более подробно: EnableSMScnfirm
payType - способ оплаты подробнее в п. Параметр payType
clientType - более подробно в п. Создание анонимного платежа
userEmail * e-mail для фискального чека, подробнее: Параметр fiscalType
fiscalType * отправлять ли фискальный чек. Подробнее: Параметр fiscalType
holdTtl - время заморозки средств (в секундах). Минимум 10 минут, максимум 4 дня, по умолчанию 30 минут. Если услуга не будет подтверждена, произойдет автоматический возврат средств на карту клиента.
orderBestBefore - Время истечения срока жизни заказа в секундах. Подробнее
properties + массив реквизитов. Более подробно в п. Создание анонимного платежа
shopToken + идентификатор организации
sign + подпись

Параметры ответа (все параметры обязательные):

Уведомление о регистрации карты

Пример запроса создания уведомления

{
"sign":"ХХХХХХХХ",
"shopToken":"SHOP_TOKEN",
"userToken":"USER_TOKEN",
"cardMask":"546949******9929",
"cardToken":"77a3adeb-1f50-400a-88a9-7127dc9ea9f3",
"cardType":"master_card"
}

Должно быть реализовано на стороне клиента самостоятельно. 
В данном случае наша платежная система сама шлет уведомления на адрес {cb url}/card-reg исходя из настроек магазина.

Параметры запроса:

Параметр Обязательный Описание
userToken + идентификатор пользователя
cardToken + токен карты
cardMask + маскированый номер карты
cardType + тип карты. Подробнее см. п. Получение списка карт
clientInfo - идентификатор клиента (задается при создании/регистрации карты)
shopToken + идентификатор организации
sign + подпись

В ответ ожидается любой ответ со статусом 200

Google Pay™

С помощью системы Google Pay™ вы сможете быстро принимать в своем приложении оплату от миллионов пользователей, которые сохранили данные банковских карт в своих аккаунтах Google.

Введение

Нажав на кнопку оплаты через Google Pay, пользователь переходит на страницу, где указаны способы оплаты и адреса доставки, сохраненные в его аккаунте Google. Здесь он может быстро выбрать нужную информацию или добавить новую.

Как это работает: оплата осуществляется из мобильного приложения с устройства пользователя. В сценарии приложение запрашивает зашифрованные данные у Google Pay. Эти данные необходимо передать в платежный шлюз: тоесть, нам.

Итак, вы приняли решение внедрить технологию Google Pay в ваше приложение. С чего начать?

Алгоритм работы

Пример инициализации структуры Подробнее

"type": "CARD",
  "parameters": {
    "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
    "allowedCardNetworks": ["MASTERCARD", "VISA"]

В настоящее время шлюз поддерживает платежные системы Visa и MasterCard, а так же обработку токенизированных и нетокенизированных карт (PAN_ONLY и CRYPTOGRAM_3DS).

Наш шлюз поддерживает возможность оплаты через Google Pay как в вашем android приложении, так и в вашем web-приложении (на сайте).

img_gpay

1. Пользователь в приложении выбирает тип оплаты Google Pay (привязывает карту, либо выбирает уже привязанную).

2. Приложение запрашивает у Google Pay данные карт, привязанных к Google в маскированном виде. Для того, чтоб приложение могло успешно общаться с системой Google Pay не нужно к ним интегрироваться, достаточно знать несколько параметров. Мы рассмотрим их ниже.

3. Google Pay возвращает в приложение данные карт (привязанных к Google) в маскированном виде.

4. Приложение показывает пользователю данные его карт/карты (привязанной к Google) в маскированном виде.

5. Пользователь подтверждает оплату (выбирает карту, либо другой способ оплаты).

6. Приложение запрашивает у Google Pay карточные данные в зашифрованном виде.

7. Google Pay шифрует данные, используя открытый ключ - соответствующий ему закрытый ключ расположен в платёжном шлюзе. То есть, собирает некую посылку в виде криптограммы.

Пример криптограммы от Google Pay

{"signature":"MEYCIQDzIjWGqr1teZiawa3HJ9IgJ/j4ZJnHkgIXzJv1pD1MIQIhAMWLvRlTZjdVCJBHO6/Jo+wuIudYqlrIxKU3nJdcU9XW","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"s3w41rMoVYpgOaWGWF8Sk6WAxxbDCPkepD94OIPTt4BMCJYTFMkM34KG60ONbu1bQkSfibSveqTtP0+bnXNcF2N50ZT+QTJ4rt7411nyXmWlsqHVGTHCI7RT02Q45l9NM33BIA8zuqAigqhPd91a3x1b0ZrBZW7xBOPf8Vzh5sokepySQRLIWwN/F40aO3DC3AP+wt8FT+ly4M3C7srDZAJT4/pbE4Qyr9ftvdqFze2fRJmPv0Uc1m8C+4AZHYwZSY8jCMlhdsEECR1pHdaXqpiTNDutY9Qw0ESQq63zMqPsfpDLo15bl4l52zkqtC7bxPfI31CaB0dmV+Et8rw6TYVa0+8DvvYAEWoHU1aZAXQd2amI7rGdJ3p6KO8IaL5QwwtFk5byjvxrsjN1Nq9EQJnzCVfE5/P7PdGVB3LLLTLmc5xJJH89CYuu6er4erVcfw\\u003d\\u003d\",\"ephemeralPublicKey\":\"BGLg5omp43/eI6V43NvI1FEF2TpTnz/S9T4hByZ3Oa726uLc3BTVzOpcUefzBDL5gePdvRqQTrL3U0vV4JRHFhU\\u003d\",\"tag\":\"x1hLpFnhsB2tSUO4CMAWCbZgvClC3ieIKkjRtCSQV1Q\\u003d\"}"}

8. Google возвращает в приложение зашифрованные данные о платеже (криптограмму).

9. Приложение отправляет в нашу платежную систему запрос на оплату, указывая полученный ранее Google Pay Token.

10. Наша платежная система собирает данные о платеже и отправляет платеж в эквайринг.

11. Эквайринг проводит платеж в обычном режиме (методами того типа магазина, который вы выбрали).

12. Информация о статусе платежа отправляется на Backend приложения.

В мобильном приложении

Пример выбора способа токенизации (из документации Google Pay API)

  private static JSONObject getGatewayTokenizationSpecification() throws JSONException {
    return new JSONObject(){{
      put("type", "PAYMENT_GATEWAY");
      put("parameters", new JSONObject(){{
        put("gateway", "billingsystems");
        put("gatewayMerchantId", "shopToken");
        }
      });
    }};
  }

Если с какими-то параметрами, запросами у вас возникли проблемы и ошибки, то обязательно загляните в раздел Устранение неполадок. Ведь с большинством проблем уже столкнулись, решили и описали их решение.

На сайте

Пример выбора способа токенизации (из документации Google Pay API для сайта)

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'billingsystems',
    'gatewayMerchantId': 'shopToken'
  }
};

Если с какими-то параметрами, запросами у вас возникли проблемы и ошибки, то обязательно загляните в раздел Устранение неполадок. Ведь с большинством проблем уже столкнулись, решили и описали их решение.

Встраиваемые модули

Вы всегда можете встроить в ваш сайт, либо личный кабинет один из наших модулей, не затрачивая на разработку свое драгоценное время!

Просто вставьте код, сгеренированный в нашем конструкторе и настройте ссылку для редиректа по своим нуждам.

Ниже мы рассмотрим подробнее настраиваемые параметры для кнопки и фрейма.

Кнопка оплаты

Если вам необходимо настроить только редирект на нашу форму оплаты с предзаполненным кодом услуги, введите интересующий вас код услуги в конструкторе помимо всего прочего.

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

Переходим на наш сайт

В строке поиска вводим код услуги вашей организации:

knopka_1

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

knopka_2

Теперь в шапке страницы нажимаем на "поиск":

knopka_3

В меню браузера нажимаем кнопку "назад":

knopka_4

Примеры получившихся ссылок

Ссылка на оплату с установелнным кодом услуги: 
https://ckassa.ru/payment/#!search_provider/pt_search/ПЕРСОНАЛЬНЫЙ_КОД_УСЛУГИ/pay
Ссылка с предустановленными суммой и л/с:
https://ckassa.ru/payment/#!search_provider/pt_search/979-13689-15/pay&amount=10000&НОМЕР_ТЕЛЕФОНА=7777777777

Копируем получившуюся ссылку из адресной строки:

knopka_5

Ссылка попадет в буфер обмена в закодированном виде. Раскодировать ее можно этим сервисом, либо любым другим

В результате вы получили ссылку с предзаполненной услугой, номером лицевого счета и суммой

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

Ссылку можно передать клиенту/водителю/курьеру напрямую, либо через QR код

Выбираем любую услугу и заполняем все нужные нам поля, например:

screen_001

Нажимаем оплатить мобильным приложением

Наша система проверит реквизиты платежа, сгеренирует короткую ссылку на оплату и QR-код:

screen_002

Оригинальная ссылка содержит в себе все необходимые параметры платежа. Она подставляется при переходе по коротой ссылке

Полученный QR код можно распечатать/сканировать/передать любым другим способом любому человеку для оплаты

QR на оплату через API

Пример запроса создания уведомления

https://oapi.ckassa.ru/api-shop/rs/pay-url/create-qr-img?service-code=979-13689-20&amount=10000&property=НОМЕР_ТЕЛЕФОНА|9659657777

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






QR code



QR

Данный метод позволяет сгенерировать QR код на оплату услуги с предустановленными параметрами

Метод работает в следующих типах магазинов: Магазин. Поездка с оплатой на р/с, Магазин. Анонимный платеж, Магазин. Рекуррентрый платеж

Параметры запроса(все параметры обязательные):

В ответ придет картинка с QR кодом в html и короткая ссылка на оплату

Пример запроса создания уведомления

https://oapi.ckassa.ru/api-shop/rs/pay-url/create-qr?service-code=979-13689-20&amount=10000&property=НОМЕР_ТЕЛЕФОНА|9659657777

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

https://bc.ckassa.ru/ys6o71

В нашем API есть специальный метод, позволяющий сгенерировать короткую ссылку на оплату

Метод работает в следующих типах магазинов: Магазин. Поездка с оплатой на р/с, Магазин. Анонимный платеж, Магазин. Рекуррентрый платеж

Параметры запроса(все параметры обязательные):

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

Фрейм

Пример фрейма

Без предустановленных значений, без шапки, способ оплаты - банковская крта, все способы оплаты открыты
https://ckassa.ru/payment/?land_in=frame&hide_extra=true&def_pay_type=card#!search_provider/pt_search/111-14401-1/pay
frame_1

Еще пример фрейма

Предустановлены значения цветовой схемы, л/с и суммы, с шапкой, способ оплаты - ЯД, другие способы оплаты скрыты, преднастроен почтовый ящик, на который отправлять фискальный чек
https://ckassa.ru/payment/?ui_type=post&land_in=frame_search&def_pay_type=yd&hide_choose_pay_type=true&fiscal_email=mail@mail.com#!search_provider/pt_search/979-13689-15/pay&amount=10000&НОМЕР_ТЕЛЕФОНА=7777777777
frame_2

Позволяет подгрузить форму оплаты прямо на ваш сайт. Клиенту не придется никуда переходить.

Управляется параметрами, вставленными в ссылку

Зеленая зона

Пример ссылки для зеленой зоны

https://ckassa.ru./payment/?lite-version=true#!search_provider/pt_search/ХХХХХХХ/pay
ХХХХХХХ - ваш персональный код услуги (ServiceCode)

Как это будет выглядеть у клиента

low_balance

Подключение решения "зеленая зона" дает возможность вашим абонентам оплатить услуги с вашего сайта, даже если у них отрицательный баланс и, как следствие, отключена услуга доступа в интернет.

Для подключения решения необходимо:

1. Разрешить заблокироанным абонентам доступ к следующим ip адресам:

2. На странице заблокированного экрана разместите Кнопку оплаты

3. Ссылка в кнопке оплаты должна содержать дополнительный параметр lite-version=true

Разбор ошибок

Если вы на свой запрос получаете ответ 400 Bad Request, то, как правило, это связано с некорректной подписью (если в запросе присутствует параметр sign). Проверьте верно ли составлена подпись по разделу Формирование подписи.

Ошибки, сигнализирующие о том, что необходимо заново регистрировать карту:

Ошибки, связанные со сложностями в авторизации:

Не удалось получить список услуг:

Сложности с регистрацией:

Сложности с активацией:

Проблемы со статусом платежа:

Трудности в создании платежа:

Общее:

Коды ошибок проводки платежа

Общие ошибки:

Спецификация №1

Так же именуемая Bisys 3

Позволяет Вывести на сайт ckassa.ru оплату услуг вашей организации, добавить на ваш сайт, либо ЛК специальную кнопку оплаты ваших услуг.

Описание общее. Что конкретно будет передаваться в запросах и ответах определяется условиями договора.

Основные положения

Поставщик принимает запросы с данными о платежах от Общества. Для обработки запросов Поставщику необходимо следующее ПО: HTTP-сервер, программы (скрипты), которые обрабатывают запросы Общества и заносят платежи в базу данных Поставщика. (Чаще всего используются Apache и скрипты, написанные на PHP.)

Обмен данными проходит по протоколу HTTPS. Для авторизации Общества используется MD5-хэш данных запроса с паролем, в шестнадцатеричном виде.

ПО Поставщика должно проверять IP-адрес, с которого поступают запросы и MD5-хэш. Поставщик обязан отвергать все запросы, совершенные с других IP-адресов, и/или с неверным значением MD5-хэша.

Для идентификации Поставщика используется MD5-хэш данных ответа с паролем. В случае получения неверного значения хэша в ответе, Общество считает ответ ошибочным и должно сообщить об этом Поставщику

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

Общий формат запроса:

<?xml version="1.0" encoding="{кодировка}"?> 
<request>
 <params>
 {параметры}
 </params>
 <sign>{подпись}</sign>
</request>

Общий формат ответа:

<?xml version="1.0" encoding="{кодировка}"?>
<response>
 <params>
 <err_code>{кодошибки}</err_code>
 <err_text>[текстошибки]</err_text>
 [параметры]
 </params>
 <sign>{подпись}</sign>
</response>

Тип запросов POST, кодировка windows-1251, или UTF-8. Кодировку выбирает Поставщик. Все запросы Общества и ответы Поставщика должны быть в одной кодировке.

Тело POST-запроса содержит один параметр params, в котором передается XML-запрос. Данные URL-кодированные. Заголовок: ContentType: application/x-www-form-urlencoded. Аналогичный запрос будет, если создать HTML-форму с элементом <textarea name="params" …>, поместить в элемент текст XML-запроса и отправить средствами браузера.

Ответы Поставщика в формате XML, кодировка ответа должна соответствовать кодировке запросов. В HTTP заголовке желательно установить Content-Type: text/xml; charset=<кодировка>.

Ограничения XML.

Запрещены пробелы до или после имени тэга (между <>). Общество гарантирует отсутствие таких пробелов в запросах. В связи с этим, и с тем, что структура XML простая, можно не использовать для обработки XML специальные компоненты, а обрабатывать простыми функциями работы со строками.

Достаточно написать одну строковую функцию по типу: содержимое_тега = get_tag_content (запрос - имя тега). Либо использовать резульрные выражения.

Элементы запроса:

Элементы ответа:

Доступные типы данных

Проверка параметров платежа

Пример запроса проверки возможности занесения платежа:

<?xml version="1.0" encoding="windows-1251"?>
<request>
 <params>
 <act>1</act>
 <agent_date>2009-04-15T11:22:33</agent_date>
 <account>54321</account>
 <serv_code>53001</serv_code>
 <pay_amount>10000</pay_amount>
 <client_name>Иванов Иван Иванович</client_name>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</request>

Данный запрос позволяет Обществу предварительно проверить возможность занесения палатежа.

Поля запроса:

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

<?xml version="1.0" encoding="windows-1251"?>
<response>
 <params>
 <err_code>0</err_code>
 <err_text>OK</err_text>
 <account>54321</account>
 <client_name>Иванов Иван Иванович</client_name>
 <balance>50.00</balance>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</response>  

Пример ответа Поставщика при ошибке:

<?xml version="1.0" encoding="windows-1251"?>
<response>
 <params>
 <err_code>20</err_code>
 <err_text>Номер счета не найден</err_text>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</response>

Поля ответа:

Проведение платежа

При запросе проведения платежа все его параметры проверяются так же, как при запросе проверки. По этому Обществу не обязательно использовать предварительный запрос проверки.

Поля запроса проведения платежа:

Пример запроса на проведение платежа:


 <?xml version="1.0" encoding="windows-1251"?>
<request>
 <params>
 <act>2</act>
 <agent_date>2009-04-15T11:22:33</agent_date>
 <pay_id>2345</pay_id>
 <pay_date>2009-04-15T11:00:12</pay_date>
 <account>54321</account>
 <pay_amount>10000</pay_amount>
 <client_name>Иванов</client_name>
 <month>08.2012</month>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</request>

Поля ответа:

Пример ответа на проведение платежа:

<?xml version="1.0" encoding="windows-1251"?>
<response>
 <params>
 <err_code>0</err_code>
 <err_text>OK</err_text>
 <reg_id>3456</reg_id>
 <reg_date>2009-04-15T11:22:55</reg_date>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</response>

Статус платежа

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

<?xml version="1.0" encoding="windows-1251"?>
<request>
 <params>
 <act>4</act>
 <pay_id>2345</pay_id>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</request>

Пример ответа Поставщика на проверку статуса:

<?xml version="1.0" encoding="windows-1251"?>
<response>
 <params>
 <err_code>0</err_code>
 <err_text>Платеж обработан</err_text>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</response>

Пример ответа Поставщика на проверку статуса в случае временной ошибки:

<?xml version="1.0" encoding="windows-1251"?>
<response>
 <params>
 <err_code>40</err_code>
 <err_text>Ошибка подключения к серверу получателя.</err_text>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</response

Иногда статус платежа у Поставщика не конечный на момент выдачи ответа на запрос проведения. В таких случаях Поставщик отвечает кодом 2 (Платеж ожидает обработки у Поставщика). После этого Общество будет посылать запросы на получение статуса. На такие запросы Поставщик отвечает кодом 0 (платеж проведен), 2 (платеж в процессе обработки), 40 (временная ошибка обработки), или 41 (окончательная ошибка обработки).

Поля запроса:

Возврат платежа

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

<?xml version="1.0" encoding="windows-1251"?>
<request>
 <params>
 <act>8</act>
 <pay_id>2345</pay_id>
 <pay_date>2009-04-15T11:00:12</pay_date>
 <account>54321</account>
 <pay_amount>10000</pay_amount>
 <reg_id>5432</reg_id>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</request>

Пример ответа на запрос по возврату платежа:

<?xml version="1.0"encoding="windows-1251"?>
<response>
 <params>
 <err_code>0</err_code>
 <err_text>Запрос принят</err_text>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</response>

Пример ответа на запрос возврата платежа в случае ошибки:

<?xml version="1.0" encoding="windows-1251"?>
<response>
 <params>
 <err_code>80</err_code>
 <err_text>Операция невозможна.</err_text>
 </params>
 <sign>827CCB0EEA8A706C4C34A16891F84E7B</sign>
</response>

В некоторых случаях требуется отмена платежа, проведенного Поставщику. Запрос на возврат передает, как бы, заявку на возврат платежа. Поставщик рассматривает возможность отмены платежа. По возможности отменяет платежи, меняя их статус. Общество может узнать об итоге операции запросом статуса платежа, или письменным уведомлением.

Запрос на возврат не обязателен для реализации протокола. Решайте сами, нужна ли вам такая возможность.

Поля запроса:

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

Уникальность платежа

При получении запроса проведения платежа Поставщик должен проверить уникальность платежа. Номер платежа pay_id должен быть уникальным по Обществоу. При получении запроса Поставщик должен выполнить в своей базе поиск платежа с таким же pay_id, как у полученного в запросе.

Если такой платеж будет найден, необходимо сверить реквизиты account и pay_amount платежа в запросе с соответствующими реквизитами платежа в базе.

Если они совпадают, то это просто повтор запроса. В этом случае ответ Поставщика должен быть как на первый удачный запрос проведения, с теми же reg_id и reg_date, если они используются, но с кодом ошибки 1.

Если account или pay_amount различаются, то это нарушение правил учета платежей у Общества и Поставщик должен ответить ошибкой с кодом 30. reg_id и reg_date в этом случае не передаются.

Формирование подписи в запросах

Пример

Для запроса: 

<?xml version="1.0" encoding="windows-1251"?>
<request>
 <params>
 <act>1</act>
 <account>758</account>
 </params>
 <sign>724870FC6BC385D7A29F4A259B6E9A6B</sign>
</request>


Нужно делать хэш для строки “<act>1</act><account>758</account>пароль”

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

Предварительно Общество и Оператор обмениваются паролем. Используется одинаковый пароль для Общества и Оператора. В качестве подписи используется MD5-хэш в виде последовательности из 32 шестнадцатеричных цифр. Регистр букв значения не имеет.

К сформированному содержимому тэга params конкатенируется пароль. Содержимое тэга params берется как есть, вместе с вложенными тэгами, переносами строк. Для полученной строки генерируется подпись, которая передается в параметре sign.

Получив запрос, Оператор извлекает из него подстроку между тэгами params, генерирует для нее подпись и сверяет ее с подписью в запросе. Оператор должен обрабатывать подпись запроса в любом регистре, поэтому перед сравнением надо приводить подписи к одному регистру.

Формирование подписи в ответах Поставщика

К сформированному содержимому тэга params конкатенируются подпись полученного ранее запроса и пароль. Подпись полученного ранее запроса должна быть в том регистре, в котором получена от Общества. Для полученной строки генерируется подпись, которая передается в параметре sign.

Получив ответ, Общество извлекает из него подстроку между тэгами params, генерирует для нее подпись и сверяет ее с подписью в ответе.

Коды ошибок

Коды ошибок, возвращаемых оператором

Код ошибки Описание ошибки
0 Успешное выполнение операции
1 Платеж уже был проведен
2 Платеж ожидает обработки у оператора
10 Запрос выполнен с неразрешенного адреса
11 Указаны не все необходимые параметры
12 Неверный формат параметров
13 Неверная цифровая подпись
20 Указанный номер счета отсутствует
21 Запрещены платежи на указанный номер счета
22 Запрещены платежи для указанной услуги
23 Запрещены платежи для указанного Общества
29 Неверные параметры платежа. В тэге err_text конкретное описание причины
30 Был другой платеж с указанным номером
40 Предварительная ошибка обработки платежа
41 Окончательная ошибка обработки платежа
80 Отказ на возврат платежа, в тэге err_text причина отказа.
90 Временная техническая ошибка
99 Прочие ошибки Поставщика. В тэге err_text указывается описание причины

Формат реестра

В информационный реестр платежей включаются все платежи, принятые Обществом для передачи Поставщику за прошедшие сутки. Платежи выбираются по дате учета Общества – agent_date. Реестр высылается Обществом до 12 часов следующих суток по часовому поясу Общества. Реестр высылается по почте. Поставщик проводит сверку платежей, принятых в течение контрольных суток, с платежами в реестре.

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

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

Формат реестра.

Реестр платежей представляет собой XML-файл в кодировке windows-1251.

Пример реестра платежей:

<?xml version="1.0" encoding="windows-1251"?>
<registry format=”P03” form_date=”2011-05-13 12:00:00”>
 <reg_date>2011-05-12</reg_date>
 <agent_name>ООО Общество</agent_name>
 <prov_name>ООО Оператор</prov_name>
 <pays>
 <pay agent_date=”2011-05-12 11:22:33” pay_id=”2345” pay_date=”2011-05-12 11:00:12”
account=”54321” pay_amount=”10000” serv_code=”123/1” serv_name=”Интернет” reg_id=”98765”
err_code=”0” note=”” />
 <pay agent_date=”2011-05-12 11:22:35” pay_id=”2346” pay_date=”2011-05-12 11:00:17”
account=”65432” pay_amount=”20000” serv_code=”123/1” serv_name=”Интернет” reg_id=”98767”
err_code=”99” note=”Ошибкаподключенияксерверуоператора”/>
…
</pays>
</registry>

Элементы реестра:

Имя файла итогового реестра формируется следующим образом:

bs-Код-YYYYMMDD.xml

Реестр отправляется отдельным сообщением электронной почты в виде вложения.

Разработчикам

Пример 1

function getTagContent(string request, string tag) return string
{
string beginTag = "<" + tag + ">";
string endTag = "</" + tag + ">";
int p1 = pos(request, beginTag); //позиция первого тэга
if (p1 > 0)
{
p1 = p1 + length(beginTag); //смещение на начало содержимого
int p2 = pos(request, endTag); //позиция конечного тэга
if (p2 > p1)
return SubString(request, p1, p2 - p1); //выбор содержимого
}
return "";
}

Пример 2

function getTagContent($string, $tagname)
{
$pattern = "|<".$tagname.">(.+)</".$tagname."|si";
preg_match($pattern, $string, $matches);
return $matches[1];
}

Пример 3

<html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=windows-1251">
 <title>Тест протокола БС</title>
 </head>
 <body>
 <form name="text" action="https://ваш адрес" method="post">
 XML-запрос:
 <br> <textarea name="params" rows="20" cols="80"></textarea>
 <br> <br>
 <input type="submit" value="Отправить">
 <input type="reset" value="Очистить">
 </form>
 </body>
</html>

XML используется с ограничениями, без атрибутов (кроме реестра). Для извлечения данных нет необходимости использовать парсер, достаточно использовать функцию.

Пример функции в примере 1

Либо регулярные выражения. Более подробно в примере 2

Так же, вы можете тестировать себя из браузера. Создайте html-файл с текстовым полем, вставляйте в поле XML-запросы и отправляйте.

Подробней в примере 3.

Спецификация №2

Так же именуемая Kiberplat

Позволяет Вывести на сайт ckassa.ru оплату услуг вашей организации, добавить на ваш сайт, либо ЛК специальную кнопку оплаты ваших услуг.

Предоставлено общее описание. Что конкретно будет передаваться в запросах и ответах определяется условиями договора.

Требования

Требования к интерфейсу поставщика:

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

Пример запроса-ответа поиска Плательщика по номеру телефона

Запрос:
https://<host>/<path>?ACTION=check&ACCOUNT=8462333333

Ответ:
<?xml version=”1.0” encoding=”windows-1251”?>
<response>
<CODE>0</CODE>
<MESSAGE>ОК</MESSAGE>
<FIO>Иванов Иван Иванович</FIO>
<ADDRESS>Москва</ADDRESS>
<ACCOUNT_BALANCE>-34.27</ACCOUNT_BALANCE>
</response>

Запрос:
https://<host>/<path>?ACTION=check&ACCOUNT=24

Ответ:
<?xml version=”1.0” encoding=”windows-1251”?>
<response>
<CODE>3</CODE>
<MESSAGE>Абонент не найден</MESSAGE>
</response>

Атрибуты ответа

Примеры запросов - ответов создания транзакции платежа

Запрос: 
https://<host>/<path>?ACTION=payment&ACCOUNT=8462333333&AMOUNT=340.24&PAY_ID=11223344&PAY_DATE=12.12.2005_12:45:18

Ответ: 
<?xml version=”1.0” encoding=”windows-1251”?>
<response>
<CODE>0</CODE>
<MESSAGE></MESSAGE>
<REG_DATE>12.12.2005_12:46:03</REG_DATE>
</response>

Запрос: 
https://<host>/<path>?ACTION=payment&ACCOUNT=8462333333&TYPE=15&AMOUNT=340.24&PAY_ID=11223344&PAY_DATE=12.12..2005_12:45:18

Ответ:
<?xml version=”1.0” encoding=”windows-1251”?>
<response>
<CODE>6</CODE>
<MESSAGE>Не верное значение даты платежа</MESSAGE>
</response>

Какой должен быть формат ответа сервера Поставщика:

Ответы сервера Поставщика возвращаются в виде XML-сообщений. Атрибут encoding должен иметь значение windows-1251 и соответствовать кодировке, используемой в XML-сообщении.

Рассмотрим атрибуты, используемые в ответах сервера Поставщика на запросы Общества.

Коды ответов

Ниже приведены возможные значения кодов возврата (атрибут - CODE)

Код ответа Значение check/payment
-1 Внутренняя ошибка организации + / +
0 Успешное завершение операции. Для операции проверки состояния транзакции это означает, что транзакция подтверждена и платежи в системе Поставщика были успешно созданы + / +
2 Неизвестный тип запроса. Неизвестное значение поля ACTION + / +
3 Плательщик не найден + / +
4 Неверная сумма платежа. Недопустимое значение для поля платежа (AMOUNT) - / +
5 Неверное значение идентификатора транзакции. Недопустимое значение поля идентификатора платѐжной транзакции в платѐжной системе (PAY_ID) - / +
6 Неверное значение даты. Недопустимое значение поля даты платежа (PAY_DATE) - / +
8 Дублирование транзакции. Транзакция с указанным идентификатором уже была введена в систему - / +
12 Транзакция не подтверждена - / -

Шаблоны ответов

Ответ сервера Поставщика на запрос проверки номера (check) должен подчиняться следующему шаблону DTD:

<?xml version=”1.0” encoding=”windows-1251”?>

<!DOCTYPE response [

<!ELEMENT response (CODE, MESSAGE, FIO,ADDRESS, ACCOUNT_BALANCE)>

]>

Ответ сервера Поставщика на запрос создания транзакции платежа (payment) должен подчиняться следующему шаблону DTD:

<?xml version=”1.0” encoding=”windows-1251”?>

<!DOCTYPE response [

<!ELEMENT response (CODE, MESSAGE, REG_DATE)>

]>

Ответ сервера Поставщика на запрос подтверждения транзакции (commit) должен подчиняться следующему шаблону DTD

<?xml version=”1.0” encoding=”windows-1251”?>

<!DOCTYPE response [

<!ELEMENT response (CODE, MESSAGE, REG_DATE, PAY_ID_EXT*)>

] >

Спецификация №3

Также именуемая ОСМП

Требования к интерфейсу Поставщика

Основные принципы работы интерфейса

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

Сумма платежа принимается от Плательщика и передается Поставщику в рублях в переменной sum – это дробное число с точностью до сотых. В качестве разделителя используется «.» (точка). Если сумма представляет целое число, то оно все равно дополняется точкой и нулями, например – «152.00»

В запросе на добавление платежа Общество передает дату платежа (под датой платежа в системе подразумевается дата получения запроса от клиента) в переменной txn_date – дата в формате ГГГГММДДЧЧММСС. Эту дату необходимо использовать для проведения бухгалтерских взаиморасчетов. Так как у Общества учет платежей ведется по дате получения запроса от Плательщика, то и расчеты с Поставщиком необходимо вести по этой дате.

Например:

Плательщик прислал Обществу запрос 31.12.2016 в 23:59:59, учитывая задержку на обработку данных и пересылку информации по каналам связи, Общество смогло отправить запрос Поставщику 01.01.2017 00:00:05, соответственно, платеж будет учтен в системе Поставщика в другом отчетном периоде. Это вызовет некоторые проблемы при проведении сверок. Чтобы избежать такой ситуации, Общество передает Принципалу дату, в которой нужно учитывать платеж.

Поставщик идентифицирует своего Плательщика по уникальному идентификатору (Идентификатор Плательщика). Перед отправкой Поставщику Идентификатор проходит проверку корректности в соответствии с регулярным выражением, которое должен предоставить Поставщик. Идентификатор Плательщика передается в переменной account – это строка, содержащая буквы, цифры и спецсимволы длиной до 200 символов.

Оплата услуг Поставщика производится системой в 2 этапа – проверка состояния Плательщика и, непосредственно, проведение платежа. Тип запроса передается Обществом в переменной command – это строка, принимающая значения check и pay. При проверке статуса (запрос check) Поставщик должен проверить наличие в своей базе абонента с указанным Идентификатором и выполнить внутренние проверки Идентификатора, суммы платежа в соответствии с принятой логикой пополнения лицевых счетов через платежные системы. При проведении платежа (запрос pay) Поставщик должен произвести пополнение баланса Плательщика.

Если любой из запросов Поставщику завершается ошибкой, то Поставщик возвращает код ошибки в соответствии с таблицей, приведенной Ниже . Все ошибки имеют признак фатальности. Для Общества фатальная ошибка означает, что повторная отправка запроса с теми же параметрами приведет к 100% повторению той же ошибки – следовательно, Общество прекращает обработку запроса и завершает его с ошибкой. Нефатальная ошибка означает для Общества, что повторение запроса с теми же параметрами через некоторый промежуток времени, возможно, приведет к успеху. Общество будет повторять запросы, завершающиеся нефатальной ошибкой, постоянно увеличивая интервал, пока операция не завершится успехом, или фатальной ошибкой, либо пока не истечет срок жизни запроса (24 часа). Отсутствие связи с сервером Поставщика является нефатальной ошибкой. Например, отсутствие в ответе элемента <result> (некорректный XML, страница Servicetemporarilyunavailable и т.д.) - является фатальной ошибкой. Запросы получают отказ с ошибкой 300 – Другая ошибка Поставщика

В базе Поставщика не должно содержаться двух успешно проведенных платежей с одним и тем же номером txn_id. Если Общество повторно присылает запрос с уже существующим в базе Поставщика txn_id, то Поставщик должен вернуть результат обработки предыдущего запроса.

Структура XML ответа Поставщика

<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id></osmp_txn_id>
<prv_txn></prv_txn>
<sum></sum>
<result></result>
<comment></comment>
</response>

Где:

Коды ответов

При обработке запросов от системы Общества, Поставщик должен сопоставить все возникающие в его приложении ошибки с приведенным ниже списком и возвращать соответствующие коды в элементе <result>

Код Значение Фатальность
0 Все ОК -
1 Временная ошибка. Повторите запрос позже -
4 Неверный формат идентификатора Плательщика +
5 Идентификатор Плательщика не найден (Ошиблись номером) +
7 Прием платежа запрещен Поставщиком +
8 Прием платежа запрещен по техническим причинам +
79 Счет Плательщика не активен +
90 Проведение платежа не окончено +
241 Сумма слишком мала +
242 Сумма слишком велика +
243 Невозможно проверить состояние счета +
300 Другая ошибка Поставщика +

Примеры

Пример запроса/ответа "check" от Поставщика

Запрос должен выглядеть так:
https://service.someprovider.ru:8443/payment_app.cgi?command=check&txn_id=1234567&account=4957835959&sum=10.45

Ответ Поставщика должен выглядеть так:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<result>0</result>
</response>\

Или так:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<result>0</result>
<comment>account exists</comment>
</response>

Пример запроса на проверку состояния счета Плательщика

Платежное приложение Поставщика payment_app.cgi, располагается по адресу service.someprv.ru, сервер поддерживает HTTPS соединения на порт 8443. Для проверки состояния Плательщика, Общество генерирует запрос, показанный в примере check

Строка запроса содержит переменные:

Возвращение result=0 на запрос check свидетельствует о том, что лицевой счет Плательщика с соответствующим ему номером osmp_txn_id может быть пополнен на сумму, указанную в запросе. После успешной проверки состояния счета Плательщика система переходит к формированию и отправке запроса на пополнение баланса (запрос pay).

Пример запроса/ответа "pay" от Поставщика


Запрос должен выглядеть так:
https://service.someprovider.ru:8443/payment_app.cgi?command=pay&txn_id=1234567&txn_date=20050815120133&account=4957835959&sum=10.45

Ответ Поставщика должен выглядеть так:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<prv_txn>2016</prv_txn>
<sum>10.45</sum>
<result>0</result>
</response>

Или так:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<prv_txn>2016</prv_txn>
<sum>10.45</sum>
<result>0</result>
<comment>OK</comment>
</response>

Пример запроса на пополнение лицевого счета

Запрос, показанный в примере запроса Поставщика "pay" содержит следующие переменные:

Возвращая result=0 на запрос pay, Поставщик сообщает об успешном завершении операции пополнения баланса. Система полностью завершает обработку данной транзакции

Пример передачи дополнительных параметров в запросе

<?xml version="1.0" encoding="UTF-8"?>
<response>
<result>0</result>
<osmp_txn_id>1001</osmp_txn_id>
<comment></comment>
<bisys_params>
<client_name>Иванов</client_name>
<balance>-200.00</balance>
</bisys_params>

SSL сертификат

ПОРЯДОК ИСПОЛЬЗОВАНИЯ SSL-СЕРТИФИКАТОВ

1. Поставщик предоставляет Обществу корневой сертификат Поставщика (для обеспечения доверия сертификатам, выданным Центром сертификации Поставщика) в виде, пригодном для установления его принадлежности Поставщику, то есть в виде base-64 кодированного файла формата PKCS#10 и на бумажном носителе, заверенном собственноручной подписью руководителя и оттиском печати Поставщика.

2. Полученный сертификат Поставщика вводится Обществом в действие, не позднее следующего рабочего дня после его предоставления Поставщиком на бумажном носителе.

3. При истечении срока действия корневого сертификата Поставщика, Поставщик не позднее, чем за 5 (пять) рабочих дней до окончания срока действия активного корневого сертификата предоставляет Обществу новый корневой сертификат в соответствии с п.1.

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

5. Общество, после получения сообщения о компрометации сертификата, выводит соответствующий сертификат из действия в максимально короткие сроки, но не позднее следующего рабочего дня после получения сообщения о компрометации.

6. Клиент имеет право в любое время производить замену собственных сертификатов.

<>