GCash
Обзор
Введение
GCash — метод, позволяющий проводить платежи филиппинских песо с использованием электронного кошелька в Филиппинах. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты и выплаты.
В этой статье представлена информация о работе с методом GCash: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | платежи с использованием электронных кошельков |
---|---|
Платёжные инструменты | электронные кошельки |
Регионы использования | PH |
Валюты платежей | PHP |
Конвертация валют | доступна только для оплат — на стороне ecommpay |
Разовые оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | – |
Частичные возвраты | – |
Выплаты | + |
Опротестования | – |
Особенности | для выполнения возвратов можно проводить выплаты |
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay, дополнительную информацию можно получить ecommpay shop |
Схема работы
В проведении отдельного платежа с использованием метода GCash задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса GCash.
Основные операции
Для проведения платежей и выполнения операций с использованием метода GCash могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.
При работе с методом GCash, независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.
Суммы, PHP | Время ¹ | |||
---|---|---|---|---|
минимум | максимум | базовое | предельное | |
Оплаты | 1,00 | 10 000,00 | 30 минут | 1 день |
Выплаты | 10,00 | 100 000,00 | 24 часа | 48 часов |
- Базовое и предельное время определяются следующим образом:
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа (подробнее).
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус
decline
. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.
Сценарии использования
Проведение оплат с использованием метода GCash осуществляется с перенаправлением пользователей к сервису GCash, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.
Пользовательский сценарий оплаты через Payment Page выглядит следующим образом.
Общие сценарии проведения оплат и выплат можно представить следующим образом.
Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом GCash соответствуют специфике этих возможностей.
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода GCash со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом GCash через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода GCash необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;payment_currency
— код валюты платежа в формате ISO-4217 alpha-3;payment_amount
— сумма платежа в дробных единицах валюты;customer_id
— идентификатор пользователя в рамках проекта.
- Должен использоваться базовый минимум параметров:
project_id
,payment_id
,payment_currency
,payment_amount
,customer_id
. - Дополнительно должен использоваться параметр
customer_email
— адрес электронной почты пользователя. Если параметр отсутствует в запросе, на Payment Page пользователю отображается поле для ввода недостающего значения. Если параметр присутствует в запросе, на Payment Page пользователю отображается поле с предварительно заполненным значением параметра, указанного в запросе, для подтверждения или изменения. - Для предварительного выбора метода GCash необходимо указывать код этого метода в параметре
force_payment_method
—gcash-wallet
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода GCash должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и подпись.
Формат оповещений
Для оповещений о результатах оплат с применением метода GCash используется типовой формат, описание которого представлено в статье Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 239
была проведена оплата в размере 10,00 PHP
.
В следующем примере оповещение свидетельствует об отклонённой оплате.
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Для проведения оплаты через Gate с использованием метода GCash со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису GCash.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом GCash через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на оплаты с применением метода GCash необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке
v2/payment/wallet/gcash/sale
. Эта конечная точка относится к группе /v2/payment/wallet/{payment_method}/sale. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа в дробных единицах валюты;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,email
— адрес электронной почты пользователя;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа.
return_url
— объект, содержащий URL для перенаправления пользователя в веб-сервис:success
— URL для перенаправления пользователя в случае успешной оплаты.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату с применением метода GCash должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и URL для перенаправления, а также подпись.
Формат промежуточных оповещений для перенаправления пользователей
Для перенаправления пользователей от веб-сервиса мерчанта к сервису GCash при проведении каждого платежа с использованием метода GCash необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data
. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data
включаются следующие объекты и параметры:
body
— объект с данными для отправки в теле запроса;method
— параметр с указанием HTTP-метода отправки запроса (GET
илиPOST
);url
— параметр со ссылкой для перенаправления.
Формат итоговых оповещений
Для оповещений о результатах оплат с применением метода GCash используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 239
была проведена оплата в размере 10,00 PHP
.
В следующем примере оповещение свидетельствует об отклонённой оплате.
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Выплаты через Gate
Общая информация
Для проведения выплаты через Gate с использованием метода GCash со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения выплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения выплат методом GCash через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на выплаты с применением метода GCash необходимо учитывать следующее:
- Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/wallet/gcash/payout
. Эта конечная точка относится к группе /v2/payment/wallet/{payment_method}/payout. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма выплаты в дробных единицах валюты;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемой выплаты;,
account
— объект, содержащий сведения об учётной записи пользователя:number
— идентификатор учётной записи, должен состоять из 11 цифр и начинаться с09
;,customer_name
— полное имя пользователя.
- Валютой платежа может быть только PHP.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на выплату с применением метода GCash должен содержать идентификатор проекта, базовые сведения о платеже (его идентификатор, сумму и код валюты), инофрмацию о пользователе и учётной записи, а также подпись.
Формат оповещений
Для оповещений о результатах выплат с применением метода GCash используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 445
была проведена выплата в размере 10,00 PHP
.
В следующем примере оповещение свидетельствует об отклонённой выплате.
Дополнительные материалы
Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Выплаты — о том, как проводить выплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Выплаты через Dashboard
При использовании интерфейса Dashboard можно проводить одиночные и массовые выплаты методом GCash с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.
- Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры (включая метод), отправить запрос и убедиться в проведении выплаты.
-
Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат.
При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры выплат — должны соответствовать требованиям, представленным в разделе Выплаты через Gate этой статьи (за исключением пункта о подписи).
Более подробная информация о проведении выплат через Dashboard представлена в отдельной статье.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу GCash, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.