Dragonpay

Обзор

Dragonpay — группа методов для проведения платежей через интернет-банкинг, наличными через банкоматы (ATM) и партнёрские точки приёма платежей (OTC), а также с использованием мобильного кошелька Gcash. Для работы с этой группой методов доступно проведение оплат через Payment Page и Gate.

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

Типы платёжных методов
  • интернет-банкинг
  • оплата наличными
  • мобильный кошелёк
Регионы использования PH
Валюты платежей PHP
Конвертация валют на стороне ECommPay (подробнее — в разделе Конвертация валют)
Оплаты +
Выплаты *
Оплаты по сохранённым данным
Полные возвраты +
Частичные возвраты +
Опротестования
Особенности
  • В рамках группы методов Dragonpay поддерживается проведение выплат на территории Филиппин с использованием метода Banks of the Philippines
  • Поддержка полных и частичных возвратов осуществляется со стороны Dragonpay
Организация и стоимость подключения По согласованию с курирующим менеджером ECommPay

Схема работы

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

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

Интерфейсы Суммы, PHP
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) Минимум Максимум
Оплаты + + 1,01 1 999 999,99
Полные возвраты * * * *
Частичные возвраты * * * *

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

Информация о вариантах проведения оплат и допустимых суммах для каждого из вариантов приведена далее, в пункте Варианты оплат и ограничения для них.

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

Проведение оплат с использованием методов Dragonpay выполняется с перенаправлением пользователей к форме оплаты Dragonpay.

Рис.: Оплата через Payment Page

Рис.: Оплата через Gate

Варианты проведения оплат и ограничения для них

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

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

Табл. 1. Варианты оплат и их ограничения
Код Вариант оплаты Суммы, PHP
Минимум Максимум
Интернет-банкинг
BDO BDO Internet Banking 1,01 999 999,99
BOG Bogus Bank * *
BPI BPI ExpressOnline (Fund Transfer) 1,01 999 999,99
BPIB BPI ExpressOnline (Bills Payment) 50,01 1 999 999,99
MBTC Metrobankdirect 1,01 999 999,99
CBC Chinabank Online * *
LBPA Landbank ATM Online 1,01 199 999,99
RCBC RCBC Online Banking 1,01 999 999,99
RSB RobinsonsBank Online Bills Payment 10,01 999 999,99
UBE Unionbank EON 1,01 999 999,99
UBP Unionbank Internet Banking 1,01 999 999,99
UCPB UCPB Connect 1,01 999 999,99
AUAL Alipay * *
AUWC WeChat Pay * *
BITC Bitcoin * *
Оплата наличными через банкоматы (ATM) или партнёрские точки приёма платежей (OTC)
BDOA Banco de Oro ATM 200,01 999 999,99
BDRX BDO Cash Deposit w/ Ref 1,01 1 999 999,99
BPXB BPI Bills Payment 1,01 999 999,99
MBTX Metrobank Cash/Check Payment 1,01 1 999 999,99
AUB AUB Online/Cash Payment 10,01 999 999,99
BOGX Bogus Bank Over the Counter * *
CBCX Chinabank ATM/Cash Payment 1,01 11 999,99
EWBX EastWest Online/Cash/Check Payment 1,01 49 999,99
LBXB Landbank Cash Payment 1,01 999 999,99
PNBB PNB eBanking Bills Payment 1,01 999 999,99
PNXB PNB Cash Payment 1,01 999 999,99
RCXB RCBC Cash Payment 25,01 999 999,99
RSBB RobinsonsBank Over the Counter 1,01 999 999,99
RSXB RCBC Savings Cash Payment 1,01 999 999,99
SBCA Security Bank ATM Bills Payment 1,01 999 999,99
SBCB Security Bank Cash Payment 1,01 999 999,99
UBXB Unionbank Cash Payment 1,01 1 999 999,99
UCXB UCPB ATM/Cash Payment 1,01 999 999,99
BAYD Bayad Center 50,01 199 999,99
LBC LBC 50,01 199 999,99
SMR SM Dept/Supermarket/Savemore Counter 50,01 199 999,99
CEBP Cebuana Lhuillier PeraPal 1,01 1 499,99
MLH M. Lhuillier 180,01 999 999,99
* Cebuana Lhuillier Bills Payment 1 500,01 999 999,99
RDS Robinsons Dept Store 50,01 199 999,99
ECPY ECPay (Pawnshops, Payment Centers) 50,01 999 999,99
RLNT RuralNet Banks and Coops 20,01 99 999,99
Мобильный кошелёк
GCSH Globe GCash 1,01 2 499,99
* Информацию необходимо уточнять у специалистов технической поддержки Dragonpay.

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

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

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

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

