PayPal

Введение

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

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

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

Порядок подключения

Для подключения этого платёжного метода мерчанту необходимо предоставить ecommpay права на проведение платежей с использованием сервиса PayPal от имени этого мерчанта. К таким правам относятся право на работу с оплатами и возвратами по ним и право на работу с выплатами. Чтобы предоставить любое из этих прав со стороны мерчанта необходимо:

1. Сообщить курирующему менеджеру ecommpay о готовности подключить платёжный метод PayPal.
2. Получить от ecommpay письмо со ссылкой для перехода на сайт сервиса PayPal.
3. Перейти по ссылке и подтвердить право ecommpay на проведение платежей. При этом можно использовать существующую учётную запись мерчанта в PayPal или зарегистрировать новую.
4. Получить от ecommpay письмо с уведомлением о подтверждении со стороны PayPal права проводить платежи с использованием указанного идентификатора мерчанта. После этого можно ожидать технической настройки на стороне ecommpay. Как правило, она выполняется в течение трёх дней.
5. Получить от ecommpay письмо с подтверждением готовности проводить платежи с использованием метода PayPal. После этого можно начинать работу с использованием данного метода.

При необходимости любое из предоставленных прав может быть отозвано на стороне сервиса PayPal по согласованию с курирующим менеджером ecommpay.

Схема работы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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. В зависимости от типа бизнеса мерчанта для повышения проходимости платежей может быть актуальным передавать следующие параметры (частично или полностью; информацию о параметрах, рекомендуемых в конкретных случаях, можно уточнять у курирующего менеджера ecommpay):
   • customer_email — адрес электронной почты пользователя.
   • customer_first_name — имя пользователя.
   • customer_last_name — фамилия пользователя.
   • customer_country — код страны пользователя в формате ISO 3166-1 alpha-2.
   • customer_phone — номер телефона пользователя;
   • payment_methods_options — строковый объект, названием которого выступает указатель метода paypal_wallet, а в качестве содержимого приводится объект additional_data с включёнными в него дополнительными сведениями о пользователе:
     • sender_create_date — время создания учётной записи пользователя в формате ISO 8601 по часовому поясу UTC+0 (например, 2022-01-25T10:15:30+00:00).
     • payments_count — количество платежей, проведённых веб-сервисом мерчанта для пользователя в течение предыдущих трёх месяцев до инициирования платежа.
     • pin_verification — признак использования PIN-кода для аутентификации пользователя (со значением Y при использовании PIN-кода и значением N в обратном случае).
     • face_id_verification — признак использования сканирования объёмно-пространственной формы лица ля аутентификации пользователя (со значением Y при использовании сканирования и значением N в обратном случае).
     • additional_verification — комбинация из четырёх индикаторов, отображающих выполнение ряда условий по подтверждению информации на стороне веб-сервиса в заданной последовательности. В качестве таких индикаторов должны использоваться цифры 0 или 1 (0 — не подтверждено, 1 — подтверждено). К этим условиям относятся:
       1. Номер телефона подтверждён.
       2. Фотография, подтверждающая личность подтверждена.
       3. Информация о платёжной карте подтверждена.
       4. Информация о банковском счёте подтверждена.

       Например: 1101.

     • ota_type — тип интернет-турагентства (например, Car rental).
     • ota_service_start_date — время начала предоставления услуг турагентством в формате ISO 8601 по часовому поясу UTC+0 (например, 2022-01-25T10:15:30+00:00).
     • ota_service_end_date — время окончания предоставления услуг турагентством в формате ISO 8601 по часовому поясу UTC+0 (например, 2022-01-25T10:15:30+00:00).
     • ota_change_guest_t_f — признак возможности изменения пользователя (возможно — 1, невозможно — 0).
     • ota_start_country — код страны, в которой начинается предоставление услуг пользователю (в формате ISO 3166-1 alpha-2).
     • ota_start_city — название города, в котором начинается предоставление услуг пользователю;
     • ota_start_zipcode — полный почтовый индекс места, в котором начинается предоставление услуг пользователю.
