Платежи через сервис PIX

Обзор

Введение

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

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

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


Тип платёжного метода	банковские платежи
Платёжные инструменты	банковские счета
Регионы использования	BR
Валюты платежей	BRL, USD
Конвертация валют	на стороне Flashpay
Оплаты	+
Повторяемые оплаты	–
Полные возвраты	–
Частичные возвраты	–
Выплаты	+
Опротестования	–
Особенности	выполнение возвратов через платёжную платформу Flashpay не поддерживается, однако пользователи могут инициировать возвраты на стороне сервиса PIX в течение недели после проведения оплаты
Организация и стоимость подключения	по согласованию с курирующим менеджером Flashpay

Схема работы

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

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

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

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


	Суммы ¹
	минимум	максимум
Оплаты	*	*
Выплаты	*	*

Прим.:

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

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

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

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

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

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

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

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

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

Пользователь на стороне веб-сервиса инициирует оплату.
От веб-сервиса на заданный URL Flashpay передаётся запрос на проведение оплаты через Payment Page.
Запрос на проведение оплаты поступает в платёжную платформу.
В платёжной платформе обеспечивается приём запроса с проверкой наличия обязательных параметров и корректной подписи.
Осуществляется генерация Payment Page согласно настройкам проекта и параметрам вызова.
Пользователю отображается сгенерированная платёжная форма.
Пользователь выбирает платёжный метод «Платежи через сервис PIX».
Запрос на проведение оплаты с использованием сервиса PIX поступает в платёжную платформу.
В платёжной платформе обеспечиваются обработка полученного запроса и его отправка в сервис PIX.
На стороне сервиса PIX выполняется обработка запроса на оплату.
От сервиса PIX к платёжной платформе передаются данные для отображения платёжной инструкции пользователю.
Данные для отображения платёжной инструкции пользователю передаются к Payment Page.
Пользователю отображается платёжная инструкция.
Пользователь выполняет необходимые действия для оплаты согласно инструкции.
На стороне сервиса PIX выполняется обработка оплаты.
От сервиса PIX к платёжной платформе направляется уведомление о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
От платёжной платформы к Payment Page направляется результат проведения оплаты.
Результат оплаты отображается пользователю на Payment Page.

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

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

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

Должен использоваться базовый минимум параметров, обязательный для любого платежа:
- project_id — идентификатор проекта, полученный от Flashpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа в дробных единицах валюты;
- customer_id — идентификатор пользователя в рамках проекта.
Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
Дополнительно необходимо использовать следующие параметры:
- customer_first_name — имя пользователя;
- customer_last_name — фамилия пользователя;
- customer_email — адрес электронной почты пользователя;
- identify_doc_number — номер CPF (состоит из 11 цифр) или номер CNPJ (состоит из 14 цифр), который следует передавать только цифрами, без пробелов и знаков препинания. Актуальный номер следует уточнять у курирующего менеджера Flashpay.
Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений (подробнее — в статье Дополнение информации о платежах).
Для предварительного выбора метода «Платежи через сервис PIX» необходимо указывать в параметре force_payment_method код платёжного метода — pix.
Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 1234,
   "payment_id": "payment_47",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer_123",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "identify_doc_number": "12345678901",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Рис. 5. Пример достаточного набора данных для запроса на оплату

{
   "project_id": 1234,
   "payment_id": "payment_47",
   "payment_amount": 10000,
   "payment_currency": "USD",
   "customer_id": "customer_123",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "identify_doc_number": "12345678901",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

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

{
        "project_id": 1234,
        "payment": {
            "id": "payment_47",
            "type": "purchase",
            "status": "success",
            "date": "2024-12-07T19:08:45+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 140,
            "type": "sale",
            "status": "success",
            "date": "2024-12-07T19:08:45+0000",
            "created_date": "2024-12-07T19:08:05+0000",
            "request_id": "008d93f549b505e10ff1",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12552,
                "payment_id": "1635927056181",
                "auth_code": ""
            }
        },
        "signature": "Fq1XOK0JUSmtkVuVkogZ8lJS6GHWWHi4s3pZQqWBZkoVmZQ=="
    }

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

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

{
        "project_id": 1234,
        "payment": {
            "id": "payment_47",
            "type": "purchase",
            "status": "decline",
            "date": "2024-12-07T19:08:45+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 141,
            "type": "sale",
            "status": "decline",
            "date": "2024-12-07T19:08:45+0000",
            "created_date": "2024-12-07T19:08:05+0000",
            "request_id": "310df107ff9138b5e7c6ff8ff7585a025d",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "123456789",
                "auth_code": ""
            }
        },
        "signature": "euhyvIW9SLnjnRLPYmoPsH1yJVs+d1PzPyvPfX0ip3jqA=="
    }

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

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

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

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

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

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

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

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