Рис.: Проведение оплаты через Payment Page

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

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

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

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

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_amount — сумма платежа в минорных единицах валюты;
    • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
    • customer_id — идентификатор пользователя, уникальный в рамках проекта.
  2. Для предварительного выбора одного из методов Dragonpay необходимо указывать этот метод в параметре force_payment_method:
    • online-banking-dragonpay для интернет-банкинга,
    • otc-atm-dragonpay для оплат наличными,
    • mobile-dragonpay для мобильного кошелька.
  3. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page.
  4. После указания целевых параметров необходимо составлять подпись (подробнее — в разделе Использование подписи к данным).

Таким образом, корректный запрос на открытие платёжной формы с применением метода Dragonpay должен содержать идентификатор, сумму и валюту платежа, идентификаторы проекта и пользователя и подпись:

EPayWidget.run(
    { payment_id: 'ECT_TEST_15470375651583', 
      payment_amount: 1000, 
      payment_currency: 'PHP', 
      project_id: 580, 
      customer_id: 'customer1',
      signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9...=="
    }
)

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

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

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

К особенностям группы методов Dragonpay можно отнести то, что в оповещениях не передаётся название отдельного метода, но передаются следующие данные:
  • название группы методов dragonpay — в параметре method объекта payment;
  • вариант оплаты, выбранный пользователем в рамках отдельного метода — в параметре endpoint_id объекта operation.provider (информация о вариантах оплат и соответствующих им буквенных кодах представлена в пункте Варианты оплат и ограничения для них).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 580 была успешно проведена оплата в размере 10,00 PHP с использованием выбранного пользователем варианта оплаты UCPB ATM/Cash Payment.

Рис.: Пример оповещения о проведении оплаты

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_15470375651583",
            "type": "purchase",
            "status": "success",
            "date": "2019-01-14T15:32:47+0000",
            "method": "dragonpay",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "ECT_TEST_15470375651583"
        },
        "operation": {
            "id": 19907000002680,
            "type": "sale",
            "status": "success",
            "date": "2019-01-14T15:32:47+0000",
            "created_date": "2019-01-14T15:29:25+0000",
            "request_id": "1f6b17a91782602b127403ba97f0b2cff2d827
                                91-92d62a12c048b7cb7c057cfb11112119c7db8307",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1165,
                "payment_id": "WVUFHH55",
                "auth_code": "",
                "endpoint_id": "UCXB"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "FZZUc4IZa1zO+WokUvz063QqsFnUPevaQBE8l/Zq3hddq9w
                            yhWRWkeLL8xdU8sWDWFn54K3f0BVSakCedm2dxw=="
    }

В следующем примере оплата была отклонена из-за нарушения ограничения на сумму или частоту оплаты.

Рис.: Пример оповещения об отказе в проведении оплаты

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_1547027708135",
            "type": "purchase",
            "status": "decline",
            "date": "2019-01-09T12:58:04+0000",
            "method": "dragonpay",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "ECT_TEST_1547027708135"
        },
        "operation": {
            "id": 12225000002575,
            "type": "sale",
            "status": "decline",
            "date": "2019-01-09T12:58:04+0000",
            "created_date": "2019-01-09T12:27:59+0000",
            "request_id": "ac0ff611f811045c4b3f82c499158c0d02f9e
                            1d5-4343dab2d9ffbd3d71d453931db2a1870aed09eb",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1165,
                "payment_id": "U3N9EUE4",
                "date": "2019-01-09T20:28:05+0000",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "Cova73mh3yF+2awvR5qDPN1DpVAfv+LVQanLRze1KjqkNYWri
                           8KtVl5A6W2wve4gZPq/m/uDS618+RTk4sSB3w=="
    }

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

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

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

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

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

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

Рис.: Проведение оплаты через Gate

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

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

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

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

  1. Должен использоваться запрос /v2/payment/online-banking/dragonpay/sale, отправляемый методом POST. Этот запрос относится к группе запросов для интернет-банкинга /v2/payment/online-banking/{payment_method}/sale.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты;
      • currency — валюта платежа в формате ISO-4217 alpha-3;
      • extra_param — название отдельного метода Dragonpay:
        • online_banking для интернет-банкинга,
        • otc_atm для оплат наличными,
        • mobile для мобильного кошелька;
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор, уникальный в рамках проекта,
      • ip_address — IP-адрес пользователя.
  3. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