4. Для предварительного выбора метода PayPal необходимо указывать код платёжного метода в параметре force_payment_method — paypal-wallet.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "payment_methods_options": {"paypal_wallet":{"additional_data":{"sender_create_date": "2022-01-25T10:15:30+00:00", "payments_count": 123, "pin_verification": "Y", "face_id_verification": "N","additional_verification": "1101", "ota_type": "Car rental", "ota_service_start_date": "2022-01-26T10:15:30+00:00", "ota_service_end_date": "2022-02-25T10:15:30+00:00", "ota_change_guest_t_f": 0, "ota_start_country": "US", "ota_start_city": "Dallas", "ota_start_zipcode": "12345"}}}
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "payment_methods_options": {"paypal_wallet":{"additional_data":{"sender_create_date": "2022-01-25T10:15:30+00:00", "payments_count": 123, "pin_verification": "Y", "face_id_verification": "N","additional_verification": "1101", "ota_type": "Car rental", "ota_service_start_date": "2022-01-26T10:15:30+00:00", "ota_service_end_date": "2022-02-25T10:15:30+00:00", "ota_change_guest_t_f": 0, "ota_start_country": "US", "ota_start_city": "Dallas", "ota_start_zipcode": "12345"}}}
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

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

{
        "project_id": 210,
        "payment": {
            "id": "test_payment_1",
            "type": "purchase",
            "status": "success",
            "date": "2019-12-25T09:48:29+0000",
            "method": "PayPal Wallet",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": ""
        },
        "account": {
            "number": "VSAFYPWDD123"
        },
        "customer": {
            "id": "7895623"
        },
        "operation": {
            "id": 63460000012251,
            "type": "sale",
            "status": "success",
            "date": "2019-12-25T09:48:29+0000",
            "created_date": "2019-12-25T09:47:54+0000",
            "request_id": "55aa73dcab3dd00c23956537f3a4eeb72f7-00063461",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1556,
                "payment_id": "14C27062M77937123",
                "auth_code": "",
                "date": "2019-12-25T09:48:27+0000"
            }
        },
        "signature": "bLraFo85nfQ+ozqLbMjCyaximHVkuL3THI1oHRkukafnk3A=="
    }

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