Рис. 8. Проведение оплаты через Gate. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату с использованием метода «Платежи через сервис PIX».
От веб-сервиса на заданный URL Flashpay передаётся запрос на проведение оплаты через Gate.
Запрос на проведение оплаты поступает в платёжную платформу Flashpay.
В платёжной платформе обеспечивается приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
В платёжной платформе обеспечиваются дальнейшая обработка запроса (с проверкой согласованности параметров) и его отправка в сервис PIX.
На стороне сервиса PIX выполняется обработка запроса на оплату.
От сервиса PIX к платёжной платформе передаются данные для отображения платёжной инструкции пользователю.
От платёжной платформы к веб-сервису направляется оповещение с данными для отображения платёжной инструкции пользователю.
Пользователю на стороне веб-сервиса отображается платёжная инструкция.
Пользователь выполняет необходимые действия для оплаты согласно инструкции.
На стороне сервиса PIX выполняется обработка оплаты.
От сервиса PIX к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

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

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

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

Для инициирования каждой оплаты должен использоваться POST-запрос к конечной точке /v2/payment/pix/sale.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от Flashpay при интеграции;
  - payment_id — идентификатор платежа, уникальный в рамках проекта;
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в статье Работа с подписью к данным);
- payment — объект, содержащий сведения о платеже:
  - amount — сумма платежа в дробных единицах валюты;
  - currency — код валюты платежа в формате ISO-4217 alpha-3;
- customer — объект, содержащий сведения о пользователе:
  - ip_address — IP-адрес, актуальный для инициируемого платежа;
  - first_name — имя пользователя;
  - last_name — фамилия пользователя;
  - id — идентификатор, уникальный в рамках проекта;
  - email — адрес электронной почты пользователя;
  - day_of_birth — дата рождения пользователя в формате ДД-ММ-ГГГГ;
  - account_id — идентификатор pixkey, задаваемый пользователем в сервисе «Платежи через сервис PIX»; этим идентификатором может быть номер CPF, номер EVP, адрес электронной почты или номер телефона;
  - identify — объект, содержащий сведения о документе, подтверждающем личность пользователя:
    - doc_number — номер CPF (состоит из 11 цифр) или номер CNPJ (состоит из 14 цифр), который следует передавать только цифрами, без пробелов и знаков препинания. Актуальный номер следует уточнять у курирующего менеджера Flashpay.
Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

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

Рис. 9. Пример достаточного набора данных для запроса на оплату

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

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

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

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

Рис. 10. Пример массива display_data

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

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

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

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

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

{
        "project_id": 1234,
        "payment": {
            "id": "payment_47",
            "type": "purchase",
            "status": "success",
            "date": "2024-12-07T19:08:45+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 140,
            "type": "sale",
            "status": "success",
            "date": "2024-12-07T19:08:45+0000",
            "created_date": "2024-11-03T08:10:13+0000",
            "request_id": "008d93f549b505e10ff1",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12552,
                "payment_id": "1635927056181",
                "auth_code": ""
            }
        },
        "signature": "Fq1XOK0JUSmtkVuVkogZ8lJS6GHWWHi4s3pZQqWBZkoVmZQ=="
    }

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

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

{
        "project_id": 1234,
        "payment": {
            "id": "payment_47",
            "type": "purchase",
            "status": "decline",
            "date": "2024-12-07T19:08:45+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 141,
            "type": "sale",
            "status": "decline",
            "date": "2024-12-07T19:08:45+0000",
            "created_date": "2024-12-07T19:08:05+0000",
            "request_id": "310df107ff9138b5e7c6ff8ff7585a025d",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "123456789",
                "auth_code": ""
            }
        },
        "signature": "euhyvIW9SLnjnRLPYmoPsH1yJVs+d1PzPyvPfX0ip3jqA=="
    }

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

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

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

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

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

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

Рис. 13. Проведение выплаты через Gate. Описание шагов

Пользователь на стороне веб-сервиса инициирует выплату через «Платежи через сервис PIX».
От веб-сервиса на заданный URL Flashpay передаётся запрос на проведение выплаты через Gate.
Запрос на проведение выплаты поступает в платёжную платформу.
Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности, подробнее — в разделе Формат ответа.
В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис PIX.
На стороне сервиса PIX выполняется обработка платежа.
От сервиса PIX к платёжной платформе направляется синхронный ответ с результатом.
От платёжной платформы к веб-сервису направляется оповещение о результате.
От веб-сервиса пользователю направляется результат выплаты.

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

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

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

Для инициирования каждой выплаты должен использоваться POST-запрос к конечной точке /v2/payment/pix/payout.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от Flashpay при интеграции;
  - payment_id — идентификатор платежа, уникальный в рамках проекта;
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в статье Использование подписи к данным);
- payment — сведения о платеже:
  - amount — сумма выплаты в дробных единицах валюты;
  - currency — код валюты платежа в формате ISO-4217 alpha-3;
