Google Pay

Введение

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

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

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

Схема работы

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

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

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

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

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

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

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

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

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

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

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

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

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. Для указания варианта проведения оплаты, отличного от заданного по умолчанию для используемого проекта, необходимо указывать параметр operation_type со значением sale (для незамедлительного списания средств при оплате в одну стадию) или auth (для предварительной блокировки средств при оплате в две стадии).
4. Можно выбирать вариант отображения кнопки Google Pay на Payment Page:
   • Отображение кнопки на странице для ввода данных платёжной карты. Предварительно пользователю необходимо выбирать оплату с использованием карт среди прочих платёжных методов. Этот вариант отображения задан по умолчанию.
   • Отображение кнопки на странице для выбора метода оплаты среди прочих платёжных методов. Для этого необходимо обращаться в техническую поддержку ecommpay.
   • Отображение кнопки на странице для ввода данных карты, когда пользователю сразу открывается эта страница и не надо предварительно выбирать оплату с использованием карт. В данном случае оба платёжных метода доступны пользователю. Для этого используется предварительный выбор метода оплаты с использованием карт и необходимо указывать код card в параметре force_payment_method.
   • Отображение одной кнопки на странице выбора метода оплаты. Для этого используется предварительный выбор метода Google Pay и необходимо указывать код платёжного метода google_pay_host в параметре force_payment_method.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

К особенностям метода Google Pay можно отнести то, что в оповещениях для оплат, сопровождающихся аутентификацией 3‑D Secure, передаётся код индикатора ECI (подробнее) в параметре operation.eci, а в качестве служебного кода метода в параметре payment.method указывается значение card. Вместе с тем, в оповещениях для оплат без аутентификации 3‑D Secure не передаётся код индикатора ECI, а в качестве служебного кода метода может указываться значение card или etoken-google.

