PIX

Введение

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

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

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

Схема работы

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

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

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

При работе с методом PIX, независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.

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

Проведение оплат с использованием метода PIX осуществляется с отображением платёжной инструкции, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.

Общие сценарии проведения оплат можно представить следующим образом.

Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как оплаты по платёжным ссылкам) сценарии выполнения операций методом PIX соответствуют специфике этих возможностей.

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

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

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

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

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

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

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. Дополнительно необходимо использовать следующие параметры:
   • customer_first_name — имя пользователя;
   • customer_last_name — фамилия пользователя;
   • customer_email — адрес электронной почты пользователя (может не указываться, если указывается параметр customer_phone);
   • customer_phone — номер телефона пользователя (может не указываться, если указывается параметр customer_email);
   • identify_doc_number — CPF (Cadastro de Pessoas Físicas, номер налогоплательщика, присвоенный физическому лицу; из 11 цифр) или CNPJ (Cadastro Nacional da Pessoa Jurídica, номер налогоплательщика, присвоенный юридическому лицу; из 14 цифр).
4. Для предварительного выбора метода PIX необходимо указывать в параметре force_payment_method код платёжного метода — pix.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением метода PIX должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и подпись, а также может содержать различные дополнительные параметры.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "BRL",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johnson@example.com,
   "identify_doc_number": "12345678901",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 10000,
   "payment_currency": "BRL",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johnson@example.com,
   "identify_doc_number": "12345678901",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

Для оповещений о результатах оплат с применением метода PIX используется типовой формат, описание которого представлено в статье Работа с оповещениями (подробнее).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 312 была проведена оплата в размере 100,00 BRL.

{
        "project_id": 312,
        "payment": {
            "id": "9582",
            "type": "purchase",
            "status": "success",
            "date": "2021-11-03T08:11:24+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 140,
            "type": "sale",
            "status": "success",
            "date": "2021-11-03T08:11:24+0000",
            "created_date": "2021-11-03T08:10:13+0000",
            "request_id": "008d93f549b505e10ff1",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12552,
                "payment_id": "1635927056181",
                "auth_code": ""
            }
        },
        "signature": "Fq1XOK0JUSmtkVuVkogZ8lJS6GHWWHi4s3pZQqWBZkoVmZQ=="
    }

В следующем примере оповещение свидетельствует о том, что оплата была отклонена.

{
        "project_id": 312,
        "payment": {
            "id": "9583",
            "type": "purchase",
            "status": "decline",
            "date": "2021-11-03T08:16:19+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 141,
            "type": "sale",
            "status": "decline",
            "date": "2021-11-03T08:16:19+0000",
            "created_date": "2021-11-03T08:15:43+0000",
            "request_id": "310df107ff9138b5e7c6ff8ff7585a025d",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "123456789",
                "auth_code": ""
            }
        },
        "signature": "euhyvIW9SLnjnRLPYmoPsH1yJVs+d1PzPyvPfX0ip3jqA=="
    }

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

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

• Быстрый старт и Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Проведение оплат — о том, как проводить разовые оплаты с незамедлительным списанием средств через Payment Page.
• Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

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

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

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

Полная схема проведения оплаты выглядит следующим образом.

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

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

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

1. Для инициирования каждой оплаты должен использоваться POST-запрос к конечной точке /v2/payment/pix/sale.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в статье Работа с подписью к данным);
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес, актуальный для инициируемого платежа;
     • first_name — имя пользователя;
     • last_name — фамилия пользователя;
     • id — идентификатор, уникальный в рамках проекта;
     • email — адрес электронной почты пользователя (может не указываться, если указывается параметр phone);
     • phone — номер телефона пользователя (может не указываться, если указывается параметр email);
     • identify — объект, содержащий сведения о документе, подтверждающем личность пользователя:
       • doc_number — CPF (Cadastro de Pessoas Físicas, номер налогоплательщика, присвоенный физическому лицу; из 11 цифр) или CNPJ (Cadastro Nacional da Pessoa Jurídica, номер налогоплательщика, присвоенный юридическому лицу; из 14 цифр).
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода PIX должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, подпись, а также может содержать различные дополнительные параметры.

{
    "general": {
        "project_id": 312,
        "payment_id": "9582",
        "signature": "3zjYFq8JuReyN4sF6x4Um+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "BRL"
    }
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "customer1",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@example.com",
        "identify": {
            "doc_number": "12345678901"
        }
    }
}

{
    "general": {
        "project_id": 312,
        "payment_id": "9582",
        "signature": "3zjYFq8JuReyN4sF6x4Um+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "BRL"
    }
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "customer1",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@example.com",
        "identify": {
            "doc_number": "12345678901"
        }
    }
}

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

Для перенаправления пользователей от веб-сервиса мерчанта к сервису PIX при проведении каждого платежа с использованием метода PIX необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data включаются следующие объекты и параметры:

• body — объект с данными для отправки в теле запроса;
• method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
• url — параметр со ссылкой для перенаправления.

  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }

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

Для итоговых оповещений об оплатах с применением метода PIX используется типовой формат, описание которого представлено в статье Работа с оповещениями (подробнее).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 312 была проведена оплата в размере 100,00 BRL.