- customer — объект, содержащий сведения о пользователе:
  - ip_address — IP-адрес, актуальный для инициируемой выплаты.
  - first_name — имя пользователя.
  - last_name — фамилия пользователя.
  - email — адрес электронной почты пользователя.
  - phone — номер телефона пользователя.
  - day_of_birth — дата рождения пользователя в формате ДД-ММ-ГГГГ.
  - address — адрес пользователя (улица, номер дома, номер корпуса, номер квартиры и т. д.); должен содержать только буквы, цифры и знаки пробела.
  - account_id — идентификатор pixkey, задаваемый пользователем в сервисе «Платежи через сервис PIX»; этим идентификатором может быть номер CPF, номер EVP, номер CNPJ, адрес электронной почты или номер телефона. Если значение pixkey — номер телефона, то его следует передавать со знаком +, без пробелов и знаков препинания. Если значение pixkey — номер документа (CPF/CNPJ), то его следует передавать только цифрами, без пробелов и знаков препинания. Актуальный идентификатор для запроса следует уточнять у курирующего менеджера Flashpay.
  - id — идентификатор, уникальный в рамках проекта.
  - identify — объект, содержащий сведения о документе, подтверждающем личность пользователя:
    - doc_number — номер CPF, состоит из 11 цифр.
- account — объект, содержащий сведения о банковском счёте пользователя:
  - number — номер счёта пользователя;
  - bank_id — идентификатор банка;
  - bank_branch_code — код филиала банка пользователя;
  - type — тип банковского счёта пользователя. Тип счёта должен соответствовать номеру счёта, который передается в параметре number, иначе платёж отклоняется провайдером. Возможные значения: Savings Bank и Checking Account.
Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "3zjYFq8JuRey87Q4OyuWs1Kaa+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "USD"
    },
    "customer": {
        "ip_address": "192.0.2.0",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@example.com",
        "phone": "1234567890123",
        "address": "20 Baltimore str.",
        "city": "London",
        "day_of_birth": "22-11-2000",
        "account_id": "123456789",
        "id": "customer_123",
        "identify": {
            "doc_number": "12345678901"
        }
    },
    "account": {
        "number": "123456",
        "type": "Savings Bank",
        "bank_id": 57111,
        "bank_branch_code": "123456"
    }
}

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

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "3zjYFq8JuRey87Q4OyuWs1Kaa+K4SAyamNnFVg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "USD"
    },
    "customer": {
        "ip_address": "192.0.2.0",
        "first_name": "John",
        "last_name": "Doe",
        "email": "example@example.com",
        "phone": "1234567890123",
        "address": "20 Baltimore str.",
        "city": "London",
        "day_of_birth": "22-11-2000",
        "account_id": "123456789",
        "id": "customer_123",
        "identify": {
            "doc_number": "12345678901"
        }
    },
    "account": {
        "number": "123456",
        "type": "Savings Bank",
        "bank_id": 57111,
        "bank_branch_code": "123456"
    }
}

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

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

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

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

{
        "project_id": 1234,
        "payment": {
            "id": "payment_47",
            "type": "payout",
            "status": "success",
            "date": "2024-12-07T19:08:45+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 142,
            "type": "payout",
            "status": "success",
            "date": "2024-12-07T19:08:45+0000",
            "created_date": "2024-12-07T19:08:05+0000",
            "request_id": "efe84ccebf77b57dd76f43970",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 12345,
                "payment_id": "12345678909",
                "auth_code": ""
            }
        },
        "signature": "lW9TpyiTQBMVa5dRBGC4geg5wneA=="
    }

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

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

{
        "project_id": 1234,
        "payment": {
            "id": "payment_47",
            "type": "payout",
            "status": "decline",
            "date": "2024-12-07T19:08:45+0000",
            "method": "pix",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": ""
        },
        "customer": {
            "id": "customer_123"
        },
        "operation": {
            "id": 143,
            "type": "payout",
            "status": "decline",
            "date": "2024-12-07T19:08:45+0000",
            "created_date": "2024-12-07T19:08:05+0000",
            "request_id": "a767d408f85ee594048bbe",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 12345,
                "payment_id": "12345678909877",
                "auth_code": ""
            }
        },
        "signature": "J55CcQzHzjl2hvtoPvwfdKHLfUCmX52swTo/0ZljkMsxw=="
    }

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

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

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

Выплаты через Dashboard

При использовании интерфейса Dashboard можно проводить одиночные и массовые выплаты методом «Платежи через сервис PIX» с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.

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

При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры выплат — должны соответствовать требованиям, представленным в разделе Выплаты через Gate этой статьи (за исключением пункта о подписи).

Более подробная информация о проведении выплат через Dashboard представлена в отдельной статье.

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

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

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

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