К особенностям оповещений в случае с Google Pay можно отнести то, что в параметре token объекта account указывается значение токена карты. В случае указания кода метода etoken-google этот токен можно использовать при запросах на выплаты, а когда указывается служебный код метода card, то токен можно использовать как для выплат, так и для оплат.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 688 была успешно проведена оплата в размере 1 000,00 USD с банковской карты 431422******0056 без проведения аутентификации 3‑D Secure.

 {
        "project_id": 688,
        "payment": {
            "id": "TEST_154356886034722221",
            "type": "purchase",
            "status": "success",
            "date": "2019-04-11T11:22:36+0000",
            "method": "etoken-google", // служебный код метода
            "sum": {
                "amount": 100000,
                "currency": "USD"
            },
            "description": "TEST_154356886034722221"
        },
        "account": {
            "number": "431422******0056",
            "token": :"a989f5ef7ab159dd5c33260e4201d13dbfcdc75"
        },
        "operation": {
            "id": 2000015,
            "type": "sale",
            "status": "success",
            "date": "2019-04-11T11:22:36+0000",
            "created_date": "2019-04-11T11:22:20+0000",
            "request_id": "2b36e68d4d9fc8839d5d65ee6273dfdebbd",
            "sum_initial": {
                "amount": 100000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "d1b9-3qfl-9rns-1ql9aokzi2v8",
                "date": "2019-04-11T11:22:34+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "Xkf7nUDleg8wcLltroCvNOMq751VtZcgrz6Nax...=="
    }

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

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

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

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

Для работы с оплатами через Gate с использованием метода Google Pay со стороны мерчанта необходимо придерживаться политик использования Google Pay API и принимать условия предоставления услуг Google Pay. Вместе с тем, со стороны веб-сервиса необходимо:

1. Выполнить начальную настройку в соответствии с требованиями Google и свериться с контрольным списком интеграции.
2. Зарегистрироваться в сервисе Google и получить Google merchant ID.
3. Заполнить заявку на сопровождение интеграции с Google Pay API специалистами Google и выполнить дальнейшие действия по запросам этих специалистов. При этом может потребоваться предоставить Google дополнительную информацию об интеграции.

Также следует иметь в виду, что оплаты с использованием метода Google Pay могут проводиться по двум сценариям:

• через приложение Google Pay (когда оно установлено на совместимом устройстве пользователя);
• без использования приложения Google Pay, как типичный карточный платёж (когда приложение не установлено на устройстве пользователя или устройство не совместимо с ним).

В первом случае оплата проводится без аутентификации 3‑D Secure, а во втором случае может проводиться как с аутентификацией, так и без неё. Для обработки таких ситуаций на стороне веб-сервиса необходимо настроить реагирование на оповещения с информацией о перенаправлении пользователя и поддержать два сценария работы.

В сценарии с использованием метода Google Pay для оплаты без аутентификации 3‑D Secure со стороны веб-сервиса необходимо:

1. Встроить кнопку Google Pay, соблюдая рекомендации по правильному использованию бренда и реализовать процесс получения токена с карточными данными пользователя от сервиса Google Pay.
2. Отправить запрос в сервис Google Pay на открытие платёжной формы или приложения Google Pay со списком сохраненных карт, доступных пользователю для оплаты.
3. Отправить запрос в сервис Google Pay для получения токена с зашифрованными данными карты, выбранной пользователем.
4. Отправить запрос, содержащий токен и другие требуемые параметры и подпись, на рабочий URL ecommpay.
5. Принять оповещение о результате оплаты от платформы.

В сценарии с использованием метода Google Pay для оплаты с аутентификацией 3‑D Secure со стороны веб-сервиса необходимо:

1. Встроить кнопку Google Pay, соблюдая рекомендации по правильному использованию бренда и реализовать процесс получения токена с карточными данными пользователя от сервиса Google Pay.
2. Отправить запрос в сервис Google Pay на открытие платёжной формы или приложения Google Pay со списком сохраненных карт, доступных пользователю для оплаты.
3. Отправить запрос в сервис Google Pay для получения токена с зашифрованными данными карты, выбранной пользователем.
4. Отправить запрос, содержащий токен и другие требуемые параметры и подпись, на рабочий URL ecommpay.
5. Получить промежуточное оповещение от платформы с данными для перенаправления пользователя на страницу аутентификации.
6. Перенаправить пользователя на страницу аутентификации для прохождения проверки 3‑D Secure.
7. Отправить запрос на продолжение проведения платежа с результатом аутентификации в платёжную платформу.
8. Принять итоговое оповещение о результате оплаты от платформы.

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

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

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

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

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к одной из следующих конечных точек:
   • /v2/payment/googlepay/sale для проведения оплаты в одну стадию,
   • /v2/payment/googlepay/auth для проведения оплаты в две стадии.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • validation_url — URL для проверки;
     • domain_name — доменное имя веб-сервиса мерчанта;
     • display_name — название проекта для отображения, должен содержать не более 64 символов;
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее).
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
     • cryptocurrency_type — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжную систему Visa, и допускающий одно из следующих значений:
       • cbdc — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством;
       • stablecoins_fiat_backed — цифровая валюта (в виде стейблкоина), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте;
       • native_tokens — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий;
       • other — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции.
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
   • etoken — объект, содержащий сведения о токене с зашифрованными данными карты, полученный от сервиса Google Pay:
     • token — токен с зашифрованными данными карты.
3. Могут потребоваться другие обязательные параметры в зависимости от типа токенизации карты, который используется при формировании запросов в сервис Google Pay. Информацию о том, какой тип токенизации используется при проведении оплат в рамках проекта, необходимо уточнять у специалистов технической поддержки ecommpay:
   • Для использования типа токенизации PAYMENT_GATEWAY дополнительно необходимо указывать адрес электронной почты пользователя в параметре email объекта customer.
   • Для типа токенизации DIRECT необходимо указывать в объекте etoken:
     • google_merchant_id — идентификатор мерчанта в сервисе Google Pay;
     • google_tokenization_type — тип токенизации DIRECT.
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {      
    "project_id": 626,
    "payment_id": "ORDER_ID_gev_S01_0.20111200_1554473913",
    "signature": "xWOlMksKctAKeYADt8W6F98D/ZFgyNqOYwFsgonIEj1MPw...=="    
  },
  "customer": {
    "email": "googlepay@google.com",
    "ip_address": "83.220.236.84",
    "id": "123"
  },
  "payment": {
    "amount": 100000,    
    "currency": "USD"
  },
  "etoken": {
    "token": "..." // в том виде,в котором был получен от Google Pay
  }
}