{
    "general": {
        "project_id": 2852,
        "payment_id": "EPd6db-b9db",
        "signature": "U5LCm6489ly9cXCKIVBNV0mFr4XiCruECSyQEbT1hSXJ70zuH4s05cFDqLks8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "PHP",
        "extra_param": "online_banking"
    },
    "customer": {
        "ip_address": "248.121.176.220",
        "id": "123"
    }
}

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

Для перенаправления пользователя от веб-сервиса к форме оплаты Dragonpay необходимо:

  1. Принять от платёжной платформы оповещение с объектом redirect_data.
  2. Сформировать конечный URL вида {url}?tokenid={tokenid}&mode={mode} с использованием значений параметров redirect_data.
  3. Обратиться к конечному URL методом GET.

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

  • method — метод запроса;
  • body — объект, содержащий следующие сведения:
    • tokenid — идентификатор токена на оплату (действительный в течение одного часа);
    • mode — числовой идентификатор одного из платёжных методов Dragonpay:
      • 1 для интернет-банкинга,
      • 6 для оплат наличными,
      • 128 для мобильного кошелька;
  • url — базовый URL для перенаправления к форме Dragonpay.

Далее приведён фрагмент оповещения с необходимыми параметрами: методом запроса, идентификаторами токена и одного из платёжных методов Dragonpay, а также базовым URL.

"redirect_data": {
            "method": "GET",
            "body": {
                "tokenid": "f252d914dce5f0522da611d9e33fb781",
                "mode": "1"
            },
            "encrypted": [],
            "url": "https://gw.dragonpay.ph/Pay.aspx"
        }

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

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

К особенностям группы методов Dragonpay можно отнести то, что в оповещениях не передаётся название отдельного метода, но передаются следующие данные:
  • название группы методов dragonpay — в параметре method объекта payment;
  • вариант оплаты, выбранный пользователем в рамках отдельного метода — в параметре endpoint_id объекта operation.provider (информация о вариантах оплат и соответствующих им буквенных кодах представлена в пункте Варианты оплат и ограничения для них).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 580 была успешно проведена оплата в размере 10,00 PHP с помощью выбранного пользователем варианта оплаты UCPB ATM/Cash Payment.

Рис.: Пример оповещения о проведении оплаты

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_15470375651583",
            "type": "purchase",
            "status": "success",
            "date": "2019-01-14T15:32:47+0000",
            "method": "dragonpay",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "ECT_TEST_15470375651583"
        },
        "operation": {
            "id": 19907000002680,
            "type": "sale",
            "status": "success",
            "date": "2019-01-14T15:32:47+0000",
            "created_date": "2019-01-14T15:29:25+0000",
            "request_id": "1f6b17a91782602b127403ba97f0b2cff2d
                                82791-92d62a12c048b7cb7c057cfb11112119c7db8307",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1165,
                "payment_id": "WVUFHH55",
                "auth_code": "",
                "endpoint_id": "UCXB"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "FZZUc4IZa1zO+WokUvz063QqsFnUPevaQBE8l/Zq3hddq
                            9wyhWRWkeLL8xdU8sWDWFn54K3f0BVSakCedm2dxw=="
    }

В следующем примере оплата была отклонена из-за нарушения ограничения на сумму или частоту оплаты.

Рис.: Пример оповещения об отказе в проведении оплаты

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_1547027708135",
            "type": "purchase",
            "status": "decline",
            "date": "2019-01-09T12:58:04+0000",
            "method": "dragonpay",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "ECT_TEST_1547027708135"
        },
        "operation": {
            "id": 12225000002575,
            "type": "sale",
            "status": "decline",
            "date": "2019-01-09T12:58:04+0000",
            "created_date": "2019-01-09T12:27:59+0000",
            "request_id": "ac0ff611f811045c4b3f82c499158c0d02f9e1d
                                5-4343dab2d9ffbd3d71d453931db2a1870aed09eb",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1165,
                "payment_id": "U3N9EUE4",
                "date": "2019-01-09T20:28:05+0000",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "Cova73mh3yF+2awvR5qDPN1DpVAfv+LVQanLRze1KjqkNY
                           Wri8KtVl5A6W2wve4gZPq/m/uDS618+RTk4sSB3w=="
    }

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

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

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

Как и при работе с другими платёжными методами, которые предоставляет ECommPay, при использовании метода Dragonpay доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей на вкладке Analytics.

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

  • Dashboard (Old Dashboard) позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
  • Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

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