{
        "project_id": 210,
        "payment": {
            "id": "test_payment_2",
            "type": "purchase",
            "status": "decline",
            "date": "2019-12-18T09:00:07+0000",
            "method": "PayPal Wallet",
            "sum": {
                "amount": 900,
                "currency": "USD"
            },
            "description": "test_paypal"
        },
        "customer": {
            "id": "156787"
        },
        "operation": {
            "id": 55628000009581,
            "type": "sale",
            "status": "decline",
            "date": "2019-12-18T09:00:07+0000",
            "created_date": "2019-12-18T08:59:30+0000",
            "request_id": "b8d98d70def1762cf5fc5259b0df9f52dc00ffb6-00055629",
            "sum_initial": {
                "amount": 900,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 900,
                "currency": "USD"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 1556,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "OEDB1GoxL9wsMnrPmuJ1Glccx2SLUnsj6gsW5qen7MrDC2o3Rg=="
    }

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

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

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

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

Платёжный метод PayPal предоставляет возможность проводить повторяемые оплаты — регулярные оплаты со списаниями по запросу. Подробная информация представлена в разделе Повторяемая оплата со списаниями по запросам. Через Payment Page доступна регистрация повторяемой оплаты, для этого со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, а также данные для регистрации повторяемой оплаты в объекте recurring, на рабочий URL ecommpay и принять оповещение о результате. В оповещении о регистрации повторяемой оплаты вы получите её идентификатор, который нужно использовать для проведения или отмены регулярной оплаты через Gate. Подробная информация об этом представлена в разделе Повторяемые оплаты через Gate.

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

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

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

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. Для указания свойств повторяемой оплаты необходимо передавать параметр recurring — в виде объекта JSON, если для вызова платёжной формы используется JavaScript-библиотека ecommpay, или в виде строки, полученной в результате кодирования URL-encoding, если платёжная форма вызывается иным способом. Параметр recurring должен содержать основные сведения о регистрации повторяемой оплаты:
   • register, boolean — признак регистрации повторяемых оплат, для которого необходимо использовать значение true;
   • type, string — категория регистрируемой повторяемой оплаты, для которой необходимо указывать одно из следующих значений:
     • U — для автооплаты;
     • R — для регулярной оплаты;
   • period, string — периодичность списаний (для регулярной оплаты), в параметре необходимо указывать одно из следующих значений:
     • D — ежедневно;
     • W — еженедельно;
     • M — ежемесячно (если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца);
     • Q — ежеквартально;
     • Y — ежегодно.
   • time, string — время выполнения последующих списаний (для регулярной оплаты) в формате hh:mm:ss, передаётся, если указан параметр period;
   • interval, integer — интервал между выбранным периодом проведения оплат, в параметре необходимо передавать числовое значение от 1 до 100, например, каждые три недели. Параметр обязательно используется в связке с параметром period.
4. Для указания свойств регулярной оплаты в параметре recurring также могут использоваться и другие сведения:
   • amount, integer — фиксированная сумма последующих списаний в дробных единицах валюты;
   • expiry_day, integer или string — день окончания проведения повторяемой оплаты;
   • expiry_month, integer или string — месяц окончания проведения повторяемой оплаты;
   • expiry_year, integer — год окончания проведения повторяемой оплаты;
   • start_date, string — дата первого списания в формате dd-mm-yyyy (параметр обязательно используется в связке с параметром scheduled_payment_id);
   • scheduled_payment_id, string — идентификатор платежа, в рамках которого следует выполнять списания; должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта (также не стоит путать его с идентификатором серии списаний, передаваемым в параметре id объекта recurring оповещения о регистрации повторяемой оплаты).
     Внимание: Если идентификаторы платежа, который необходимо присвоить повторяемой оплате (scheduled_payment_id), и платежа, в рамках которого эта оплата регистрируется (payment_id), совпадают, запрос на регистрацию отклоняется.
5. В зависимости от типа бизнеса мерчанта для повышения проходимости платежей может быть актуальным передавать следующие параметры (частично или полностью; информацию о параметрах, рекомендуемых в конкретных случаях, можно уточнять у курирующего менеджера ecommpay):
   • customer_email — адрес электронной почты пользователя.
   • customer_first_name — имя пользователя.
   • customer_last_name — фамилия пользователя.
   • customer_country — код страны пользователя в формате ISO 3166-1 alpha-2.
   • customer_phone — номер телефона пользователя;
   • payment_methods_options — строковый объект, названием которого выступает указатель метода paypal_wallet, а в качестве содержимого приводится объект additional_data с включёнными в него дополнительными сведениями о пользователе:
     • sender_create_date — время создания учётной записи пользователя в формате ISO 8601 по часовому поясу UTC+0 (например, 2022-01-25T10:15:30+00:00).
     • payments_count — количество платежей, проведённых веб-сервисом мерчанта для пользователя в течение предыдущих трёх месяцев до инициирования платежа.
     • pin_verification — признак использования PIN-кода для аутентификации пользователя (со значением Y при использовании PIN-кода и значением N в обратном случае).
     • face_id_verification — признак использования сканирования объёмно-пространственной формы лица ля аутентификации пользователя (со значением Y при использовании сканирования и значением N в обратном случае).
     • additional_verification — комбинация из четырёх индикаторов, отображающих выполнение ряда условий по подтверждению информации на стороне веб-сервиса в заданной последовательности. В качестве таких индикаторов должны использоваться цифры 0 или 1 (0 — не подтверждено, 1 — подтверждено). К этим условиям относятся:
       1. Номер телефона подтверждён.
       2. Фотография, подтверждающая личность подтверждена.
       3. Информация о платёжной карте подтверждена.
       4. Информация о банковском счёте подтверждена.

       Например: 1101.

     • ota_type — тип интернет-турагентства (например, Car rental).
     • ota_service_start_date — время начала предоставления услуг турагентством в формате ISO 8601 по часовому поясу UTC+0 (например, 2022-01-25T10:15:30+00:00).
     • ota_service_end_date — время окончания предоставления услуг турагентством в формате ISO 8601 по часовому поясу UTC+0 (например, 2022-01-25T10:15:30+00:00).
     • ota_change_guest_t_f — признак возможности изменения пользователя (возможно — 1, невозможно — 0).
     • ota_start_country — код страны, в которой начинается предоставление услуг пользователю (в формате ISO 3166-1 alpha-2).
     • ota_start_city — название города, в котором начинается предоставление услуг пользователю;
     • ota_start_zipcode — полный почтовый индекс места, в котором начинается предоставление услуг пользователю.
6. Для предварительного выбора метода PayPal необходимо указывать код платёжного метода в параметре force_payment_method — paypal-wallet.
7. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
8. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "force_payment_method": "paypal-wallet",
   "recurring": {"register":true,"type":"R","expiry_year":2025,"expiry_month":"01","period":"D","time":"10:00:00","start_date":"15-11-2020","scheduled_payment_id":"A2323"},
   "payment_methods_options": {"paypal_wallet":{"additional_data":{"sender_create_date": "2022-01-25T10:15:30+00:00", "payments_count": 123, "pin_verification": "Y", "face_id_verification": "N","additional_verification": "1101", "ota_type": "Car rental", "ota_service_start_date": "2022-01-26T10:15:30+00:00", "ota_service_end_date": "2022-02-25T10:15:30+00:00", "ota_change_guest_t_f": 0, "ota_start_country": "US", "ota_start_city": "Dallas", "ota_start_zipcode": "12345"}}}
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "force_payment_method": "paypal-wallet",
   "recurring": {"register":true,"type":"R","expiry_year":2025,"expiry_month":"01","period":"D","time":"10:00:00","start_date":"15-11-2020","scheduled_payment_id":"A2323"},
   "payment_methods_options": {"paypal_wallet":{"additional_data":{"sender_create_date": "2022-01-25T10:15:30+00:00", "payments_count": 123, "pin_verification": "Y", "face_id_verification": "N","additional_verification": "1101", "ota_type": "Car rental", "ota_service_start_date": "2022-01-26T10:15:30+00:00", "ota_service_end_date": "2022-02-25T10:15:30+00:00", "ota_change_guest_t_f": 0, "ota_start_country": "US", "ota_start_city": "Dallas", "ota_start_zipcode": "12345"}}}
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

{
    "project_id": 1037,
    "payment": {
        "id": "ORDER_ID_123",
        "type": "recurring",
        "status": "success",
        "date": "2024-04-05T16:49:20+0000",
        "method": "PayPal Wallet",
        "sum": {
            "amount": 1500,
            "currency": "USD"
        },
        "description": "Book order"
    },
    "account": {
        "number": "1234******abc"
    },
    "customer": {
        "id": "123"
    },
    "provider_extra_fields": {
        "holder": "John Doe",
        "email": "****************"
    },
    "recurring": {
        "id": 11607,
        "currency": "USD"
    },
    "operation": {
        "id": 3486000011257,
        "type": "recurring",
        "status": "success",
        "date": "2024-04-05T16:49:20+0000",
        "created_date": "2024-04-05T16:48:20+0000",
        "request_id": "5562e4dfe5dc45dfe142b2cbe-00003487",
        "sum_initial": {
            "amount": 1500,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 1500,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 1782,
            "payment_id": "0DL958510G965733C",
            "auth_code": "",
            "date": "2024-04-05T16:49:01+0000"
        }
    },
    "signature": "pMFA9Onino0suaGv+kJxuEhHhHJ8MtHfg7Weg=="
}

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

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

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

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

Платёжный метод PayPal предоставляет возможность проводить повторяемые оплаты — регулярные оплаты со списаниями по запросу. Подробная информация представлена в разделах Повторяемая оплата со списаниями по запросам и Повторяемая оплата со списаниями по запросам.

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

Регистрация повторяемой оплаты

Для регистрации повторяемых оплат со стороны веб-сервиса необходимо отправить запрос на оплату, содержащий требуемые параметры и подпись, а также признак регистрации повторяемой оплаты в параметре register объекта recurring со значением true, на заданный URL ecommpay и принять оповещение с информацией о результате. В оповещении о регистрации повторяемой оплаты содержится идентификатор, который можно использовать для проведения или отмены регулярных оплат.

Информация о проведении оплаты через Gate с помощью метода PayPal представлена в разделе Разовые оплаты через Gate.

Формат запросов на регистрацию повторяемых оплат при проведении одноразовых одностадийных оплат

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

1. Каждый раз должен использоваться запрос, отправляемый методом POST к конечной точке /v2/payment/wallet/paypal/sale, относящейся к группе /v2/payment/wallet/{payment_method}/sale.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
   • recurring — объект, содержащий сведения о повторяемой оплате (условия проведения регулярной оплаты определяются на стороне мерчанта):
     • register — признак регистрации платежа как повторяемой оплаты;
     • type — тип повторяемой оплаты: R (для регулярной оплаты), C (для экспресс-оплаты), или U (для автооплаты), подробную информацию см. в разделе Повторяемые оплаты;
     • scheduled_payment_id — идентификатор платежа, в рамках которого следует выполнять списания; должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта;
     • start_date — дата начала регулярной оплаты, в формате ДД-ММ-ГГГГ (должна быть как минимум на один день позже, чем дата регистрации);
     • amount — сумма платежа в дробных единицах валюты;
     • period — период выполнения регулярной оплаты;
     • interval — интервал выполнения регулярной оплаты;
     • time — время выполнения регулярной оплаты в формате hh:mm:ss (UTC0).
3. В зависимости от типа бизнеса мерчанта для повышения проходимости платежей может быть актуальным передавать следующие параметры (частично или полностью; информацию о параметрах, рекомендуемых в конкретных случаях, можно уточнять у курирующего менеджера ecommpay):
   • customer — объект, содержащий сведения о пользователе:
     • email — адрес электронной почты;,
     • first_name — имя;,
     • last_name — фамилия;,
     • country — код страны в формате ISO 3166-1 alpha-2;,
     • phone — номер телефона.
   • additional_data — объект, содержащий дополнительные данные о пользователе в сервисе мерчанта:
     • sender_create_date — время создания учётной записи пользователя в формате ISO 8601 по часовому поясу UTC+0 (например 2022-01-25T10:15:30+00:00).
     • payments_count — количество платежей, проведённых веб-сервисом мерчанта для пользователя в течение предыдущих трёх месяцев до инициирования платежа.
     • pin_verification — признак использования PIN-кода для аутентификации пользователя (со значением Y при использовании PIN-кода и значением N в обратном случае).
     • face_id_verification — признак использования сканирования объёмно-пространственной формы лица ля аутентификации пользователя (со значением Y при использовании сканирования и значением N в обратном случае).
     • additional_verification — комбинация из четырёх индикаторов, отображающих выполнение ряда условий по подтверждению информации на стороне веб-сервиса в заданной последовательности. В качестве таких индикаторов должны использоваться цифры 0 или 1 (0 — не подтверждено, 1 — подтверждено). К этим условиям относятся:
       1. Номер телефона подтверждён.
       2. Фотография, подтверждающая личность подтверждена.
       3. Информация о платёжной карте подтверждена.
       4. Информация о банковском счёте подтверждена.

       Например: 1101.

     • ota_type — тип интернет-турагентства (например, Car rental).
     • ota_service_start_date — время начала предоставления услуг турагентством (UTC+0) в формате ISO 8601 (например, 2022-01-25T10:15:30+00:00).
     • ota_service_end_date — время окончания предоставления услуг турагентством (UTC+0) в формате ISO 8601 (например, 2022-01-25T10:15:30+00:00).
     • ota_change_guest_t_f — признак возможности изменения пользователя (возможно — 1, невозможно — 0).
     • ota_start_country — код страны, в которой начинается предоставление услуг пользователю (в формате ISO 3166-1 alpha-2).
     • ota_start_city — название города, в котором начинается предоставление услуг пользователю;
     • ota_start_zipcode — полный почтовый индекс места, в котором начинается предоставление услуг пользователю.
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQSkzd0Iq6lM2...==",
  },
  "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD",
    "email": "test@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "3572437356",
    "country": "US"
  },   
  "additional_data": {
    "sender_create_date": "2022-01-25T10:15:30+00:00",
    "payments_count": 123,
    "pin_verification": "Y",
    "face_id_verification": "N",
    "additional_verification": "1101",
    "ota_type": "Car rental",
    "ota_service_start_date": "2022-01-26T10:15:30+00:00",
    "ota_service_end_date": "2022-02-25T10:15:30+00:00",
    "ota_change_guest_t_f": 0,
    "ota_start_country": "US",
    "ota_start_city": "Dallas",
    "ota_start_zipcode": "12345"
  },
  "return_url": {
    "success": "http://example.com/success",
    "decline": "http://example.com/decline"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQSkzd0Iq6lM2...==",
  },
  "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD",
    "email": "test@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "3572437356",
    "country": "US"
  },   
  "additional_data": {
    "sender_create_date": "2022-01-25T10:15:30+00:00",
    "payments_count": 123,
    "pin_verification": "Y",
    "face_id_verification": "N",
    "additional_verification": "1101",
    "ota_type": "Car rental",
    "ota_service_start_date": "2022-01-26T10:15:30+00:00",
    "ota_service_end_date": "2022-02-25T10:15:30+00:00",
    "ota_change_guest_t_f": 0,
    "ota_start_country": "US",
    "ota_start_city": "Dallas",
    "ota_start_zipcode": "12345"
  },
  "return_url": {
    "success": "http://example.com/success",
    "decline": "http://example.com/decline"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

Формат запросов на регистрацию повторяемых оплат при проведении одноразовых двухстадийных оплат

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

1. Каждый раз должен использоваться запрос, отправляемый методом POST к конечной точке /v2/payment/wallet/paypal/auth, относящейся к группе /v2/payment/wallet/{payment_method}/auth.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
   • return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
     • return — URL для перенаправления пользователя на любом шаге оплаты.
   • recurring — объект, содержащий сведения о повторяемой оплате (условия проведения регулярной оплаты определяются на стороне мерчанта):
     • register — признак регистрации платежа как повторяемой оплаты;
     • type — тип повторяемой оплаты: R (для регулярной оплаты), C (для экспресс-оплаты), или U (для автооплаты), подробную информацию см. в разделе Повторяемые оплаты;
     • scheduled_payment_id — идентификатор платежа, в рамках которого следует выполнять списания; должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта;
     • start_date — дата начала регулярной оплаты, в формате ДД-ММ-ГГГГ (должна быть как минимум на один день позже, чем дата регистрации);
     • amount — сумма платежа в дробных единицах валюты;
     • period — период выполнения регулярной оплаты;
     • interval — интервал выполнения регулярной оплаты;
     • time — время выполнения регулярной оплаты в формате hh:mm:ss (UTC0).
3. В зависимости от типа бизнеса мерчанта для повышения проходимости платежей может быть актуальным передавать следующие параметры (частично или полностью; информацию о параметрах, рекомендуемых в конкретных случаях, можно уточнять у курирующего менеджера ecommpay):
   • customer — объект, содержащий сведения о пользователе:
     • email — адрес электронной почты;,
     • first_name — имя;,
     • last_name — фамилия;,
     • country — код страны в формате ISO 3166-1 alpha-2;,
     • phone — номер телефона.
   • additional_data — объект, содержащий дополнительные данные о пользователе в сервисе мерчанта:
     • sender_create_date — время создания учётной записи пользователя в формате ISO 8601 по часовому поясу UTC+0 (например 2022-01-25T10:15:30+00:00).
     • payments_count — количество платежей, проведённых веб-сервисом мерчанта для пользователя в течение предыдущих трёх месяцев до инициирования платежа.
     • pin_verification — признак использования PIN-кода для аутентификации пользователя (со значением Y при использовании PIN-кода и значением N в обратном случае).
     • face_id_verification — признак использования сканирования объёмно-пространственной формы лица ля аутентификации пользователя (со значением Y при использовании сканирования и значением N в обратном случае).
     • additional_verification — комбинация из четырёх индикаторов, отображающих выполнение ряда условий по подтверждению информации на стороне веб-сервиса в заданной последовательности. В качестве таких индикаторов должны использоваться цифры 0 или 1 (0 — не подтверждено, 1 — подтверждено). К этим условиям относятся:
       1. Номер телефона подтверждён.
       2. Фотография, подтверждающая личность подтверждена.
       3. Информация о платёжной карте подтверждена.
       4. Информация о банковском счёте подтверждена.

       Например: 1101.

     • ota_type — тип интернет-турагентства (например, Car rental).
     • ota_service_start_date — время начала предоставления услуг турагентством в формате ISO 8601 по часовому поясу UTC+0 (например, 2022-01-25T10:15:30+00:00).
     • ota_service_end_date — время окончания предоставления услуг турагентством в формате ISO 8601 по часовому поясу UTC+0 (например, 2022-01-25T10:15:30+00:00).
     • ota_change_guest_t_f — признак возможности изменения пользователя (возможно — 1, невозможно — 0).
     • ota_start_country — код страны, в которой начинается предоставление услуг пользователю (в формате ISO 3166-1 alpha-2).
     • ota_start_city — название города, в котором начинается предоставление услуг пользователю;
     • ota_start_zipcode — полный почтовый индекс места, в котором начинается предоставление услуг пользователю.
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

 {
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JIipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "customer123",
    "email": "test@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "3572437356",
    "country": "US"
  },   
  "additional_data": {
    "sender_create_date": "2022-01-25T10:15:30+00:00",
    "payments_count": 123,
    "pin_verification": "Y",
    "face_id_verification": "N",
    "additional_verification": "1101",
    "ota_type": "Car rental",
    "ota_service_start_date": "2022-01-26T10:15:30+00:00",
    "ota_service_end_date": "2022-02-25T10:15:30+00:00",
    "ota_change_guest_t_f": 0,
    "ota_start_country": "US",
    "ota_start_city": "Dallas",
    "ota_start_zipcode": "12345"
  },
  "return_url": {
    "return": "http://example.com/return"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

 {
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JIipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "customer123",
    "email": "test@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "3572437356",
    "country": "US"
  },   
  "additional_data": {
    "sender_create_date": "2022-01-25T10:15:30+00:00",
    "payments_count": 123,
    "pin_verification": "Y",
    "face_id_verification": "N",
    "additional_verification": "1101",
    "ota_type": "Car rental",
    "ota_service_start_date": "2022-01-26T10:15:30+00:00",
    "ota_service_end_date": "2022-02-25T10:15:30+00:00",
    "ota_change_guest_t_f": 0,
    "ota_start_country": "US",
    "ota_start_city": "Dallas",
    "ota_start_zipcode": "12345"
  },
  "return_url": {
    "return": "http://example.com/return"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

Формат запросов на проведение повторяемой оплаты

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

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

1. Для проведения каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/paypal/recurring, относящейся к группе /v2/payment/wallet/{payment_method}/recurring.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;
   • recurring — объект, содержащий сведения о повторяемой оплате:
     • id — идентификатор зарегистрированной повторяемой оплаты.
3. Также зависимости от типа бизнеса мерчанта можно передавать следующие параметры (информацию необходимо уточнять у курирующего менеджера 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 — подтверждено). К этим условиям относятся:
       1. Номер телефона подтверждён;,
       2. Фотография, подтверждающая личность подтверждена;,
       3. Информация о платёжной карте подтверждена;,
       4. Информация о банковском счёте подтверждена.

       Например: 1101.

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

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

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6wx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD",
    "email": "test@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "3572437356",
    "country": "US"
  },   
  "additional_data": {
    "sender_create_date": "2022-01-25T10:15:30+00:00",
    "payments_count": 123,
    "pin_verification": "Y",
    "face_id_verification": "N",
    "additional_verification": "1101",
    "ota_type": "Car rental",
    "ota_service_start_date": "2022-01-26T10:15:30+00:00",
    "ota_service_end_date": "2022-02-25T10:15:30+00:00",
    "ota_change_guest_t_f": 0,
    "ota_start_country": "US",
    "ota_start_city": "Dallas",
    "ota_start_zipcode": "12345"
  },
  "recurring": {
    "id": 1234567890
  }
}

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6wx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD",
    "email": "test@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "3572437356",
    "country": "US"
  },   
  "additional_data": {
    "sender_create_date": "2022-01-25T10:15:30+00:00",
    "payments_count": 123,
    "pin_verification": "Y",
    "face_id_verification": "N",
    "additional_verification": "1101",
    "ota_type": "Car rental",
    "ota_service_start_date": "2022-01-26T10:15:30+00:00",
    "ota_service_end_date": "2022-02-25T10:15:30+00:00",
    "ota_change_guest_t_f": 0,
    "ota_start_country": "US",
    "ota_start_city": "Dallas",
    "ota_start_zipcode": "12345"
  },
  "recurring": {
    "id": 1234567890
  }
}