{
  "general": {      
    "project_id": 626,
    "payment_id": "ORDER_ID_gev_S01_0.20111200_1554473913",
    "signature": "xWOlMksKctAKeYADt8W6F98D/ZFgyNqOYwFsgonIEj1MPw...=="    
  },
  "customer": {
    "email": "googlepay@google.com",
    "ip_address": "83.220.236.84",
    "id": "123"
  },
  "payment": {
    "amount": 100000,    
    "currency": "USD"
  },
  "etoken": {
    "token": "..." // в том виде,в котором был получен от Google Pay
  }
}

Корректный запрос на оплату с применением метода Google Pay и типа токенизации DIRECT должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, токен, идентификатор мерчанта в сервисе Google Pay, тип токенизации карты, а также подпись:

{
  "general": {
    "project_id": 688,
    "payment_id": "ORDER_89218100_1554981739",
    "signature": "aRZiZZc0w5RVnuCxC7KSm50Pfwsj/8fqy2XlAJ...=="
  },
  "customer": {
    "ip_address": "83.220.236.84"
  },
  "payment": {
    "amount": 100000,
    "currency": "USD"
  },
  "etoken": {
    "token": "...", // в том виде,в котором был получен от Google Pay
    "google_merchant_id": "12345678901234567890",
    "google_tokenization_type": "DIRECT"
  }
}

{
  "general": {
    "project_id": 688,
    "payment_id": "ORDER_89218100_1554981739",
    "signature": "aRZiZZc0w5RVnuCxC7KSm50Pfwsj/8fqy2XlAJ...=="
  },
  "customer": {
    "ip_address": "83.220.236.84"
  },
  "payment": {
    "amount": 100000,
    "currency": "USD"
  },
  "etoken": {
    "token": "...", // в том виде,в котором был получен от Google Pay
    "google_merchant_id": "12345678901234567890",
    "google_tokenization_type": "DIRECT"
  }
}

Формат запросов на продолжение проведения оплаты после 3‑D Secure аутентификации

При работе с запросами на продолжение оплаты после проведения 3‑D Secure аутентификации пользователя необходимо учитывать следующее:

1. Для продолжения каждой оплаты после проведения 3‑D Secure аутентификации должен использоваться отдельный POST-запрос к конечной точке /v2/payment/card/3ds_result.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • Один из следующих параметров:
     • pares — данные о результате аутентификации, полученные в уведомлении от платёжной платформы;,
     • cres — данные о результате аутентификации, полученные в уведомлении от сервера управления доступом.

Таким образом, корректный запрос на оплату с применением метода Google Pay должен содержать идентификаторы проекта и платежа, подпись и данные результата аутентификации.

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "pares": "eJzVWdfvq8iy/iujOY/I1...Dfn76en3N+f/A1fJrSU="
  }

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "pares": "eJzVWdfvq8iy/iujOY/I1...Dfn76en3N+f/A1fJrSU="
  }

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

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

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

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

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwChlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "payment": {
    "amount": 100000,
    "currency": "USD"
  }

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwChlDZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "payment": {
    "amount": 100000,
    "currency": "USD"
  }

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

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

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

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

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKww7ew6ow3RpGYv4U...=="
  }

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKww7ew6ow3RpGYv4U...=="
  }

Формат оповещений о результатах оплат

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

К особенностям метода Google Pay можно отнести то, что в оповещениях для оплат, проводимых без использования приложения Google Pay и сопровождающихся аутентификацией 3‑D Secure, передаётся код индикатора ECI (подробнее) в параметре operation.eci, а в качестве служебного кода метода в параметре payment.method указывается значение card. Вместе с тем, в оповещениях для оплат без аутентификации 3‑D Secure не передаётся код индикатора ECI, а в качестве служебного кода метода может указываться значение card или etoken-google.

