PayPal Pay Later

Обзор

Введение

PayPal Pay Later — метод, позволяющий проводить платежи в евро, долларах США, австралийских долларах и фунтах стерлингов с использованием электронного кошелька в Австралии, США и некоторых странах Европы. Пользователи могут оплачивать заказы в рассрочку и в кредит, условия рассрочки и кредита определяются в результате взаимодействия пользователя и PayPal. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты и возвраты.

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

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

Тип платёжного метода платежи с использованием электронных кошельков
Платёжные инструменты электронные кошельки
Регионы использования AU, DE, ES, FR, IT, GB, US
Валюты платежей AUD, EUR, GBP, USD
Конвертация валют на стороне ecommpay
Оплаты +
Повторяемые оплаты
Полные возвраты +
Частичные возвраты +
Выплаты
Опротестования +
Особенности для мерчантов, зарегистрированных в Соединённых Штатах Америки, применяются ограничения по поддерживаемым регионам (за уточнениями можно обращаться к курирующему менеджеру ecommpay)
Организация и стоимость подключения по согласованию с курирующим менеджером ecommpay

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

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

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

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

Схема работы

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

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

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

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

Суммы, USD ¹ Время ²
минимум максимум базовое предельное
Оплаты 30,00 10 000,00 * 1 минута 3 дня
Возвраты 35 дней
Прим.:
  1. Подробную информацию уточняйте у курирующего менеджера ecommpay.
  2. Базовое и предельное время определяются следующим образом:
    • Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа (подробнее).
    • Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.

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

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

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

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

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

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



Рис. 5. Проведение оплаты через Payment Page. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выбирает для оплаты метод PayPal Pay Later.
  8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода PayPal Pay Later.
  9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис PayPal.
  10. В сервисе PayPal выполняется обработка запроса на оплату.
  11. От сервиса PayPal к платёжной платформе передаются данные для перенаправления пользователя к сервису PayPal.
  12. Данные для перенаправления пользователя передаются к Payment Page.
  13. Пользователь перенаправляется к сервису PayPal.
  14. Пользователь выполняет необходимые действия для оплаты.
  15. В сервисе PayPal выполняется обработка платежа.
  16. Пользователь перенаправляется к Payment Page.
  17. От сервиса PayPal к платёжной платформе направляется информация о результате оплаты.
  18. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  19. От платёжной платформы к Payment Page направляется информация о результате оплаты.
  20. Информация о результате оплаты отображается пользователю на Payment Page.

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

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

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

  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. Для предварительного выбора метода PayPal Pay Later необходимо указывать код paypal-wallet в параметре force_payment_method и дополнительно указать параметр payment_methods_options со значением "{\"submethod_code\": \"paylater\"}":
    "payment_methods_options": "{\"submethod_code\": \"paylater\"}"
  4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
  5. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
Рис. 6. Пример достаточного набора данных для запроса на оплату
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

Рис. 7. Пример данных из оповещения о проведении оплаты
{
        "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": "55aa73dcab3dd003a4eeb72f7-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+ozqLbMjmHVkuL3THI1oHRkukafnk3A=="
    }

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

Рис. 8. Пример данных из оповещения об отклонении оплаты
{
        "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": "b8d98d70def1762cf2dc00ffb6-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": "OEDB1GoxL9wsx2SLUnsj6gsW5qen7MrDC2o3Rg=="
    }

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

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

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

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

Введение

Оплаты через Gate с использованием метода PayPal Pay Later могут проводиться двумя способами: напрямую через Gate API, а также с использованием SDK PayPal и Gate API. На стороне веб-сервиса различия между способами касаются отправки запросов на инициирование оплат и перенаправления пользователей, выбор конкретного способа остаётся за мерчантом.

Подготовка к проведению оплат с использованием SDK PayPal и Gate API

