Метод process payment api кошелька ю money

Введение

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете проверить сценарий оплаты банковскими картами разных типов с разными результатами:

pan (номер карты) срок CVV ожидаемый результат RC Платежная система Актуальная

• 5479 2700 0000 0000 03/22 123 Успех с 3ds 12345678 00 MASTER CARD Да
• 4111 1111 1111 1111 12/24 123 Успех с 3ds 12345678 00 VISA Да
• 6011 0000 0000 0004 12/24 123 Успех с 3ds 12345678 00 MAESTRO Да
• 2201 3820 0000 0013 12/24 123 Успех с 3ds 12345678 00 МИР Да
• 2201 3820 0000 0062 12/24 123 Успех с 3ds 12345678 00 МИР Да
• 2201 3820 0000 0039 12/24 123 Успех с 3ds 12345678 00 МИР Да

Для получения RC=05 необходимо ввести неверный код cvc2.

• Shop name — любой
• shopToken — 1a4c0d33-010c-4365-9c65-4c7f9bb415d5
• secKey — 6a7abaad-2147-4646-b91a-435b5d97527b

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

• Code serviceCode Тип услуги
• 17526 1000-13864-2 Зачисление на р/с без комиссии

Реквизиты для параметра properties по услуге 1000-13864-2:

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

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

Находим заявку на подключение и внизу нажимаем получить токен и ключ

Откроется форма потдверждения. СМС код придет на телефон технического специалиста:
После ввода кода необходимо выбрать какие типы callback вы хотите получать:
Появятся поля для заполнения ссылок на callback:
Обратите внимание. Несмотря на то, что полей для ссылок может быть несколько, мы принимаем только одну ссылку для любых типов callback
Мы считаем это багом и скоро его исправим.
А пока, необходимо во все поля писать одну и ту же ссылку.
Осталось нажать подтвердить и вы получите нужные вам ShopToken и SecKey:
Готово! Вы, как всегда, восхитительны! Успешной вам интеграции! Побольше платежей и поменьше errorов!
## Платеж с 3ds
Некоторые рекуррентные платежи невозможны без данной технологии. При этом будет сгенерировано исключение NeedPass3dsException (смотри код 2365 в разделе Разбор ошибок), которое содержит номер платежа regPayNum и securePageURL (URL - тот, на который необходимо перенаправить пользователя для прохождения 3ds методом GET)
Ислючение может быть получено на этапе создания рекуррента (описан в разделе создание платежа), а так же на этапе проверки статуса платежа (описан в разделе Получение статуса платежа)
## Параметр needRegCard
Используется только для рекуррентных платежей без параметра cardToken, необходим для привязки карты к пользователю после успешно оплаты
Данный парамер определяет необходимость принудительного 3ds для платежа
Задается при Создании рекуррентного платежа
Значения для данного параметра следующие:
## Параметр enableSMSConfirm
Данный параметр определяет включать ли поддержку 3ds
Задается при Создании платежа
false - включен по умолчанию
При необходимости пройти 3ds, будет сгенерировано исключение: CreatePaymentException (код 1295), либо CantDoRecurrent (код 2360) в разделе разбор ошибок
При необходимости пройти 3ds платёж будет создан. При проверке статуса) данного платежа будет сгенерировано исключение NeedPass3dsException (код 2365)
В параметре securePageURL будет передана ссылка на прохождение 3дс, перенаправьте по ней клиента вызовом метода GET
## Тэги для работы с 3ds в мобильном приложении
Фрагмент HTML разметки с блоком успеха
Фрагмент HTML разметки с блоком ошибки
При работе с 3дс приложение загружает страницы в WebView. Каждая загруженная страница парсится в html документ с помощью JSOUP. Выполняется поиск идентификаторов, которые используются для того, чтобы можно было определить что загруженная страница - последняя, больше редиректов не будет и можно закрывать WebView.
Содержит html тэг с идентификатором endpoint_result, внутри которого должен находиться тэг с идентификатором endpoint_success.
Содержит html тэг с идентификатором endpoint_result, внутри которого должен находиться тэг с идентификатором endpoint_error.
На основе содержимого этих тэгов создастся исключение, которое будет позже показано пользователю в виде AlertDialog
error_title - Заголовок ошибки. Отображается как заголовок диалога. Если error_title не будет найден, по умолчанию используется текст Ошибка проведения платежа

Параметр shopLogin

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

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

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

Доступен для методов do/payment и do/payment-rezerv

Работает следующим образом:

Параметр fiscalType

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

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

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