К особенностям оповещений в случае с Google Pay можно отнести то, что в параметре token объекта account указывается значение токена карты. В случае указания кода метода etoken-google этот токен можно использовать при запросах на выплаты, а когда указывается служебный код метода card, токен можно использовать как для выплат, так и для оплат.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 688 была успешно проведена оплата в размере 1 000,00 USD с банковской карты 431422******0056 без проведения аутентификации 3‑D Secure.

 {
        "project_id": 688,
        "payment": {
            "id": "TEST_154356886034722221",
            "type": "purchase",
            "status": "success",
            "date": "2019-04-11T11:22:36+0000",
            "method": "etoken-google", // служебный код метода
            "sum": {
                "amount": 100000,
                "currency": "USD"
            },
            "description": "TEST_154356886034722221"
        },
        "account": {
            "number": "431422******0056",
            "token": :"a989f5ef7ab159dd5c33260e4201d13dbfcdc75"
        },
        "operation": {
            "id": 2000015,
            "type": "sale",
            "status": "success",
            "date": "2019-04-11T11:22:36+0000",
            "created_date": "2019-04-11T11:22:20+0000",
            "request_id": "2b36e68d4d9fc8839d5d65ee6273dfdebbd",
            "sum_initial": {
                "amount": 100000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "d1b9-3qfl-9rns-1ql9aokzi2v8",
                "date": "2019-04-11T11:22:34+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "Xkf7nUDleg8wcLltroCvNOMq751VtZcgrz6Nax...=="
    }

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

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

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

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

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

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

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

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

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

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, содержащий признак регистрации и необходимую информацию. Для регистрации регулярной оплаты в запросе необходимо передать информацию о периодичности, сумме, начале и конце совершения регулярной оплаты. Полный список параметров, которые можно передать в объекте recurring представлен в разделе Регистрация повторяемых оплат.
4. Для предварительного выбора метода Google Pay необходимо указывать код платёжного метода в параметре force_payment_method:
   • google_pay_host — для открытия Payment Page с предварительно выбранным платёжным методом Google Pay;
   • card — для открытия Payment Page с возможностью выбрать оплату с использованием платёжной карты, подключенной к сервису Google Pay. В данном случае оба платёжных метода доступны пользователю.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "force_payment_method": "google_pay_host",
   "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"},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 100000,
   "payment_currency": "USD",
   "customer_id": "customer1",
   "force_payment_method": "google_pay_host",
   "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"},
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

К особенностям метода Google Pay можно отнести то, что в оповещениях для повторяемых оплат, сопровождающихся аутентификацией 3‑D Secure, передаётся код индикатора ECI (подробнее) в параметре operation.eci, а в качестве служебного кода метода в параметре payment.method указывается значение card. Вместе с тем, в оповещениях для оплат без аутентификации 3‑D Secure не передаётся код индикатора ECI, а в качестве служебного кода метода может указываться значение card или etoken-google.