Формат запросов на отмену проведения повторяемой оплаты

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

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

1. Для отмены каждой повторяемой оплаты должен использоваться отдельный POST-запрос к конечной точке: /v2/payment/wallet/paypal/recurring/cancel, относящейся к группе /v2/payment/wallet/{payment_method}/recurring/cancel.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
   • recurring — объект, содержащий сведения о повторяемой оплате:
     • id — идентификатор зарегистрированной повторяемой оплаты.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890
  }
}

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6/ZtDzO5GMSkzd0Iq6lM2v8...==",
  },
  "recurring": {
    "id": 1234567890
  }
}

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

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

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

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

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

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

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

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

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

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

1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/paypal/refund. Эта конечная точка относится к группе /v2/payment/wallet/{payment_method}/refund.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, для которого необходимо выполнить возврат;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее)),
   • payment — объект, содержащий сведения о возврате:
     • description — комментарий к возврату или его описание;
     • amount — сумма возврата (является обязательной при частичном возврате);,
     • currency — код валюты возврата в формате ISO-4217 alpha-3 (является обязательным при частичном возврате)
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на возврат с применением метода PayPal должен содержать идентификаторы проекта и платежа, описание возврата, подпись, а также, при необходимости, код валюты и сумму возврата.

{
    "general": {
        "project_id": 210,
        "payment_id": "test_refund_1",
        "signature": "U5LCm6489ly9cXCKIVBNqLks8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 1000,
        "currency": "USD",
        "description": "Test PayPal refund"
    }
}

