Boleto

Обзор

Введение

Boleto — метод, позволяющий проводить платежи в бразильских реалах и долларах США с использованием ваучеров в Бразилии. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты.

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

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

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

Схема работы

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



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

Для проведения платежей и выполнения операций с использованием метода Boleto могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок).

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

Проведение оплат с использованием метода Boleto осуществляется с перенаправлением пользователей к сервису Boleto.

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

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

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

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



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

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

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

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

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

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

Таким образом, корректный запрос на открытие платёжной формы с применением метода 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 также могут быть полезны следующие материалы:

Оплаты через 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, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

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

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

  1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/voucher/boleto/sale. Эта точка относится к группе /v2/payment/voucher/{payment_method}/sale.
  2. В каждом запросе должны использоваться следующие объекты и параметры:
    • 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 для возврата после проведенного платежа.
  3. Валютой платежа может быть только BRL или USD.
  4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода 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 также могут быть полезны следующие материалы:

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

Для анализа информации о платежах и операциях, как в отдельности по методу Boleto, так и в совокупности с другими методами, можно использовать:

  • инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
  • отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
  • данные в формате JSON, получаемые по программным запросам через интерфейс Data API.

С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.