К особенностям оповещений в случае с Google Pay можно отнести то, что в параметре token объекта account указывается значение токена карты. В случае указания кода метода etoken-google этот токен можно использовать при запросах на выплаты, а когда указывается служебный код метода card, то токен можно использовать как для выплат, так и для оплат.

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

 {
        "project_id": 208,
        "payment": {
            "id": "payment",
            "type": "purchase",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "method": "etoken-google", // служебный код метода
            "sum": {
                "amount": 300,
                "currency": "USD"
            },
            "description": "payment"
        },
        "account": {
            "number": "431422******0056",
            "token": :"a989f5ef7ab159dd5c33260e4201d13dbfcdc75"
        },
        "recurring": {
            "id": 1000030038,
            "currency": "USD",
            "valid_thru": "-0001-11-30T00:00:00+0000"
        },
        "operation": {
            "id": 1000034,
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "created_date": "2018-11-20T08:44:41+0000",
            "request_id": "07fd7ade7cf010",
            "sum_initial": {
                "amount": 300,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "2548950091",
                "date": "2020-11-20T08:44:45+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "x2tsnvLCRXZM9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

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

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

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

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

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

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

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

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

Подробнее о проведении оплаты через Gate с помощью метода Google Pay см. в разделе Разовые оплаты через Gate.

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

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

1. Каждый раз должен использоваться запрос, отправляемый методом POST к одной из следующих конечных точек: /v2/payment/googlepay/sale или /v2/payment/googlepay/auth.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
     • cryptocurrency_type — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжную систему Visa, и допускающий одно из следующих значений:
       • cbdc — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством;
       • stablecoins_fiat_backed — цифровая валюта (в виде стейблкоина), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте;
       • native_tokens — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий;
       • other — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции.
   • recurring — объект, содержащий сведения о повторяемой оплате (условия проведения регулярного платежа хранятся на стороне мерчанта):
     • register — признак регистрации платежа как повторяемой оплаты,
     • type—тип повторяемой оплаты: R (для регулярной оплаты), C (для экспресс-оплаты), или U (для автооплаты), более подробная информация доступна в разделе Общая информация,
     • scheduled_payment_id—идентификатор платежа, в рамках которого следует выполнять списания; должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта,
     • start_date — дата начала регулярной оплаты, в формате ДД-ММ-ГГГГ (должна быть как минимум на один день позже, чем дата регистрации),
     • amount — сумма платежа,
     • period — период выполнения регулярной оплаты,
     • interval — интервал выполнения регулярной оплаты,
     • time — время выполнения регулярной оплаты в формате hh:mm:ss (UTC0).
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytOqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "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": "DH0v2pZnkK9hwytOqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "123"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "recurring": {
    "register": true,
    "type": "R",
    "amount": 1000,
    "interval": 1,
    "cycle": "week",
    "start_date": "21-11-2018"
  }
}

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

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

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

1. Каждый раз должен использоваться запрос, отправляемый методом POST к одной из следующих конечных точек:
   1. /v2/payment/googlepay/recurring — в случае получения значения etoken-google в качестве служебного кода метода в оповещении о зарегистрированной повторяемой оплате;
   2. /v2/payment/card/recurring — в случае получения значения card в качестве служебного кода метода в оповещении о зарегистрированной повторяемой оплате;
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,;
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
     • cryptocurrency_type — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжную систему Visa, и допускающий одно из следующих значений:
       • cbdc — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством;
       • stablecoins_fiat_backed — цифровая валюта (в виде стейблкоина), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте;
       • native_tokens — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий;
       • other — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции.
   • recurring — объект, содержащий сведения о повторяемой оплате:
     • id — идентификатор зарегистрированной повторяемой оплаты.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

 {
  "general": {
    "project_id": 208,
    "payment_id": "TEST_15427007172789",
    "signature": "DH0v2pZnkK9hwytQ6wx/OqrWdbltzO5GMSkzd0Iq6lM2...==",
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "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"
  },
  "recurring": {
    "id": 1234567890
  }
}

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

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

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

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

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

 {
  "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
  }
}

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

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

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

 {
        "project_id": 208,
        "payment": {
            "id": "payment",
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "method": "etoken-google",
            "sum": {
                "amount": 300,
                "currency": "USD"
            },
            "description": "payment"
        },
        "account": {
            "number": "431422******0056",
            "token": :"a989f5ef7ab159dd5c33260e4201d13dbfcdc75"
        },
        "recurring": {
            "id": 1000030038,
            "currency": "USD",
            "valid_thru": "-0001-11-30T00:00:00+0000"
        },
        "operation": {
            "id": 1000034,
            "type": "recurring",
            "status": "success",
            "date": "2018-11-20T08:44:46+0000",
            "created_date": "2018-11-20T08:44:41+0000",
            "request_id": "07fd7ade7cf010",
            "sum_initial": {
                "amount": 300,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 300,
                "currency": "USD"
            },
            "provider": {
                "id": 1381,
                "payment_id": "2548950091",
                "date": "2020-11-20T08:44:45+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "x2tsnvLCRXZMX8Kwyr9a8+I3RipuPWUod5c89cDSQ6cRq...=="
    }

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

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

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

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

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

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

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

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

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

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

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

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

При этом в качестве служебного кода метода в параметре payment.method может указываться etoken-google или card (в зависимости от оплаты, для которой выполняется возврат).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 208 для пользователя был выполнен возврат в размере 30,00 USD на счёт карты 541333******0019.

{
        "project_id": 208,
        "payment": {
            "id": "TEST_123456",
            "type": "purchase",
            "status": "refunded",
            "date": "2020-03-30T08:54:23+0000",
            "method": "etoken-google", // служебный код метода
            "sum": {
                "amount": 0,
                "currency": "USD"
            },
            "description": "payment for 30.0 USD"
        },
        "account": {
            "number": "541333******0019",
            "type": "mastercard",
            "card_holder": "LEE OONG",
            "expiry_month": "09",
            "expiry_year": "2020",
            "token": :"a989f5ef7ab159dd5c33260e4201d13dbfcdc75"
        },
        "customer": {
            "id": "907680850"
        },
        "operation": {
            "id": 57299000036261,
            "type": "refund",
            "status": "success",
            "date": "2020-03-30T08:54:24+0000",
            "created_date": "2020-03-30T08:54:22+0000",
            "request_id": "122809a-c43c08a4b6ee7d73bfaaf7f",
            "sum_initial": {
                "amount": 3000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 3000,
                "currency": "USD"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 120,
                "payment_id": "353197036",
                "auth_code": "000000",
                "endpoint_id": 120,
                "date": "2020-03-30T08:54:23+0000"
            }
        },
        "signature": "8y41YTzCAy0N/sGYLUYAyAIp3U/3x7jymU...=="
    }

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

{
        "project_id": 208,
        "payment": {
            "id": "TEST_1234567",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-27T17:41:04+0000",
            "method": "etoken-google",
            "sum": {
                "amount": 2000,
                "currency": "EUR"
            },
            "description": "35121367"
        },
        "account": {
            "number": "541333******0019",
            "type": "mastercard",
            "card_holder": "LEE OONG",
            "expiry_month": "09",
            "expiry_year": "2028"
        },
        "customer": {
            "id": "LEE OONG"
        },
        "operation": {
            "id": 42809000016421,
            "type": "refund",
            "status": "decline",
            "date": "2020-03-27T17:41:04+0000",
            "created_date": "2020-03-27T17:41:03+0000",
            "request_id": "b869d91-ff913d9c5ae5ba1bb6c3457c30e91",
            "sum_initial": {
                "amount": 1400,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1400,
                "currency": "EUR"
            },
            "code": "10000",
            "message": "General decline"
        },
        "signature": "8ql4yC3p2RiYbNXHSxMYBrBQJmcKmL...=="
    }

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

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

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

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

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

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

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

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

1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/card/payout/token.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма выплаты в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемой выплаты;,
     • first_name — имя пользователя;,
     • middle_name — отчество или среднее имя пользователя;,
     • last_name — фамилия пользователя;,
   • card — объект, содержащий сведения о платёжной карте пользователя:
     • card_holder — полное имя держателя карты;,
   • token — токен карты, полученный от ecommpay в параметре token оповещения о проведённой оплате.
3. В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, в запросе необходимо передавать объект recipient, содержащий сведения о местонахождении получателя выплаты:
   • country — код страны получателя в формате ISO 3166-1 alpha-2;
   • city — город получателя;
   • address — адрес получателя;
   • если код страны соответствует CA или US, дополнительно следует передать параметр state — штат, провинция или другой регион получателя выплаты.
4. В случае проведения выплаты в рамках программы Money Transfer платёжной системы Visa на карту, выпущенную в Бразилии или Катаре, в запросе необходимо передавать номер телефона отправителя в параметре phone объекта sender.
5. В случае проведения выплаты в рамках программ сервиса MoneySend платёжной системы Mastercard, в которой отправителем является физическое лицо, в запросе необходимо передавать информацию об имени и фамилии получателя в параметрах first_name и last_name объекта recipient, а также информацию об отправителе выплаты в объекте sender:
   • номер платёжного инструмента отправителя — pan для карты или wallet_id для электронного кошелька;
   • first_name — имя отправителя;
   • last_name — фамилия отправителя;
   • address — адрес отправителя;
   • city — город отправителя;
   • zip — почтовый индекс отправителя;
   • country — код страны отправителя в формате ISO 3166-1 alpha-2;
   • если код страны соответствует CA или US, дополнительно следует передать параметр state — штат, провинция или другой регион отправителя выплаты.
6. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "first_name": "John",
    "middle_name": "Jr",
    "last_name": "Jonson",
    "ip_address": "192.0.2.0"
  },
  "card": {
    "card_holder": "John Johnson"
  },
  "token": "a989f5ef7ab159dd5c3016eee7563736f"
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "USD"
  },
  "customer": {
    "id": "customer123",
    "first_name": "John",
    "middle_name": "Jr",
    "last_name": "Jonson",
    "ip_address": "192.0.2.0"
  },
  "card": {
    "card_holder": "John Johnson"
  },
  "token": "a989f5ef7ab159dd5c3016eee7563736f"
}

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

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

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