{
    "general": {
        "project_id": 210,
        "payment_id": "test_refund_1",
        "signature": "U5LCm6489ly9cXCKIVBNqLks8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 1000,
        "currency": "USD",
        "description": "Test PayPal refund"
    }
}

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

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

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

{
        "customer": {
            "id": "7895623"
        },
        "account": {
            "number": "VSAFYPWDD35123"
        },
        "project_id": 210,
        "payment": {
            "id": "test_refund_1",
            "type": "purchase",
            "status": "refunded",
            "date": "2019-12-25T09:52:32+0000",
            "method": "PayPal Wallet",
            "sum": {
                "amount": 0,
                "currency": "USD"
            },
            "description": ""
        },
        "operation": {
            "id": 63460000005982,
            "type": "refund",
            "status": "success",
            "date": "2019-12-25T09:52:33+0000",
            "created_date": "2019-12-25T09:52:08+0000",
            "request_id": "ce8a135fe3c28ad2c4ddcfa7a7002d80ad948284c-00063461",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1556,
                "payment_id": "8YC17810N19968319",
                "auth_code": "",
                "date": "2019-12-25T09:52:11+0000"
            }
        },
        "signature": "TPqAIy7FUlH3iy/mz8mmSosn5HpuNofnt4or7LdABIrH6JGMGw=="
    }

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

