Oxxo

Обзор

Oxxo — платёжный метод, который поддерживает получение оплат от пользователей с использованием ваучеров. Оплаты выполняются через Payment Page и Gate.

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

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

Схема работы

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



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

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

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

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

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

Рис.: Оплата через Payment Page



Рис.: Оплата через Gate



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

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

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

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



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

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

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

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

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

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

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

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

EPayWidget.run(
    { payment_id: 'X03936', 
      payment_amount: 10000, 
      payment_currency: 'MXN', 
      project_id: 0,    
      customer_id: 'customer1',  
      customer_first_name: 'Guido',
      customer_last_name: 'Marques',
      customer_email: 'marques@gmail.com',
      identify_doc_number: '1234567890',
      signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASUkDJrOcZzUCwX6R\/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+wgKzmhLdjawVTrcq9KiR/u/xc3f53e5d8PwovSQGtyFSH7OBlJ8bQ=="
    }

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

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

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

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

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

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

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

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

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay.
  2. Осуществить перенаправление пользователя в сервис Oxxo.
  3. Принять оповещение о результате оплаты.


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

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

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

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

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

  1. Должен использоваться запрос /v2/payment/voucher/oxxo/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 — адрес электронной почты,
      • identify — объект, содержащий сведения о документе, подтверждающем личность:
        • doc_number — номер документа, подтверждающего личность, который должен содержать от 10 до 18 цифр,
    • payment — сведения о платеже:
      • amount — сумма платежа в минорных единицах; в зависимости от провайдера, обрабатывающего платёж, может потребоваться передавать целочисленное значение, подробности следует уточнять у курирующего менеджера ECommPay,
      • currency — валюта платежа в формате ISO-4217 alpha-3.
  3. Валютой платежа может быть только MXN или USD.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

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

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

{
    general: {
        project_id: 580,
        payment_id: "38202000002316",
        signature: "h4ZxUifBNaLuvlYXyvBuqG/tRr67tWadwpXnBeF+iSR0K5OFdK0B9CjMCc2DbkDrk3qhLg=="
    },
    customer: {
        id: "589256",
        email: "Paul@mail.com",
        first_name: "Paul",
        last_name: "Marques",
        identify: {
            doc_number: "84887177100"
        },
        ip_address: "66.249.64.45"
    },
    payment: {
        amount: 10000,
        currency: "USD",
        description: "38202000002316"
    }
}

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

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

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

"redirect_data" : {
			"body" : [	],
			"method" : "GET",
			"url" : "http://test/redirect_url/13831b619cd5ae5583c43b4ea59d418c"
		},

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

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

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

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

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

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

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

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

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

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

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

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

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