Параметр payType

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

Параметр orderBestBefore

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

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

По умолчанию срок жизни заказа 72 часа

Параметр orderItems

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

orderItems — Описание предметов расчета (тег 1059 в фискальном чеке).

Параметр — public class OrderItems

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

Параметр clientAuInfo

Пример заполнения параметра clientAuInfo

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

В параметре clientAuInfo необходимо передавать данные для корректного прохождения 3ds v2.

Применимо только для методов рекуррентного платежа: Создание платежа, поездка, Создание платежа с бронированием суммы, поездка, Создание платежа, Лайт, Создание платежа с бронированием суммы, Лайт, Создание платежа, Лайт мерчант, Создание платежа с бронированием суммы, Лайт мерчант, Cоздание рекуррентного платежа

Для метода Анонимного платежа наша форма оплаты сама соберёт необходимые данные.

Параметр orderNote

В параметре orderNote передаются дополнительные данные, которые будут отображаться на платёжной форме.

Доп. справочное поле для пользователя.

Применимо только для методов, когда используется форма для ввода данных карты: Создание платежа, анонимного платежа, Cоздание рекуррентного платежа с типом оплаты картой (payType:card) и без заполненного параметра cardToken

В параметре также есть возможность передачи валюты. Для этого необходимо указать валюту в кодировке ISO 4217 (буквенной). На форме ввода данных карты валюта в кодировке ISO 4217 будет показа символьным эквивалентом. Передавать в параметр валюту необходимо в таком виде RUB Список допустимых валют:

Буквенный код Цифровой код Валюта Разменная валюта Символ

RUB 643 российский рубль копейки (1⁄100) ₽

USD 840 американский бакс цент (1⁄100) $

GPB 826 фунт, Великобритания пе́нни (1⁄100) £

KGS 417 сом, Киргизия тыйын (1⁄100) с •

UZS 860 сум, узбекский тийин (1⁄100) Som

AZN 944 азербайджанский манат гяпик (1⁄100) ₼

GEL 981 лари, Грузия тетри (1⁄100) ₾

TRY 949 турецкая лира куруш (1⁄100) ₺

AMD 051 армянский драм лума (1⁄100) ֏

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

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

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

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

• created_error: ошибка при создании платежа
• created: платеж создан, но не оплачен
• rejected: платеж отменен (если оплачивает не рекуррент, то возможен переход в статус payed, например, при повторном вводе данных карты)
• refunded: оплата возвращена

Платеж оплачен и ожидает исполнения (можно оказывать услугу):

• payed: платеж оплачен
• holded: денежные средства заморожены
• processed: платеж оплачен и успешно проведен

Ошибка при проведении (платеж оплачен, но при проведении платежа возникла ошибка)

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

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

{ state: holded, totalAmount: 2575, createdDate: 2020-05-29 14:11:21, providerServCode: 1000-13864-3, providerName: Тест ShopAPI, errorCode: null, error: null, message: null, provisionServices: false, procDate: null
}

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

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

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

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

По умолчанию отправляются только успешные платежи. При неуспешном создании платежа уведомление не отправляется. Ckassa отправляет POST запросы с нарастающим интервалом. Ожидается ответ https — статусом 200.

Также можно выбрать тип callback full3 для отправки дополнительных параметров. Параметры ответа:

• amount: сумма платежа в копейках
• state: статус платежа
• result: результат (code, message, details)
• rrn: Merchant bank’s Retrieval Reference Number
• irn: Internal Reference Number
• approvalCode: код авторизации
• cardPan: публичный номер карты
• created: время создания платежа

Чек по 54ФЗ:

Процесс фискализации платежа может занимать от нескольких минут до часа.

После отправки запроса вы получите ссылку на сервис ckassa. При переходе на данную ссылку, если платеж уже был фискализирован, проихойдет редирект клиента на сайт ФНС с фискальным чеком.

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

Рекомендуемый алгоритм работы с методом:

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

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

Фискализация наличных

Пример запроса на фискализацию наличных

Наше API позволяет не только провести платеж, но и создать информационный платеж чтобы зарегистрировать в ФНС принятые наличные

Для того, чтоб создать такой платеж укажите в параметре payType значение fiscalCash

Для тестирования механизма рекомендуем следующий алгоритм:

Проверка баланса на карте Лайт

С помощью данного метода можно проверить баланс у водителя на карте Лайт

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

С помощью данного метода можно можно отправлять заявки на возврат и частичный возврат. Метод доступен только для Магазин. Рекуррентный платёж или Магазин. Анонимный платеж.

