Boleto

Обзор

Boleto — платёжный метод, который поддерживает получение оплат от пользователей с использованием ваучеров.

Характеристика

Тип платёжного метода платежи через точки оплаты
Платёжные инструменты ваучеры
Регионы использования Бразилия
Валюты платежей BRL, USD
Конвертация валют
Оплаты +
Выплаты
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности
  • в зависимости от провайдера, обрабатывающего платёж, срок действия ваучера для оплаты может быть:
    • 8 дней, но пользователь может совершить оплату в течение 30 дней, обратившись в банк
    • 3 дня
  • в зависимости от провайдера платежи могут быть целочисленными, за более подробной информацией следует обращаться к курирующему менеджеру ecommpay
Организация и стоимость подключения По согласованию с курирующим менеджером ecommpay

Схема работы

В проведении отдельного платежа с использованием Boleto задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства провайдера и терминалы оплаты.



Основные операции

Интерфейсы Суммы
Payment Page CMS Plug-ins Gate Dashboard Минимум Максимум
Оплаты + + * *

* Информацию об ограничениях сумм необходимо уточнять у курирующего менеджера ecommpay.

Сценарии использования

Проведение оплат с использованием метода Boleto включает в себя получение ваучера для оплаты через Payment Page или в веб-сервисе мерчанта и оплату с помощью этого ваучера в одном из терминалов.

Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежей, а также о том, что можно использовать для анализа информации о проведённых платежах и операциях, представлены далее.

Оплаты через Payment Page

Общая информация

Проведение оплаты с использованием метода Boleto со стороны веб-сервиса выполняется стандартным способом: с отправкой запроса, содержащего требуемые параметры и подпись, на рабочий URL Payment Page и с последующей обработкой этого запроса и приём оповещения о результате оплаты от платёжной платформы. При этом метод Boleto можно делать предварительно выбранным при вызове платёжной формы, подробнее в разделе Предварительный выбор платёжных методов. Полная схема проведения оплаты представлена далее.



Рис.: Проведение оплаты через Payment Page

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL передаётся запрос на открытие Payment Page.
  3. От Payment Page запрос перенаправляется в платёжную платформу ecommpay.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. Осуществляется генерация Payment Page согласно настройкам проекта и параметрам вызова.
  6. Пользователю отображается сгенерированная платёжная форма.
  7. Пользователь выбирает платёжный метод Boleto.
  8. Пользователю отображается платёжная форма, соответствующая запросу.
  9. Пользователь вводит персональные данные для оплаты.
  10. Запрос на проведение оплаты через Boleto поступает в платёжную платформу.
  11. Выполняются дальнейшая обработка запроса и его отправка в сервис Boleto.
  12. На стороне Boleto выполняется обработка запроса.
  13. От Boleto в платёжную платформу направляются сгенерированный ваучер для оплаты в терминале или данные для перенаправления пользователя в сервис Boleto. В зависимости от провайдера, обрабатывающего платёж ваучер может быть действителен в течение 8 (но пользователь может совершить оплату в течение 30 дней, обратившись в банк) или 3 дней с момента получения.
  14. Данные ваучера или перенаправления передаются в веб-сервис.
  15. Пользователю на Payment Page или после перенаправления в сервисе Boleto отображаются ваучер и инструкция для оплаты. Статус платежа awaiting customer action или awaiting redirect result (в зависимости от провайдера, обрабатывающего платёж) остается до тех пор, пока пользователь не завершит оплату.
  16. Пользователь завершает оплату в одном из доступных терминалов оплаты, используя полученный ваучер.
  17. В сервисе терминалов оплаты происходит обработка платежа.
  18. Сервис терминалов отправляет результат оплаты в сервис Boleto.
  19. Boleto перенаправляет ответ с результатом оплаты в платёжную платформу.
  20. От платёжной платформы ecommpay к веб-сервису направляется оповещение о результате платежа.
  21. От веб-сервиса пользователю направляется результат оплаты.

Информация о формате запросов и параметрах вызова Payment Page при работе с Boleto, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API — в отдельном разделе.

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

