Boleto
Обзор
Введение
Boleto — метод, позволяющий проводить платежи в бразильских реалах и долларах США с использованием ваучеров в Бразилии. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты.
В этой статье представлена информация о работе с методом Boleto: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | платежи через точки оплаты |
---|---|
Платёжные инструменты | ваучеры |
Регионы использования | BR |
Валюты платежей | BRL, USD |
Конвертация валют | – |
Разовые оплаты | + |
Оплаты по сохранённым данным | – |
Полные возвраты | – |
Частичные возвраты | – |
Выплаты | – |
Опротестования | – |
Особенности |
|
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommpay shop |
Схема работы
В проведении отдельного платежа с использованием метода Boleto задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса Boleto.
Основные операции
Для проведения платежей и выполнения операций с использованием метода Boleto могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок).
Сценарии использования
Проведение оплат с использованием метода Boleto осуществляется с перенаправлением пользователей к сервису Boleto.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода Boleto со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Payment Page. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
- Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
- Пользователю отображается платёжная форма.
- Пользователь выбирает для оплаты метод Boleto.
- Пользователю отображается платёжная форма, соответствующая запросу.
- Пользователь вводит персональные данные для оплаты.
- В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Boleto.
- В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Boleto.
- В сервисе Boleto выполняется обработка запроса на оплату.
- От сервиса Boleto в платёжную платформу направляются сгенерированный ваучер для оплаты в терминале или данные для перенаправления пользователя в сервис Boleto. В зависимости от провайдера, обрабатывающего платёж ваучер может быть действителен в течение 8 (но пользователь может совершить оплату в течение 30 дней, обратившись в банк) или 3 дней с момента получения.
- Данные ваучера или перенаправления передаются к Payment Page.
- Пользователю на Payment Page или после перенаправления в сервисе Boleto отображаются ваучер и инструкция для оплаты. Статус платежа
awaiting customer action
илиawaiting redirect result
(в зависимости от провайдера, обрабатывающего платёж) остается до тех пор, пока пользователь не завершит оплату. - Пользователь завершает оплату в одном из доступных терминалов оплаты, используя полученный ваучер.
- В сервисе терминалов оплаты выполняется обработка платежа.
- От сервиса терминалов оплаты к сервису Boleto направляется информация о результате оплаты.
- От сервиса Boleto к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Boleto через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода Boleto необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;payment_currency
— код валюты платежа в формате ISO-4217 alpha-3;payment_amount
— сумма платежа в дробных единицах валюты;customer_id
— идентификатор пользователя в рамках проекта.
- Должен использоваться базовый минимум параметров:
project_id
,payment_id
,payment_currency
,payment_amount
,customer_id
. - Валютой платежа может быть только BRL или USD.
- Дополнительно должны передаваться следующие данные пользователя:
customer_first_name
иcustomer_last_name
— имя и фамилия пользователя;customer_email
— адрес электронной почты пользователя;customer_address
— почтовый адрес пользователя;customer_zip
— почтовый индекс пользователя;identify_doc_number
— номер документа пользователя, подтверждающего личность, должен содержать 11 цифр.
- Валютой платежа может быть только BRL или USD.
- Для предварительного выбора метода Boleto необходимо указывать код этого метода в параметре
force_payment_method
—boleto
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода Boleto должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и подпись.
{ "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "BRL", "customer_id": "customer1", "customer_first_name": "Paul", "customer_last_name": "Marques", "customer_email": "customer@example.com", "customer_address": "Avenida das Nações", "customer_zip": "123456", "identify_doc_number": "84887177100", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Рис.: Пример достаточного набора данных для запроса на оплату
{ "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "BRL", "customer_id": "customer1", "customer_first_name": "Paul", "customer_last_name": "Marques", "customer_email": "customer@example.com", "customer_address": "Avenida das Nações", "customer_zip": "123456", "identify_doc_number": "84887177100", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода Boleto используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 198
была проведена оплата в размере 1,00 BRL
.
Рис.: Пример данных из оповещения о проведении оплаты
{ "project_id": 198, "payment": { "id": "tet_boleto_2555", "type": "purchase", "status": "decline", "date": "2018-12-17T13:49:02+0000", "method": "boleto", "sum": { "amount": 100, "currency": "BRL" }, "description": "" }, "account": { "number": "20342583281" }, "customer": { "id": "1" "phone": "0123849512" }, "operation": { "id": 10785000002264, "type": "sale", "status": "decline", "date": "2018-12-17T13:49:02+0000", "created_date": "2018-12-17T13:48:58+0000", "request_id": "2da6493b62a13152562f465ecac9b2c893367f80f", "sum_initial": { "amount": 100, "currency": "BRL" }, "sum_converted": { "amount": 100, "currency": "BRL" }, "provider": { "id": 1166, "payment_id": "321", "date": "2018-12-17T13:49:01+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "p3HCoH1BL6LhKzH5NAlALKfzTodkwHYkSuP77c4caVo5fw==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
Рис.: Пример данных из оповещения об отклонении оплаты
{ "project_id": 198, "payment": { "id": "TEST_1545", "type": "purchase", "status": "decline", "date": "2018-12-18T08:47:45+0000", "method": "boleto", "sum": { "amount": 10000, "currency": "ARS" }, "description": "ECT_TEST_1545121924660" }, "account": { "number": "44444444444" }, "customer": { "id": "1" }, "errors": [ { "code": "2284", "message": "Currency rate not found", "description": "fatal: RATE_NOT_FOUND" } ], "operation": { "id": 18399000002318, "type": "sale", "status": "decline", "date": "2018-12-18T08:47:45+0000", "created_date": "2018-12-18T08:47:44+0000", "request_id": "42dd4e6c84a3ddb95b1f8966efa986b1b0bbda", "sum_initial": { "amount": 50000, "currency": "ARS" }, "sum_converted": { "amount": 50000, "currency": "ARS" }, "provider": { "id": 1166, "payment_id": "" }, "code": "2284", "message": "Currency rate not found" }, "signature": "hR0GFnmCqVp5/6hm+oYUyoiNht4HVTkWtMevKrjVw==" }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Для оплаты через Gate с использованием метода Boleto со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять оповещение от платёжной платформы с данными ваучера и инструкцией для отображения пользователю или с данными для перенаправления пользователя в сервис Boleto в зависимости от провайдера, обрабатывающего платёж).
- Принять оповещение о результате оплаты.
Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Gate. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Boleto.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
- В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис Boleto.
- В сервисе Boleto выполняется обработка запроса на оплату.
- От сервиса Boleto к платёжной платформе передаётся сгенерированный ваучер для оплаты в терминале или данные для перенаправления пользователя в сервис Boleto. В зависимости от провайдера, обрабатывающего платёж ваучер может быть действителен в течение 8 (но пользователь может совершить оплату в течение 30 дней, обратившись в банк) или 3 дней с момента получения.
- Данные ваучера или перенаправления передаются в веб-сервис.
- Ваучер и инструкция по оплате отображается пользователю в веб-сервисе или после перенаправления в сервисе Boleto. Статус платежа
awaiting customer action
илиawaiting redirect result
(в зависимости от провайдера, обрабатывающего платёж) остается до тех пор, пока пользователь не завершит оплату. - Пользователь завершает оплату в одном из доступных терминалов оплаты, используя полученный ваучер.
- В сервисе терминалов оплаты выполняется обработка платежа.
- От сервиса терминалов оплаты к сервису Boleto направляется информация о результате оплаты.
- От сервиса Boleto к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Boleto через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на оплаты с применением метода Boleto необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/voucher/boleto/sale
. Эта точка относится к группе /v2/payment/voucher/{payment_method}/sale. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа в дробных единицах валюты;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа;,first_name
— имя пользователя;,last_name
— фамилия пользователя;,email
— адрес электронной почты пользователя;,address
— почтовый адрес пользователя;,zip
— почтовый индекс пользователя;,identify
— объект, содержащий сведения о документе, подтверждающем личность:doc_number
— номер документа, подтверждающего личность, который должен состоять из 11 или 14 цифр;,
return_url
— URL для возврата пользователя к веб-сервису:success
— URL для возврата после проведенного платежа.
- Валютой платежа может быть только BRL или USD.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату с применением метода Boleto должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, URL для перенаправления, а также подпись.
{ "general": { "project_id": 580, "payment_id": "38202000002316", "signature": "h4ZxUifBNaLuvlYXyvBuqG/K0B9CjMCc2DbkDrk3qhLg==" }, "payment": { "amount": 10000, "currency": "USD", "description": "38202000002316" }, "customer": { "id": "589256", "email": "paul@mail.com", "first_name": "Paul", "last_name": "Marques", "address": "The street,23", "zip": "123456", "identify": { "doc_number": "84887177100" }, "ip_address": "192.0.2.0" }, "return_url": { "success": "example.com/success" } }
Рис.: Пример достаточного набора данных для запроса на оплату
{ "general": { "project_id": 580, "payment_id": "38202000002316", "signature": "h4ZxUifBNaLuvlYXyvBuqG/K0B9CjMCc2DbkDrk3qhLg==" }, "payment": { "amount": 10000, "currency": "USD", "description": "38202000002316" }, "customer": { "id": "589256", "email": "paul@mail.com", "first_name": "Paul", "last_name": "Marques", "address": "The street,23", "zip": "123456", "identify": { "doc_number": "84887177100" }, "ip_address": "192.0.2.0" }, "return_url": { "success": "example.com/success" } }
Формат промежуточных оповещений с даными для передачи пользователям
В зависимости от провайдера, обрабатывающего платеж, для завершения оплаты необходимо отобразить пользователям инструкцию с ваучером или перенаправить в сервис Boleto. Информация для создания отображаемой инструкции и генерации ваучера содержится в оповещении от платёжной платформы в объекте provider_extra_fields
поэтому прежде чем отобразить инструкцию и сформировать ваучер, надо принять и обработать такое оповещение:
ticket_barcode
— код для включения в штрих-код,ticket_company_name
— название компании получателя платежа,ticket_expiration_date
— дата и время истечения срока жизни ваучера,ticket_id
— идентификатор ваучера,ticket_number
— числовой код ваучер,ticket_provider_name
— название банка, который создает ваучер,ticket_type
— тип ваучера, может быть numeric, barcode или custom,image_url
— URL полной версии ваучера.
Рис.: Пример объекта provider_extra_fields
"provider_extra_fields" : { "doc_number" : "1234567812", "ticket_barcode" : "1000010009136517000100040000626788", "ticket_company_name" : "BRASIL LTDA", "ticket_expiration_date" : "2019-06-20T08:13:39+00:00", "ticket_id" : "344.775", "ticket_number" : "104991365817006267884978590000001000", "ticket_provider_name" : "caixa", "ticket_type" : "NUMERIC", "image_url": "http://example.com/payments/e7fdb20-5ac7-8583-00971" }
Для перенаправления пользователей от веб-сервиса мерчанта к сервису Boleto необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data
. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data
включаются следующие объекты и параметры:
body
— объект с данными для отправки в теле запроса;method
— параметр с указанием HTTP-метода отправки запроса (GET
илиPOST
);url
— параметр со ссылкой для перенаправления.
Рис.: Пример объекта redirect_data
"redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" }
Формат итоговых оповещений
Для оповещений о результатах оплат с применением метода Boleto используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 842
была проведена оплата в размере 100,00 USD
.
Рис.: Пример данных из оповещения о проведении оплаты
{ "project_id": 842, "payment": { "id": "EP8a3e-3e96", "type": "purchase", "status": "success", "date": "2019-06-03T12:09:38+0000", "method": "boleto", "sum": { "amount": 10000, "currency": "USD" }, "description": "" }, "operation": { "id": 1001313740, "type": "sale", "status": "success", "date": "2019-06-03T12:09:38+0000", "created_date": "2019-06-03T12:08:52+0000", "request_id": "46b8b94eabf", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "provider": { "id": 1414, "payment_id": "9d7e3e16b6a5", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "hTnUho5lgWxu+wgKzmhLdjawf5d8PwovSQGtyFSH7OBlJ8bQ==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
Рис.: Пример данных из оповещения об отклонении оплаты
{ "project_id": 842, "payment": { "id": "EP2ea6-f489", "type": "purchase", "status": "decline", "date": "2019-06-03T12:14:18+0000", "method": "boleto", "sum": { "amount": 1000, "currency": "EUR" }, "description": "" }, "operation": { "id": 2001313740, "type": "sale", "status": "decline", "date": "2019-06-03T12:14:18+0000", "created_date": "2019-06-03T12:13:38+0000", "request_id": "d5978bf20bae024", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1414, "payment_id": "D-30006-7729dab9-3782-4c0a-8192-840622f63f08", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "eL+OigWVAgeT85JjOOUKYy+MkG9SCynp47KzdImN3tAy0kA==" }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу Boleto, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.