Редирект

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

Success url = http://acq.test.ru/success/

После совершения успешного платежа, номер которого 123456789, пользователь, после нажатия на кнопку "Вернуться в магазин", будет перенаправлен по ссылке http://acq.test.ru/success/?reg_pay_num=123456789

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

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

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

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

только для библиотеки php

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

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

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

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

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

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

clientType — тип клиента*

payType — Способ оплаты. Обязателен только для совершения рекуррентного платежа через SberPay** Подробнее о Функции payType

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

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

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

login + номер телефона с кодом, но без ‘+’, например — 79020000000.

email — e-mail (на него отправляются чеки после оплаты)

name — имя

surName — фамилия

middleName — отчество

state + статус. Более подробно — Статус пользователя

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

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

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

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

ShopToken — идентификатор магазина

cards — список карт

Данные в переменной cards:

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

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

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

resultState — результат

Возможные значения для resultState:

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

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

cardToken + токен карты

cardMask + маскированый номер карты

cardType + тип карты. Подробнее см. п. Получение списка карт

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

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

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

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

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

serviceCode + код провайдера

amount + сумма платежа в копейках, которая идет на счет пользователю

comission + комиссия платежа в копейках (при отсутствии комиссии передается 0)

needRegCard — Включает принудительный 3ds, более подробно: needRegCard

cardToken — идентификатор карты (для рекуррентного платежа), см. пункт Получение списка карт

gpayToken — Токен при оплате через Google Pay. Более подробно в разделе Google Pay

applePayToken — токен при оплате через Apple pay. Подробнее в разделе Apple Pay

mirPayToken — токен при оплате через Mir Pay. Подробнее в разделе Mir Pay

enableSMSConfirm — более подробно: EnableSMScnfirm

payType — способ оплаты подробнее в п. Параметр payType

clientType — более подробно в п. Создание анонимного платежа

fiscalType * отправлять ли фискальный чек. Подробнее: Параметр fiscalType

orderBestBefore — Время истечения срока жизни заказа в секундах. Подробнее

holdTtl — время заморозки средств (в секундах). Минимум 10 минут, максимум 4 дня. Если услуга не будет подтверждена, произойдет автоматический возврат средств на карту клиента.

successUrl — динамический url возврата клиента после успешной оплаты***

failUrl — динамический url возврата клиента после неуспешной оплаты***

cbUrl — динамический url для отправки уведомлений, более подробно: Уведомление об оплате

properties + массив реквизитов. Более подробно в п. Создание анонимного платежа

orderItems — Корзина для фискализации. Подробнее

clientAuInfo + Параметры браузера для прохождения 3ds v2. Подробнее

shopLogin — Для авторегистрации пользователя, после создания платежа Подробнее

Создание платежа с бронированием суммы

Для оплаты поездок рекомендуем указывать holdTtl не менее 30 минут (1800)

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

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

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

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

Метод можно вызвать несколько раз

Чтобы обновить получателя денежных средств необходимо указать новый главный реквизит получателя (обычно этот реквизит называют ‘лицевой счет’. Указывается в массиве реквизитов properties)

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

1. Выполнить Создание платежа с бронированием суммы, указав в properties дефолтный лицевой счет. Он не обязательно должен быть рабочим, главное, чтобы он проходил под критерии проверки реквизита (размер, с чего начинается и т.д.)

2. После назначения машины выполнить обновление получателя денежных средств

3. По завершению поездки подтвердить заморозку

regPayNum + номер платежа

value + новое значение главного реквизита

resultState + результат (success / fail)

desc — пояснение

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

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

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

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

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

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

orderId + уникальный номер заказа на стороне поставщика услуг

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

ShopToken — Идентификатор магазина

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

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

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

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

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

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

Заказ с оплатой на виртуальную карту Лайт

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

Блок-схемы проведения процессов:

Регистрация карты плательщика

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

Проверка возможности оплаты на карту КУБ Лайт

Если проверка для карты КУБ Лайт прошла успешно, вызовите метод Создания платежа

При Создании платежа с бронированием суммы нужно проверять конечного получателя (если для него опалата не доступна — деньги будут возвращены клиенту)

login номер телефона с кодом, но без ‘+’. Например: 79020000000

enable + true/false возможно или нет выполнить платеж

incomeToList + IncomeTo. список, расшифровка по иструментам зачисления

desc + пояснение

Параметры передаваемые в IncomeTo:

enable — true/false

incomeTo — доступные инструменты (куда пойдет зачисление денег)