Oxxo
Обзор
Введение
Oxxo — метод, позволяющий проводить платежи в мексиканских песо и долларах США с использованием ваучеров в Мексике. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты.
В этой статье представлена информация о работе с методом Oxxo: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | платежи через точки оплаты |
---|---|
Платёжные инструменты | ваучеры |
Регионы использования | MX |
Валюты платежей | MXN, USD |
Конвертация валют | – |
Разовые оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | – |
Частичные возвраты | – |
Выплаты | – |
Опротестования | – |
Особенности |
|
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием метода Oxxo задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса Oxxo.
Основные операции
Для проведения платежей и выполнения операций с использованием метода Oxxo могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок).
Сценарии использования
Проведение оплат с использованием метода Oxxo осуществляется с перенаправлением пользователей к сервису Oxxo.
Рис.: Оплата через Payment Page
Рис.: Оплата через Gate
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода Oxxo со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Payment Page. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
- Запрос на проведение оплаты поступает в платёжную платформу.
- В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
- Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
- Пользователю отображается платёжная форма.
- Пользователь выбирает для оплаты метод Oxxo.
- Пользователю отображается платёжная форма, соответствующая запросу.
- Пользователь вводит данные для оплаты.
- В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Oxxo.
- В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Oxxo.
- В сервисе Oxxo выполняется обработка запроса на оплату.
- От сервиса Oxxo к платёжной платформе передаются данные для перенаправления пользователя к сервису Oxxo.
- Данные для перенаправления пользователя передаются к Payment Page.
- Пользователю на Payment Page отображается ссылка для перенаправления в сервис Oxxo.
- Пользователь перенаправляется к сервису Oxxo.
- Пользователю отображается сгенерированный ваучер со штрихкодом для оплаты в терминале. Статус платежа
awaiting redirect result
остается до тех пор, пока пользователь не завершит оплату. В зависимости от провайдера, обрабатывающего платёж ваучер может быть действителен в течение 10 (но пользователь может совершить оплату в течение 30 дней, обратившись в банк) или 3 дней с момента получения. - Пользователь завершает оплату в одном из доступных терминалов оплаты, предъявляя полученный ваучер.
- В сервисе терминалов оплаты происходит обработка платежа.
- От сервиса терминалов к сервису Oxxo направляется информация о результате оплаты.
- От сервиса Oxxo к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Oxxo через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода Oxxo необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
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
. - Валютой платежа может быть только MXN или USD.
- Дополнительно должны передаваться следующие данные пользователя:
customer_first_name
иcustomer_last_name
— имя и фамилия пользователя;customer_email
— адрес электронной почты пользователя;identify_doc_number
— номер документа пользователя, подтверждающего личность, который должен содержать от 10 до 18 цифр.
- Валютой платежа может быть только MXN или USD.
- Для предварительного выбора метода Oxxo необходимо указывать код этого метода в параметре
force_payment_method
—oxxo
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода Oxxo должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и подпись.
{ "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "MXN", "customer_id": "customer1", "customer_first_name": "Guido", "customer_last_name": "Marques", "customer_email": "customer@example.com", "identify_doc_number": "12345678901", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Рис.: Пример достаточного набора данных для запроса на оплату
{ "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "MXN", "customer_id": "customer1", "customer_first_name": "Guido", "customer_last_name": "Marques", "customer_email": "customer@example.com", "identify_doc_number": "12345678901", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }
Формат оповещений
Для оповещений о результатах оплат с применением метода Oxxo используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 842
была проведена оплата в размере 100,00 USD
.
Рис.: Пример данных из оповещения о проведении оплаты
{ "project_id": 842, "payment": { "id": "EP8a3e-3e96", "type": "purchase", "status": "success", "date": "2019-06-03T12:09:38+0000", "method": "oxxo", "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+wgKzmhLdjawVQGtyFSH7OBlJ8bQ==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
Рис.: Пример данных из оповещения об отклонении оплаты
{ "project_id": 842, "payment": { "id": "EP2ea6-f489", "type": "purchase", "status": "decline", "date": "2019-06-03T12:14:18+0000", "method": "oxxo", "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+OigWVAgeT85JjOOUIkg5PyKnp47KzdImN3tAy0kA==" }
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Для проведения оплаты через Gate с использованием метода Oxxo со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису Oxxo.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
Рис.: Проведение оплаты через Gate. Описание шагов
- Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Oxxo.
- От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
- Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
- В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
- В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис Oxxo.
- В сервисе Oxxo выполняется обработка запроса на оплату.
- От сервиса Oxxo к платёжной платформе передаются данные для перенаправления пользователя к сервису Oxxo.
- От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису Oxxo.
- Пользователю отображается ссылка для перенаправления в сервис Oxxo.
- Пользователь перенаправляется в сервис Oxxo.
- Пользователю отображается сгенерированный ваучер со штрихкодом для оплаты в терминале. Статус платежа
awaiting redirect result
остается до тех пор, пока пользователь не завершит оплату. В зависимости от провайдера, обрабатывающего платёж ваучер может быть действителен в течение 10 (но пользователь может совершить оплату в течение 30 дней, обратившись в банк) или 3 дней с момента получения. - Пользователь завершает оплату в одном из доступных терминалов оплаты, предъявляя полученный ваучер.
- В сервисе терминалов оплаты выполняется обработка платежа.
- От сервиса терминалов оплаты к сервису Oxxo направляется информация о результате оплаты.
- От сервиса Oxxo к платёжной платформе направляется информация о результате оплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
- На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом Oxxo через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на оплаты с применением метода Oxxo необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/voucher/oxxo/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
— адрес электронной почты пользователя;,identify
— объект, содержащий сведения о документе, подтверждающем личность:doc_number
— номер документа, подтверждающего личность, который должен содержать от 10 до 18 цифр.
- Валютой платежа может быть только MXN или USD.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату с применением метода Oxxo должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, а также подпись.
{ "general": { "project_id": 580, "payment_id": "38202000002316", "signature": "h4ZxUifBNaLuvlYXyvBuqGOFdK0B9CjMCc2DbkDrk3qhLg==" }, "payment": { "amount": 10000, "currency": "USD", "description": "38202000002316" }, "customer": { "id": "589256", "email": "Paul@mail.com", "first_name": "Paul", "last_name": "Marques", "identify": { "doc_number": "84887177100" }, "ip_address": "192.0.2.0" } }
Рис.: Пример достаточного набора данных для запроса на оплату
{ "general": { "project_id": 580, "payment_id": "38202000002316", "signature": "h4ZxUifBNaLuvlYXyvBuqGOFdK0B9CjMCc2DbkDrk3qhLg==" }, "payment": { "amount": 10000, "currency": "USD", "description": "38202000002316" }, "customer": { "id": "589256", "email": "Paul@mail.com", "first_name": "Paul", "last_name": "Marques", "identify": { "doc_number": "84887177100" }, "ip_address": "192.0.2.0" } }
Формат промежуточных оповещений для перенаправления пользователей
Для перенаправления пользователей от веб-сервиса мерчанта к сервису Oxxo при проведении каждого платежа с использованием метода Oxxo необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data
. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data
включаются следующие объекты и параметры:
body
— объект с данными для отправки в теле запроса;method
— параметр с указанием HTTP-метода отправки запроса (GET
илиPOST
);url
— параметр со ссылкой для перенаправления.
Рис.: Пример объекта redirect_data
"redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" }
Формат итоговых оповещений
Для оповещений о результатах оплат с применением метода Oxxo используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 842
была проведена оплата в размере 100,00 USD
.
Рис.: Пример данных из оповещения о проведении оплаты
{ "project_id": 842, "payment": { "id": "EP8a3e-3e96", "type": "purchase", "status": "success", "date": "2019-06-03T12:09:38+0000", "method": "oxxo", "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+wgKzmhLdjawVTf53e5d8PwovSQGtyFSH7OBlJ8bQ==" }
В следующем примере оповещение свидетельствует об отклонённой оплате.
Рис.: Пример данных из оповещения об отклонении оплаты
{ "project_id": 842, "payment": { "id": "EP2ea6-f489", "type": "purchase", "status": "decline", "date": "2019-06-03T12:14:18+0000", "method": "oxxo", "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+OigWVAgeT85JjOOUIlKYy+MkG9SCynp47KzdImN3tAy0kA==" }
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу Oxxo, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.