При формировании запросов на открытие платёжной формы с применением метода Boleto необходимо учитывать следующее:

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
    • payment_amount — сумма платежа в дробных единицах; в зависимости от провайдера, обрабатывающего платёж, может потребоваться передавать целочисленное значение, подробности следует уточнять у курирующего менеджера ecommpay;
    • customer_id — идентификатор пользователя в рамках проекта.
  2. Валютой платежа может быть только BRL или USD.
  3. Дополнительно должны передаваться следующие данные пользователя:
    • customer_first_name и customer_last_name — имя и фамилия;
    • customer_email — адрес электронной почты;
    • customer_address — почтовый адрес;
    • customer_zip — почтовый индекс;
    • identify_doc_number — номер документа, подтверждающего личность, должен содержать 11 цифр.
  4. Для предварительного выбора метода Boleto необходимо указывать код платёжного метода в параметре force_payment_methodboleto.
  5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page.
  6. После указания целевых параметров необходимо составить подпись. Подробную информацию см. в разделе Работа с подписью к данным.

Таким образом, корректный запрос на открытие платёжной формы с применением метода Boleto должен содержать идентификаторы проекта и платежа, данные пользователя, а также валюту и сумму платежа:

Рис.: Пример запроса на открытие Payment Page

EPayWidget.run(
    { payment_id: 'X03936', 
      payment_amount: 1000, 
      payment_currency: 'BRL', 
      project_id: 0,    
      customer_id: 'customer121',
      customer_first_name: 'Paul',
      customer_last_name: 'Marques',
      customer_email: 'paul@mail.com',
      customer_address: 'Avenida das Nações',
      customer_zip: '123456',
      identify_doc_number: '84887177100',
      signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO\/RLCvhtT4DqtVUk...=="
    }
)

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

Формат оповещений

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

В данном случае оповещение свидетельствует о том, что в рамках проекта 198 для пользователя 1 была успешно проведена оплата в размере 100,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": "2da6493b62a1315256e2e9c98a737b0ef4a723f7-f7402e3f2124fb0542f465ecac9b2c893367f80f",
            "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": "p3HCoH1BL6LhKzH5NAlAL4weJOK6maPj8NTHolhlBJDJLK/QtfVtfL2+cuRs7KfzTodkwHYkSuP77c4caVo5fw=="
    }

В этом примере оплата была отклонена из-за несоответствующей валюты операции.

Рис.: Пример оповещения об отказе в проведении оплаты

 {
        "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": "42dd4e6c84a3ddb95b1f8966e3c2e39ddaaa20a2-6d87502d662a2d2f3809253e39efa986b1b0bbda",
            "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/6hCVy9+bCUgQD/bc7RDrviZCKZnGoo7srY/3vcTALx88HGem+oYUyoiNht4HVTkWtMevKrjVw=="
    }

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

Оплаты через Gate

Общая информация

Для оплаты через Gate с использованием метода Boleto со стороны веб-сервиса необходимо:

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
  2. Принять оповещение от платёжной платформы с данными ваучера и инструкцией для отображения пользователю или с данными для перенаправления пользователя в сервис Boleto в зависимости от канала проведения платежа).
  3. Принять оповещение о результате оплаты.

Полная схема проведения оплаты представлена далее.



Рис.: Проведение оплаты через Gate

  1. Пользователь на стороне веб-сервиса инициирует оплату через Boleto.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис Boleto.
  7. На стороне Boleto выполняется обработка запроса на оплату.
  8. От Boleto в платёжную платформу направляются сгенерированный ваучер для оплаты в терминале или данные для перенаправления пользователя в сервис Boleto. В зависимости от провайдера, обрабатывающего платёж ваучер может быть действителен в течение 8 (но пользователь может совершить оплату в течение 30 дней, обратившись в банк) или 3 дней с момента получения.
  9. Данные ваучера или перенаправления передаются в веб-сервис.
  10. Ваучер и инструкция по оплате отображается пользователю в веб-сервисе или после перенаправления в сервисе Boleto. Статус платежа awaiting customer action или awaiting redirect result (в зависимости от провайдера, обрабатывающего платёж) остается до тех пор, пока пользователь не завершит оплату.
  11. Пользователь завершает оплату в одном из доступных терминалов оплаты, используя полученный ваучер.
  12. В сервисе терминалов оплаты происходит обработка платежа.
  13. Сервис терминалов отправляет результат оплаты в сервис Boleto.
  14. Boleto перенаправляет ответ с результатом оплаты в платёжную платформу.
  15. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  16. От веб-сервиса пользователю направляется результат оплаты.