Перед проведением оплат с использованием SDK PayPal и Gate API с использованием метода PayPal Pay Later со стороны веб-сервиса необходимо:

  1. Настроить использование SDK PayPal в соответствии с официальной документацией (https://developer.paypal.com/sdk/js/).
  2. Настроить отображение кнопки выбора этого платёжного метода на стороне веб-сервиса, также в соответствии с официальной документацией (https://developer.paypal.com/docs/checkout/standard/customize/standalone-buttons/, https://developer.paypal.com/demo/checkout/#/pattern/server).
  3. Подключить JavaScript-библиотеку PayPal в клиентской части веб-сервиса по ссылке следующего вида.
    <script src="https://www.paypal.com/sdk/js?client-id=<CLIENT_ID>&merchant-id=<MERCHANT_ID>&currency=USD"></script>

    В этой ссылке используются переменные <CLIENT_ID> — идентификатор платёжной платформы ecommpay в сервисе PayPal, который определяется после предоставления ecommpay прав на проведение платежей от имени мерчанта, и <MERCHANT_ID> — идентификатор мерчанта в сервисе PayPal.

Проведение оплат с использованием SDK PayPal и Gate API

После подготовки к использованию SDK PayPal для проведения каждой оплаты через этот SDK и Gate API с использованием метода PayPal Pay Later со стороны веб-сервиса необходимо:

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

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



Рис. 9. Проведение оплат с использованием SDK. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода PayPal Pay Later.
  2. От веб-сервиса к PayPal SDK передаются данные для формирования запроса на оплату.
  3. От PayPal SDK на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
  4. Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
  5. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
  6. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
  7. В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис PayPal.
  8. В сервисе PayPal выполняется обработка запроса на оплату.
  9. От сервиса PayPal к платёжной платформе передаются данные для перенаправления пользователя к сервису PayPal.
  10. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису PayPal.
  11. От веб-сервиса к SDK PayPal передаются данные для перенаправления пользователя к сервису PayPal.
  12. На стороне PayPal SDK выполняется перенаправление пользователя к сервису PayPal.
  13. Пользователь выполняет необходимые действия для оплаты.
  14. В сервисе PayPal выполняется обработка платежа.
  15. От сервиса PayPal к платёжной платформе направляется информация о результате оплаты.
  16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

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

Проведение оплат с прямым использованием Gate API

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

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

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



Рис. 10. Проведение оплаты напрямую через API. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода PayPal Pay Later.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
  4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
  6. В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис PayPal Pay Later.
  7. В сервисе PayPal Pay Later выполняется обработка запроса на оплату.
  8. От сервиса PayPal Pay Later к платёжной платформе передаются данные для перенаправления пользователя к сервису PayPal Pay Later.
  9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису PayPal Pay Later.
  10. Пользователь перенаправляется к сервису PayPal Pay Later.
  11. Пользователь выполняет необходимые действия для оплаты.
  12. В сервисе PayPal Pay Later выполняется обработка платежа.
  13. Пользователь перенаправляется к веб-сервису.
  14. От сервиса PayPal Pay Later к платёжной платформе направляется информация о результате оплаты.
  15. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  16. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

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

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

Используемые параметры

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

  1. В каждом запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
      • payment_id — идентификатор платежа, уникальный в рамках проекта;,
      • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа;,
      • currency — код валюты платежа в формате ISO-4217 alpha-3;,
      • extra_param — идентификатор метода в платёжной платформе (в значении необходимо указывать paylater);,
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор пользователя, уникальный в рамках проекта;,
      • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;,
    • return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
      • success — URL для перенаправления пользователя в случае, когда он выполнил необходимые действия на стороне сервиса PayPal;,
      • decline — URL для перенаправления пользователя в случае, когда он не выполнил необходимые действия на стороне сервиса PayPal.
  2. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQs+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD",
    "extra_param": "paylater"
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "customer123"
  },
  "return_url": {
    "success": "http://example.com/success",
    "decline": "http://example.com/decline"
  }
}
Рис. 11. Пример достаточного набора данных для запроса на оплату
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQs+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD",
    "extra_param": "paylater"
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "customer123"
  },
  "return_url": {
    "success": "http://example.com/success",
    "decline": "http://example.com/decline"
  }
}

Способ отправки запросов с использованием SDK PayPal и Gate API

При отправке запросов с использованием SDK PayPal и Gate API необходимо, чтобы запросы соответствовали формату, поддерживаемому SDK PayPal. При этом для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/paypal/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.

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

Формат данных при использовании SDK PayPal и Gate API

Для перенаправления пользователей от веб-сервиса мерчанта к сервису PayPal при проведении каждого платежа с использованием метода PayPal Pay Later необходимо принять промежуточное оповещение от платёжной платформы и использовать идентификатор заказа (orderID) на стороне PayPal в соответствии с официальной документацией для открытия страницы оплаты. Этот идентификатор передаётся в параметре payment_id объекта provider, включённого в объект operation. Формат промежуточных оповещений является типовым (подробнее).

Рис. 12. Пример объекта operation и параметра payment_id
"operation": {
            "sum_initial": {
                "amount": 50000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 50000,
                "currency": "USD"
            },
            "code": "9999",
            "message": "Awaiting processing",
            "provider": {
                "id": 1556,
                "payment_id": "14C27062M77937123",
                "auth_code": ""
            }

Формат данных при прямом использовании Gate API

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

  • body — объект с данными для отправки в теле запроса;
  • method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
  • url — параметр со ссылкой для перенаправления.
Рис. 13. Пример объекта redirect_data
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.sandbox.paypal.com/checkoutnow?token=123"
  }

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

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

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

Рис. 14. Пример данных из оповещения о проведении оплаты
{
        "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=="
    }

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

Рис. 15. Пример данных из оповещения об отклонении оплаты
{
        "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": "b8d98d70def1762cf5fc59f52dc00ffb6-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": "OEDB1GoxL9wsMnrPmuJsj6gsW5qen7MrDC2o3Rg=="
    }

Возвраты через Gate

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

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



Рис. 16. Выполнение возврата через Gate. Описание шагов
  1. Пользователь инициирует возврат.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на выполнение возврата.
  3. Запрос на выполнение возврата поступает в платёжную платформу ecommpay.
  4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
  6. В платёжной платформе обеспечиваются дальнейшая обработка запроса (с проверкой согласованности параметров) и его отправка в сервис PayPal.
  7. В сервисе PayPal выполняется обработка возврата.
  8. От сервиса PayPal к платёжной платформе направляется информация о результате возврата.
  9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата.
  10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата.

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

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

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

  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 Pay Later должен содержать идентификаторы проекта и платежа, описание возврата, подпись, а также, при необходимости, код валюты и сумму возврата.

{
    "general": {
        "project_id": 210,
        "payment_id": "test_refund_1",
        "signature": "U5LCm6489ly9cXCKIVBNqLks8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 1000,
        "currency": "USD",
        "description": "Test refund"
    }
}
Рис. 17. Пример достаточного набора данных для запроса на возврат
{
    "general": {
        "project_id": 210,
        "payment_id": "test_refund_1",
        "signature": "U5LCm6489ly9cXCKIVBNqLks8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 1000,
        "currency": "USD",
        "description": "Test refund"
    }
}

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

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

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

Рис. 18. Пример данных из оповещения о выполнении возврата
{
        "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=="
    }

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

Рис. 19. Пример данных из оповещения об отклонении возврата
{
        "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 также могут быть полезны следующие материалы:

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

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

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

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