{
        "project_id": 312,
        "payment": {
            "id": "9582",
            "type": "purchase",
            "status": "success",
            "date": "2021-11-03T08:11:24+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 140,
            "type": "sale",
            "status": "success",
            "date": "2021-11-03T08:11:24+0000",
            "created_date": "2021-11-03T08:10:13+0000",
            "request_id": "008d93f549b505e10ff1",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12552,
                "payment_id": "1635927056181",
                "auth_code": ""
            }
        },
        "signature": "Fq1XOK0JUSmtkVuVkogZ8lJS6GHWWHi4s3pZQqWBZkoVmZQ=="
    }

В следующем примере оповещение свидетельствует о том, что оплата была отклонена.

{
        "project_id": 312,
        "payment": {
            "id": "9583",
            "type": "purchase",
            "status": "decline",
            "date": "2021-11-03T08:16:19+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 141,
            "type": "sale",
            "status": "decline",
            "date": "2021-11-03T08:16:19+0000",
            "created_date": "2021-11-03T08:15:43+0000",
            "request_id": "310df107ff9138b5e7c6ff8ff7585a025d",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "123456789",
                "auth_code": ""
            }
        },
        "signature": "euhyvIW9SLnjnRLPYmoPsH1yJVs+d1PzPyvPfX0ip3jqA=="
    }

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

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

• Быстрый старт и Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
• Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

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

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

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

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

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

1. Для инициирования каждой выплаты должен использоваться POST-запрос к конечной точке /v2/payment/pix/payout.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в статье Использование подписи к данным);
   • payment — сведения о платеже:
     • amount — сумма выплаты в дробных единицах валюты;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес, актуальный для инициируемой выплаты;
     • first_name — имя пользователя;
     • last_name — фамилия пользователя;
     • email — адрес электронной почты пользователя (может не указываться, если указывается параметр phone);
     • phone — номер телефона пользователя (может не указываться, если указывается параметр email);
     • country — код страны пользователя в формате ISO 3166-1 alpha-2;
     • day_of_birth — дата рождения пользователя в формате ДД-ММ-ГГГГ;
     • id — идентификатор, уникальный в рамках проекта;
     • identify — объект, содержащий сведения о документе, подтверждающем личность пользователя:
       • doc_number — CPF (Cadastro de Pessoas Físicas, номер налогоплательщика, присвоенный физическому лицу; из 11 цифр) или CNPJ (Cadastro Nacional da Pessoa Jurídica, номер налогоплательщика, присвоенный юридическому лицу; из 14 цифр);
   • account — объект, содержащий сведения о счёте пользователя:
     • number — номер счёта.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на выплату с применением метода PIX должен содержать идентификатор проекта, базовые сведения о платеже (его идентификатор, сумму и код валюты), информацию о пользователе, а также подпись.

{
    "general": {
        "project_id": 312,
        "payment_id": "f8827",
        "signature": "3zjYFq8JuRey87Q4OyuWs1KaaWIHaNUPcN4sF6x4Um+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "BRL"
    },
    "customer": {
        "ip_address": "127.0.0.1",
        "first_name": "John",
        "last_name": "Doe",
        "country": "BR",
        "email": "example@xmpl.com",
        "day_of_birth": "22-11-2000",
        "id": "customer_123",
        "identify": {
            "doc_number": "12345678901"
        }
    },
    "account": {
        "number": "S0Pkonh1Lr2E"
  }
}

{
    "general": {
        "project_id": 312,
        "payment_id": "f8827",
        "signature": "3zjYFq8JuRey87Q4OyuWs1KaaWIHaNUPcN4sF6x4Um+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "BRL"
    },
    "customer": {
        "ip_address": "127.0.0.1",
        "first_name": "John",
        "last_name": "Doe",
        "country": "BR",
        "email": "example@xmpl.com",
        "day_of_birth": "22-11-2000",
        "id": "customer_123",
        "identify": {
            "doc_number": "12345678901"
        }
    },
    "account": {
        "number": "S0Pkonh1Lr2E"
  }
}

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

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

В следующем примере в оповещении содержится информация о том, что в рамках проекта 312 проведена выплата в размере 100,00 BRL.

{
        "project_id": 312,
        "payment": {
            "id": "306081845",
            "type": "payout",
            "status": "success",
            "date": "2021-11-03T08:19:26+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 142,
            "type": "payout",
            "status": "success",
            "date": "2021-11-03T08:19:26+0000",
            "created_date": "2021-11-03T08:18:46+0000",
            "request_id": "efe84ccebf77b57dd76f43970",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12345,
                "payment_id": "12345678909",
                "auth_code": ""
            }
        },
        "signature": "lW9TpyiTQBMVa5dRBGC4geg5wneA=="
    }

В следующем примере оповещение свидетельствует о том, что выплата была отклонена.

{
        "project_id": 312,
        "payment": {
            "id": "306082355",
            "type": "payout",
            "status": "decline",
            "date": "2021-11-03T08:24:33+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "BRL"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 143,
            "type": "payout",
            "status": "decline",
            "date": "2021-11-03T08:24:33+0000",
            "created_date": "2021-11-03T08:23:56+0000",
            "request_id": "a767d408f85ee594048bbe",
            "sum_initial": {
                "amount": 10000,
                "currency": "BRL"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "BRL"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "12345678909877",
                "auth_code": ""
            }
        },
        "signature": "J55CcQzHzjl2hvtoPvwfdKHLfUCmX52swTo/0ZljkMsxw=="
    }

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

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

• Быстрый старт и Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Выплата — о том, как проводить выплаты через Gate.
• Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

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

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

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