PayPal
Обзор
Введение
PayPal — метод, позволяющий проводить платежи в разных валютах с использованием электронного кошелька в разных странах. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты в одну и две стадии, возвраты и выплаты.
В этой статье представлена информация о работе с методом PayPal: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | платежи с использованием электронных кошельков |
---|---|
Платёжные инструменты | электронные кошельки |
Регионы использования | в соответствии со списком |
Валюты платежей | AUD, BRL (только для Бразилии), CAD, CZK, DKK, EUR, HKD, HUF, INR (только для Индии), ILS, JPY, MYR (только для Малайзии), MXN, TWD, NZD, NOK, PHP, PLN, GBP, SGD, SEK, CHF, THB, USD |
Конвертация валют | на стороне ecommpay |
Оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | + |
Частичные возвраты | + |
Выплаты | + |
Опротестования | + |
Особенности |
|
Организация и стоимость подключения | в соответствии с порядком подключения, представленным далее, дополнительную информацию можно получить в ecommpay shop |
Порядок подключения
Для подключения этого платёжного метода мерчанту необходимо предоставить ecommpay права на проведение платежей с использованием сервиса PayPal от имени этого мерчанта. К таким правам относятся право на работу с оплатами и возвратами по ним и право на работу с выплатами. Чтобы предоставить любое из этих прав со стороны мерчанта необходимо:
- Сообщить курирующему менеджеру ecommpay о готовности подключить платёжный метод PayPal.
- Получить от ecommpay письмо со ссылкой для перехода на сайт сервиса PayPal.
- Перейти по ссылке и подтвердить право ecommpay на проведение платежей. При этом можно использовать существующую учётную запись мерчанта в PayPal или зарегистрировать новую.
- Получить от ecommpay письмо с уведомлением о подтверждении со стороны PayPal права проводить платежи с использованием указанного идентификатора мерчанта. После этого можно ожидать технической настройки на стороне ecommpay. Как правило, она выполняется в течение трёх дней.
- Получить от ecommpay письмо с подтверждением готовности проводить платежи с использованием метода PayPal. После этого можно начинать работу с использованием данного метода.
При необходимости любое из предоставленных прав может быть отозвано на стороне сервиса PayPal по согласованию с курирующим менеджером ecommpay.
Схема работы
В проведении отдельного платежа с использованием PayPal задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства PayPal.
Основные операции
Для проведения платежей и выполнения операций с использованием метода PayPal могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а возвраты и выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.
При работе с методом PayPal, независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.
Суммы, USD ¹ | Время ² | |||
---|---|---|---|---|
минимум | максимум | базовое | предельное | |
Оплаты | – | 60 000,00 * | 1 минута | 3 дня |
Выплаты | – | * | 1 минута | 30 дней |
Полные возвраты | – | – | – | 35 дней |
Частичные возвраты | – | – | – | 35 дней |
- Подробную информацию уточняйте у курирующего менеджера ecommpay.
- Базовое и предельное время определяются следующим образом:
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа (подробнее).
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.
Сценарии использования
Проведение оплат с использованием метода PayPal осуществляется с перенаправлением пользователей к сервису PayPal, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.
Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом PayPal соответствуют специфике этих возможностей.
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода PayPal со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом PayPal через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода PayPal необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;payment_currency
— код валюты платежа в формате ISO-4217 alpha-3;payment_amount
— сумма платежа в дробных единицах валюты;customer_id
— идентификатор пользователя в рамках проекта.
- Должен использоваться базовый минимум параметров:
project_id
,payment_id
,payment_currency
,payment_amount
,customer_id
. - Для предварительного выбора метода PayPal необходимо указывать код платёжного метода в параметре
force_payment_method
—paypal-wallet
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода PayPal должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор пользователя и подпись.
Детальная информация обо всех указанных параметрах приведена в отдельном разделе.
Формат оповещений
Для оповещений о результатах оплат с применением метода PayPal используется типовой формат, описание которого представлено в статье Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 210
была проведена оплата в размере 10,00 USD
.
В следующем примере оплата была отклонена.
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Введение
Оплаты через Gate с использованием метода PayPal могут проводиться двумя способами: напрямую через Gate API, а также с использованием SDK PayPal и Gate API. На стороне веб-сервиса различия между способами касаются отправки запросов и перенаправления пользователей, выбор конкретного способа остаётся за мерчантом.
Подготовка к проведению оплат с использованием SDK PayPal и Gate API
Перед проведением оплат с использованием SDK PayPal и Gate API с использованием метода PayPal со стороны веб-сервиса необходимо:
- Настроить использование SDK PayPal в соответствии с официальной документацией (https://developer.paypal.com/sdk/js/).
- Настроить отображение кнопки выбора этого платёжного метода на стороне веб-сервиса, также в соответствии с официальной документацией (https://developer.paypal.com/docs/checkout/standard/customize/standalone-buttons/, https://developer.paypal.com/demo/checkout/#/pattern/server).
- Подключить JavaScript-библиотеку PayPal в клиентской части веб-сервиса по ссылке следующего вида.
<script src="https://www.paypal.com/sdk/js?client-id=<CLIENT_ID>&merchant-id=<MERCHANT_ID>¤cy=USD"></script>
В этой ссылке используются переменные
<CLIENT_ID>
— идентификатор платёжной платформы ecommpay в сервисе PayPal, который определяется после предоставления ecommpay прав на проведение платежей от имени мерчанта, и<MERCHANT_ID>
— идентификатор мерчанта в сервисе PayPal.
Проведение оплат с использованием SDK PayPal и Gate API
После подготовки к использованию SDK PayPal для проведения каждой оплаты через этот SDK и Gate API с использованием метода PayPal со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay с использованием SDK PayPal.
- Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису PayPal.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом PayPal через SDK PayPal и Gate API, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Проведение оплат с прямым использованием Gate API
Для проведения оплаты через Gate с использованием метода PayPal со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису PayPal.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом PayPal с прямым использованием Gate API, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов на проведение оплат в одну стадию
Ипользуемые параметры
При работе с запросами на оплаты с применением метода PayPal (независимо от способа взаимодействия) необходимо учитывать следующее:
- В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа.
return_url
— объект, содержащий URL для перенаправления пользователя в веб-сервис:success
— URL для перенаправления пользователя в случае, когда он выполнил необходимые действия на стороне сервиса PayPal;,decline
— URL для перенаправления пользователя в случае, когда он не выполнил необходимые действия на стороне сервиса PayPal.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату в одну стадию с применением метода PayPal должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, URL для перенаправления и подпись.
Способ отправки запросов с использованием SDK PayPal и Gate API
При отправке запросов на инициирование оплат в одну стадию с использованием SDK PayPal и Gate API необходимо, чтобы запросы соответствовали формату, поддерживаемому SDK PayPal. При этом для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/paypal/sale
(относится к группе запросов /v2/payment/wallet/{payment_method}/sale).
В частном случае реализация функции отправки запроса может выглядеть следующим образом.
const test = { createOrder: function (data) { return fetch('https://api.ecommpay.com/v2/payment/wallet/paypal/sale', { method: 'POST', body: JSON.stringify(data), }); }, }; test.createOrder({ project_id: 123, payment_amount: '10000', ... })
Способ отправки запросов с прямым использованием Gate API
Для инициирования каждой оплаты в одну стадию должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/paypal/sale
. Эта точка относится к группе /v2/payment/wallet/{payment_method}/sale.
Формат запросов на блокировку средств
Используемые параметры
При работе с запросами на блокировку средств с применением метода PayPal (независимо от способа взаимодействия) необходимо учитывать следующее:
- В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа.
return_url
— объект, содержащий URL для перенаправления пользователя в веб-сервис:return
— URL для перенаправления пользователя на любом шаге оплаты.
- Также зависимости от типа бизнеса мерчанта можно передавать следующие параметры (информацию необходимо уточнять у курирующего менеджера ecommpay):
customer
— объект, содержащий сведения о пользователе:email
— адрес электронной почты;,first_name
— имя;,last_name
— фамилия;,country
— код страны в формате ISO 3166-1 alpha-2;,phone
— номер телефона.
additional_data
— объект, содержащий дополнительные данные о пользователе в сервисе мерчанта:sender_create_date
— время создания учётной записи пользователя в UTC+0 в формате ISO 8601 (например2022-01-25T10:15:30+00:00
);,payments_count
— количество платежей, проведённых веб-сервисом мерчанта для пользователя в течение предыдущих трёх месяцев до инициирования платежа;,pin_verification
— определяет, подтверждается ли при оплате подлинность пользователя с использованием PIN-кода (если да — в значении необходимо передаватьY
, если нет —N
);,face_id_verification
— определяет, подтверждается ли при оплате подлинность пользователя с использованием сканирования объёмно-пространственной формы лица (если да — в значении необходимо передаватьY
, если нет —N
);,additional_verification
— комбинация из четырёх индикаторов, отображающих выполнение ряда условий по подтверждению информации на стороне веб-сервиса в заданной последовательности. В качестве таких индикаторов должны использоваться цифры0
или1
(0
— не подтверждено,1
— подтверждено). К этим условиям относятся:- Номер телефона подтверждён;,
- Фотография, подтверждающая личность подтверждена;,
- Информация о платёжной карте подтверждена;,
- Информация о банковском счёте подтверждена.
Например:
1101
.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на блокировку средств с применением метода PayPal должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, URL для перенаправления, дополнительную информацию (по необходимости) и подпись.
Способ отправки запросов с использованием SDK PayPal и Gate API
При отправке запросов на блокировку средств с использованием SDK PayPal и Gate API необходимо, чтобы запросы соответствовали формату, поддерживаемому SDK PayPal. При этом для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/paypal/auth
(относится к группе запросов /v2/payment/wallet/{payment_method}/auth).
В частном случае реализация функции отправки запроса может выглядеть следующим образом.
const test = { createOrder: function (data) { return fetch('https://api.ecommpay.com/v2/payment/wallet/paypal/auth', { method: 'POST', body: JSON.stringify(data), }); }, }; test.createOrder({ project_id: 123, payment_amount: '10000', ... })
Способ отправки запросов с прямым использованием Gate API
Для блокировки средств по каждой оплате должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/paypal/auth
. Эта точка относится к группе /v2/payment/wallet/{payment_method}/auth.
Формат запросов на списание заблокированных средств
При работе с запросами на списание средств с применением метода PayPal необходимо учитывать следующее:
- Для инициирования каждого списания средств должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/wallet/paypal/capture
(относится к группе запросов /v2/payment/wallet/{payment_method}/capture). - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на списание заблокированных средств с применением метода PayPal должен содержать идентификаторы проекта и платежа, а также подпись.
Формат запросов на отмену блокировки средств
При работе с запросами на отмену блокировки средств с применением метода PayPal необходимо учитывать следующее:
- Для инициирования каждой отмены блокировки средств должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/wallet/paypal/cancel
(относится к группе запросов /v2/payment/wallet/{payment_method}/cancel), отправляемый методом POST.. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на отмену блокировки средств с применением метода PayPal должен содержать идентификаторы проекта и платежа, а также подпись.
Форматы данных для перенаправления пользователей
Формат данных при использовании SDK PayPal и Gate API
Для перенаправления пользователей от веб-сервиса мерчанта к сервису PayPal при проведении каждого платежа с использованием метода PayPal необходимо принять промежуточное оповещение от платёжной платформы и использовать идентификатор заказа (orderID
) на стороне PayPal в соответствии с официальной документацией для открытия страницы оплаты. Этот идентификатор передаётся в параметре payment_id
объекта provider
, включённого в объект operation
. Формат промежуточных оповещений является типовым (подробнее).
Формат данных при прямом использовании Gate API
Для перенаправления пользователей от веб-сервиса мерчанта к сервису PayPal при проведении каждого платежа с использованием метода PayPal необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data
. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data
включаются следующие объекты и параметры:
body
— объект с данными для отправки в теле запроса;method
— параметр с указанием HTTP-метода отправки запроса (GET
илиPOST
);url
— параметр со ссылкой для перенаправления.
Формат оповещений
Для итоговых оповещений об оплатах с применением метода PayPal (независимо от используемого способа взаимодействия) используется типовой формат, описание которого представлено в статье Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 210
была проведена оплата в размере 10,00 USD
.
В следующем примере оповещение свидетельствует об отклонённой одностадийной оплате.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 1037
была успешно проведена блокировка средств в размере 100,00 USD
:
В следующем примере оповещение свидетельствует об отказе в блокировке средств:
В следующем примере оповещение свидетельствует о том, что в рамках проекта 1037
списаны заблокированные ранее средства в размере 100,00 EUR
:
В следующем примере оповещение свидетельствует об отказе в списании средств:
В следующем примере оповещение свидетельствует о том, что в рамках проекта 1037
отменена блокировка средств в размере 140,00 EUR
:
В следующем примере оповещение свидетельствует об отмене блокировки средств:
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Разовая оплата в две стадии — о том, как проводить оплаты в две стадии через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Возвраты через Gate
Общая информация
Для выполнения возврата через Gate с использованием метода PayPal со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема выполнения возврата выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом PayPal через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на возврат с применением метода PayPal необходимо учитывать следующее:
- Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/wallet/paypal/refund
. Эта конечная точка относится к группе /v2/payment/wallet/{payment_method}/refund. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, для которого необходимо выполнить возврат;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее)),
payment
— объект, содержащий сведения о возврате:description
— комментарий к возврату или его описание;amount
— сумма возврата (является обязательной при частичном возврате);,currency
— код валюты возврата в формате ISO-4217 alpha-3 (является обязательным при частичном возврате)
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на возврат с применением метода PayPal должен содержать идентификаторы проекта и платежа, описание возврата, подпись, а также, при необходимости, код валюты и сумму возврата.
Формат оповещений
Для оповещений о результатах возвратов с применением метода PayPal используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 210
был выполнен возврат в размере 10,00 USD
на счёт № VSAFYPWDD35123
.
В следующем примере оповещение свидетельствует об отклонённом возврате.
Дополнительные материалы
Для организации работы с возвратами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Возвраты средств после оплат — о том, как выполнять возвраты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Выплаты через Gate
Общая информация
Для проведения выплаты через Gate с использованием метода PayPal со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения выплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения выплат методом PayPal через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на выплаты с применением метода PayPal необходимо учитывать следующее:
- Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/wallet/paypal/payout
. Эта конечная точка относится к группе /v2/payment/wallet/{payment_method}/payout. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
payment
— сведения о платеже:amount
— сумма выплаты;currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проект;,ip_address
— IP-адрес пользователя, актуальный для инициируемой выплаты;,
account
— объект, содержащий сведения об электронном кошельке пользователя:number
— идентификатор кошелька пользователя или адрес электронной почты, на которую зарегистрирован кошелёк. Выбор значения параметра зависит от типа бизнеса мерчанта. Информацию необходимо уточнять у курирующего менеджера ecommpay.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на выплату с применением метода PayPal должен содержать идентификатор проекта, базовые сведения о платеже (его идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, номер счёта и подпись.
Формат оповещений
Для оповещений о результатах выплат с применением метода PayPal используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 112
для пользователя 120005
была проведена выплата в размере 10,00 GBP
на кошелёк DHEV3UAE54T3G
.
В следующем примере оповещение свидетельствует об отклонённой выплате.
Дополнительные материалы
Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Выплаты — о том, как проводить выплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Выплаты через Dashboard
При использовании интерфейса Dashboard можно проводить одиночные и массовые выплаты методом PayPal с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.
- Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры (включая метод), отправить запрос и убедиться в проведении выплаты.
-
Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат.
При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры выплат — должны соответствовать требованиям, представленным в разделе Выплаты через Gate этой статьи (за исключением пункта о подписи).
Более подробная информация о проведении выплат через Dashboard представлена в отдельной статье.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу PayPal, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.