{
        "customer": {
            "id": "7895623"
        },
        "account": {
            "number": "VSAFYPWDD35123"
        },
        "project_id": 210,
        "payment": {
            "id": "test_refund_2",
            "type": "purchase",
            "status": "success",
            "date": "2019-12-25T09:52:32+0000",
            "method": "PayPal Wallet",
            "sum": {
                "amount": 1000,
                "currency": "USD"
            },
            "description": ""
        },
        "operation": {
            "id": 63460000005982,
            "type": "refund",
            "status": "decline",
            "date": "2019-12-25T09:52:33+0000",
            "created_date": "2019-12-25T09:52:08+0000",
            "request_id": "ce8a135fe3c28ad2c66c901802d80ad948284c-00063461",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "code": "20100",
            "message": "Decline",
            "provider": {
                "id": 1556,
                "payment_id": "8YC17810N19968319",
                "auth_code": "",
                "date": "2019-12-25T09:52:11+0000"
            }
        },
        "signature": "TPqAIy7FUlH3iy/mz8mmSosMTdxuNofnt4or7LdABIrH6JGMGw=="
    }

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

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

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

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

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

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

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

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

1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/paypal/payout. Эта конечная точка относится к группе /v2/payment/wallet/{payment_method}/payout.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
   • payment — сведения о платеже:
     • amount — сумма выплаты;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проект;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемой выплаты;,
   • account — объект, содержащий сведения об электронном кошельке пользователя:
     • number — идентификатор кошелька пользователя или адрес электронной почты, на которую зарегистрирован кошелёк. Выбор значения параметра зависит от типа бизнеса мерчанта. Информацию необходимо уточнять у курирующего менеджера ecommpay.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
    "general": {
        "project_id": 603,
        "payment_id": "test_payoutt_1",
        "signature": "U5LCm6489ly9cXCKIVBNVs8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 3000,
        "currency": "USD"
    },
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "34534543545"
    },
    "account": {
        "number": "DHEV3UAE54T6G"
    }
}