Информация о формате запросов и параметрах инициализации оплат методом Boleto через Gate, а также о формате оповещений о результатах оплат приведена далее, общая информация о работе с API см. в разделе Работа с API.

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

При работе с запросами на оплаты с применением метода Boleto необходимо учитывать следующее:

  1. Должен использоваться запрос /v2/payment/voucher/boleto/sale, отправляемый методом POST. Этот запрос относится к группе запросов на проведение платежей с помощью ваучеров /v2/payment/voucher/{payment_method}/sale.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные сведения:
      • project_id — идентификатор проекта,
      • payment_id — идентификатор платежа,
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор,
      • ip_address — используемый IP-адрес,
      • first_name — имя,
      • last_name — фамилия,
      • email — адрес электронной почты,
      • address — почтовый адрес,
      • zip — почтовый индекс,
      • identify — объект, содержащий сведения о документе, подтверждающем личность:
        • doc_number — номер документа, подтверждающего личность, который должен состоять из 11 или 14 цифр,
    • payment — сведения о платеже:
      • amount — сумма платежа в дробных единицах; в зависимости от провайдера, обрабатывающего платёж, может потребоваться передавать целочисленное значение, подробности следует уточнять у курирующего менеджера ecommpay,
      • currency — валюта платежа в формате ISO-4217 alpha-3,
    • return_url — URL для возврата пользователя с сайта банка:
      • success — URL сайта для возврата после проведенного платежа.
  3. Валютой платежа может быть только BRL или USD.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода Boleto должен содержать идентификаторы проекта и платежа, подпись, информацию о пользователе, валюту и сумму платежа:

Рис.: Пример запроса на оплату

{
    general: {
        project_id: 580,
        payment_id: "38202000002316",
        signature: "h4ZxUifBNaLuvlYXyvBuqG/tRr67tWadwpXnBeF+iSR0K5OFdK0B9CjMCc2DbkDrk3qhLg=="
    },
    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: "66.249.64.45"
    },
    payment: {
        amount: 10000,
        currency: "USD",
        description: "38202000002316"
    }
}

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

В зависимсоти от канала, через который проходит платеж, для завершения оплаты необходимо отобразить пользователям инструкцию с ваучером или перенаправить в сервис 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 полной версии ваучера.

Для перенаправления пользователя от веб-сервиса в сервис Boleto необходимо принять оповещение от платёжной платформы, содержащее ссылку для перенаправления в параметре redirect_data.url и данные для отправки в теле запроса redirect_data.body, и использовать эти параметры при открытии HTML-страницы методом, указанным в redirect_data.method.

Далее приведены фрагменты примеров оповещения, содержащего необходимые данные.

"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://site.com/payments/e7fdb20-5ac7-8583-00971"
		}
 "redirect_data": {
                    "body": [],
                    "method": "GET",
                    "url": "https://example.com/en/payments/pay/0a0ffa98-98da-11eed6528"
                }

Формат оповещений

Для оповещений о результатах оплат с применением метода 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+wgKzmhLdjawVTrcq9KiR/u/xc3f5d8PwovSQGtyFSH7OBlJ8bQ=="
    }

В этом примере оплата была отклонена из-за несоответствующей валюты операции.

Рис.: Пример оповещения об отказе в проведении оплаты

 {
        "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+OigWVAgeT85JjOOUIkg5PyKCPYnwOT0lKYy+MkG9SCynp47KzdImN3tAy0kA=="
    }

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

Анализ результатов проведения платежей

Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода Boleto доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

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

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

  • Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
  • Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

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