{
        "payment": {
            "method": "card",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "id": "test_id",
            "type": "payout",
            "status": "success",
            "date": "2023-11-07T07:37:27+0000",
            "description": "Test payout"
        },
        "customer": {
            "id": "Test",
            "ip": "192.0.2.0",
            "first_name": "Test",
            "last_name": "Test"
        },
        "account": {
            "number": "1234******4567",
            "token": "a9608ce50413260e4201d13dbfcdc75",
            "type": "visa",
            "card_holder": "TEST TEST",
            "expiry_month": "01",
            "expiry_year": "2031"
        },
        "project_id": 123,
        "rrn": "331140338636",
        "testdebet": "credit",
        "opeation": {
            "last_processor_message": "Success"
        },
        "operation": {
            "created_date": "2023-11-07T07:37:22+0000",
            "request_id": "d22a4c02f61ed9a82140045-00049491",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 414,
                "payment_id": "0040000018267721",
                "auth_code": "408112",
                "endpoint_id": 414,
                "date": "2023-11-07T07:37:24+0000"
            },
            "id": 49490010084733,
            "type": "payout",
            "status": "success",
            "date": "2023-11-07T07:37:27+0000"
        },
        "signature": "TL2BLpOE/xAVCmYf8SIUXYqmlF1WHtaHQ=="
    }

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

