PIX

Введение

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

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

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

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

Схема работы

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

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

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

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

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

Пользовательский сценарий оплаты через Payment Page (в базовом варианте с выбором пользователем метода и перенаправлением с итоговой страницы платёжной формы к веб-сервису) выглядит следующим образом.

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

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

Для проведения оплаты через 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 — адрес электронной почты пользователя;
   • identify_doc_number — номер CPF, состоит из 11 цифр.

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

4. Для предварительного выбора метода PIX необходимо указывать код платёжного метода в параметре force_payment_method — pix.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Информация обо всех доступных параметрах приведена в разделе Параметры вызова платёжной формы.Дополнительно могут использоваться любые другие параметры из числа доступных для работы с 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": "Johnson",
   "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. Принять промежуточное оповещение от платёжной платформы и отобразить пользователю платёжную инструкцию.
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 — адрес электронной почты пользователя;
     • identify — объект, содержащий сведения о документе, подтверждающем личность пользователя:
       • doc_number — номер CPF, состоит из 11 цифр.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

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

Формат промежуточных оповещений для отображения платёжной инструкции

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

• type — тип передаваемых данных (в значении всегда передаётся qr_data);
• title — название передаваемых данных, которые необходимо отобразить пользователю (в значении всегда передаётся QR Code);
• data — строка, на основании которой на стороне веб-сервиса должен быть создан QR-код (в соответствии со стандартом ISO/IEC 18004:2015).

"display_data": [
    {
        "type": "qr_data",
        "title": "QR code",
        "data": "00020101com.br359a71a-0cad-4cb2-a937-a3fa5319a5252070503***63042BBF"
    }
]

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

Для оповещений о результатах оплат с применением метода 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.
• Работа с подписью — о том, как создавать и проверять подписи в запросах и оповещениях при взаимодействии с платёжной платформой.
• Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
• Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

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

Для проведения выплаты через 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 — адрес электронной почты пользователя;
     • day_of_birth — дата рождения пользователя в формате ДД-ММ-ГГГГ;
     • account_id — идентификатор pixkey, задаваемый пользователем в сервисе PIX; этим идентификатором может быть номер CPF или адрес электронной почты;
     • id — идентификатор, уникальный в рамках проекта;
     • identify — объект, содержащий сведения о документе, подтверждающем личность пользователя:
       • doc_number — номер CPF, состоит из 11 цифр.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
    "general": {
        "project_id": 312,
        "payment_id": "f8827",
        "signature": "3zjYFq8JuRey87Q4OyuWs1Kaa+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "BRL"
    }
    "customer": {
        "ip_address": "192.0.2.0",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@example.com",
        "day_of_birth": "22-11-2000",
        "account_id": "email@example.com",
        "id": "customer_123",
        "identify": {
            "doc_number": "12345678901"
        }
    }
}

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

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