Oxxo

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

Схема работы

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

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

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

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

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

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

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

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

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

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

Информация о формате запросов и параметрах вызова 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_method — oxxo.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page.
6. После указания целевых параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.

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

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 используется стандартный формат, описание которого представлено в разделе Оповещения.

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация о выполнении операций

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

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

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

Информация о формате запросов и параметрах инициализации оплат методом 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, в том числе с помощью аналитических панелей на вкладке Analytics.

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

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

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