{
        "payment": {
            "method": "card",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "id": "test_id",
            "type": "payout",
            "status": "decline",
            "date": "2023-11-07T07:38:27+0000",
            "description": "Test payout"
        },
        "customer": {
            "id": "Test",
            "ip": "192.0.2.0",
            "first_name": "Test",
            "last_name": "Test"
        },
        "account": {
            "number": "1234******4567",
            "token": "a9608ce50413260e4201d13dbfcdc75",
            "type": "visa",
            "card_holder": "TEST TEST",
            "expiry_month": "01",
            "expiry_year": "2031"
        },
        "project_id": 123,
        "rrn": "",
        "testdebet": "credit",
        "opeation": {
            "last_processor_message": "Decline"
        },
        "operation": {
            "created_date": "2023-11-07T07:38:22+0000",
            "request_id": "d22a4c02f61ed9a82140045-00049492",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 414,
                "payment_id": "0040000018267721",
                "auth_code": "",
                "endpoint_id": 414,
                "date": "2023-11-07T07:38:24+0000"
            },
            "id": 49490010084733,
            "type": "payout",
            "status": "decline",
            "date": "2023-11-07T07:38:27+0000"
        },
        "signature": "TL2BLpOE/xAVCmYf8SIUXYqmlF1WHtaHA=="
    }

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

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

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

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

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

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

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

1. Для проверки действительности карты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/googlepay/account_verification.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
     • payment — объект, содержащий сведения о платеже:
       • amount — сумма платежа в дробных единицах валюты;,;
       • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;
   • etoken — сведения о токене от Google Pay:
     • token — токен, полученный от Google Pay после идентификации пользователя.
3. Сумма платежа должна быть нулевой.
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {
    "project_id": 238,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+DZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 0,
    "currency": "USD"
  },
  "etoken": {
        "token": "..."
    }
}

{
  "general": {
    "project_id": 238,
    "payment_id": "TEST_15427033321774",
    "signature": "96c+hWk1zweuGKwDRrl+DZrjJXZw7ew6ow3RpGYv4U...=="
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 0,
    "currency": "USD"
  },
  "etoken": {
        "token": "..."
    }
}

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

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

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

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

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

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

Для метода Google Pay доступно тестирование оплат в одну и две стадии через Payment Page и Gate, а тестирование проверки действительности карты через Gate. Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой функциональности следует обращаться к специалистам технической поддержки ecommpay.