{
    "general": {
        "project_id": 603,
        "payment_id": "test_payoutt_1",
        "signature": "U5LCm6489ly9cXCKIVBNVs8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 3000,
        "currency": "USD"
    },
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "34534543545"
    },
    "account": {
        "number": "DHEV3UAE54T6G"
    }
}

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 112 для пользователя 120005 была проведена выплата в размере 10,00 GBP на кошелёк DHEV3UAE54T3G.

{
        "customer": {
            "id": "120005"
        },
        "account": {
            "number": "DHEV3UAE54T6G"
        },
        "project_id": 112,
        "payment": {
            "id": "test_paypal_payout",
            "type": "payout",
            "status": "success",
            "date": "2020-01-27T12:50:35+0000",
            "method": "PayPal Wallet",
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "test_payout"
        },
        "operation": {
            "id": 56417000021431,
            "type": "payout",
            "status": "success",
            "date": "2020-01-27T12:50:35+0000",
            "created_date": "2020-01-27T12:50:11+0000",
            "request_id": "678923242211798109ef056eb0b1c7adfdcad60e968f-00056418",
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1556,
                "payment_id": "2334",
                "auth_code": "",
                "date": "2020-01-27T12:50:17+0000"
            }
        },
        "signature": "BmR11YQo8fszfS3kMMO66zXDCOpVLXd/y/v0mXN8Huy9V3gA=="
    }

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

{
        "customer": {
            "id": "120005"
        },
        "account": {
            "number": "DHEV3UAE54T3G"
        },
        "project_id": 112,
        "payment": {
            "id": "test_paypal_payout2",
            "type": "payout",
            "status": "decline",
            "date": "2020-01-27T12:51:35+0000",
            "method": "PayPal Wallet",
            "sum": {
                "amount": 1000,
                "currency": "GBP"
            },
            "description": "test_payout2"
        },
        "operation": {
            "id": 56417000021432,
            "type": "payout",
            "status": "decline",
            "date": "2020-01-27T12:51:35+0000",
            "created_date": "2020-01-27T12:51:11+0000",
            "request_id": "678923242211798109ef056eb0b1c7adfdcad60e968f-00056423",
            "sum_initial": {
                "amount": 1000,
                "currency": "GBP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "GBP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1556,
                "payment_id": "2335",
                "auth_code": "",
                "date": "2020-01-27T12:51:17+0000"
            }
        },
        "signature": "BmR11YQo8fszfS3kMMO66zXDCOpVLXd/y/v0mXeqewqgV3gA=="
    }

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

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

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