При проведении тестовых платежей следует учитывать, что в запросах должен указываться идентификатор тестового проекта, а интерфейсы эмулятора платёжных форм Payment Page и страницы аутентификации 3‑D Secure могут отличаться от рабочих. Вместе с тем для проведения тестовых платежей необходимо использовать действительные платёжные карты, предварительно зарегистрированные в сервисе Google Pay. Это никак не влияет на проведение реальных платежей с использованием этих карт, но позволяет выполнять полноценное тестирование.

Для тестирования оплат через Gate необходимо также подготовить веб-сервис к работе с сервисом Google (подробнее — в разделе Разовые оплаты через Gate).

Статусы тестовых платежей и операций

При тестировании оплат в одну и две стадии их итоговые статусы определяются исходя из сумм, указанных в запросах:

• success — при указании суммы 1000;
• decline — при указании суммы 2000, 5000 или 10001.

При тестировании проверки действительности карты статус этой проверки определяется исходя из сумм, указанных в запросах:

• success — при указании суммы 0;
• decline — при указании любой другой суммы.

Оплата в одну стадию через Payment Page

Для проведения тестовой оплаты в одну стадию через Payment Page необходимо:

1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
2. Если в запросе не был указан код предварительного выбора метода card или google_pay_host — выбрать оплату методом Google Pay на странице эмулятора.
3. При отображении страницы аутентификации эмулятора пройти аутентификацию 3‑D Secure 2.
4. Принять итоговое оповещение с информацией о результате оплаты.

Более подробная информация о проведении оплат с использованием метода Google Pay через Payment Page представлена в разделе Разовые оплаты через Payment Page этой статьи.

Оплата в одну стадию через Gate

Для проведения тестовой оплаты через Gate необходимо:

1. Отправить в платёжную платформу корректный тестовый запрос на оплату.
2. При получении оповещения с данными для перенаправления на страницу аутентификации 3‑D Secure 2 эмулятора:
   1. Выполнить перенаправление и пройти аутентификацию.
   2. Отправить запрос на продолжение проведения оплаты. В этом запросе необходимо использовать параметр cres со следующим значением:

      ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDogIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmRiNjMzNzZlYiIsCiAgICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjZmMmM3OGFkLTFjOWMtNTI2ZC04MDAwLTAwMDAwMDAwMTA2YiIsCiAgICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ

3. Принять итоговое оповещение с информацией о результате оплаты.

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

Оплата в две стадии с блокировкой средств через Payment Page и подтверждением или отменой через Gate

Для проведения тестовой оплаты в две стадии с блокировкой через Payment Page и подтверждением или отменой через Gate необходимо:

1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
2. Если в запросе не был указан код предварительного выбора метода card или google_pay_host — выбрать оплату методом Google Pay на странице эмулятора.
3. При отображении страницы аутентификации эмулятора пройти аутентификацию 3‑D Secure 2.
4. Принять оповещение с информацией о результате блокировки средств.
5. Отправить запрос на подтверждение или отмену оплаты.
6. Принять итоговое оповещение с информацией о результате.

Более подробная информация о проведении оплат с использованием метода Google Pay через Payment Page и Gate представлена в разделах Разовые оплаты через Payment Page и Разовые оплаты через Gate этой статьи.

Оплата в две стадии с блокировкой средств и подтверждением или отменой через Gate

Для проведения тестовой оплаты в две стадии с блокировкой и подтверждением или отменой через Gate необходимо:

1. Отправить в платёжную платформу корректный тестовый запрос на оплату.
2. При получении оповещения с данными для перенаправления на страницу аутентификации 3‑D Secure 2 эмулятора:
   1. Выполнить перенаправление и пройти аутентификацию.
   2. Отправить запрос на продолжение проведения оплаты. В этом запросе необходимо использовать параметр cres со следующим значением:

      ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDogIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmRiNjMzNzZlYiIsCiAgICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZlclRyYW5zSUQiIDogIjZmMmM3OGFkLTFjOWMtNTI2ZC04MDAwLTAwMDAwMDAwMTA2YiIsCiAgICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ

3. Принять оповещение с информацией о результате блокировки средств.
4. Отправить запрос на подтверждение или отмену оплаты.
5. Принять итоговое оповещение с информацией о результате.

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

Проверка действительности карты через Gate

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