QR Ph

Введение

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

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

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

Схема работы

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

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

Для проведения платежей и выполнения операций с использованием метода QR Ph могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а возвраты и выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, минимальная сумма оплаты составляет 100,00 PHP, максимальная — 50 000,00 PHP. За дополнительной информацией об ограничениях сумм платежей можно обращаться к курирующему менеджеру ecommpay.

При работе с методом QR Ph, независимо от используемых интерфейсов, минимальная сумма оплаты составляет 100,00 PHP, максимальная — 50 000,00 PHP.

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

Проведение оплат с использованием метода QR Ph осуществляется с сканированием QR-кодов пользователями с использованием мобильных приложений.

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

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

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

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

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

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

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

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • customer_id — идентификатор пользователя в рамках проекта.

   В зависимости от провайдера, используемого для проведения платежа, для его проведения могут потребоваться другие параметры (такие как customer_first_name, customer_last_name и customer_email. За дополнительной информацией о возможных требуемых параметрах следует обращаться к курирующему менеджеру ecommpay.

2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.

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

3. Для предварительного выбора метода QR Ph необходимо указывать код этого метода в параметре force_payment_method — ph-qr.
4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
5. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

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

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

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

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

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "QRPH",
        "sum": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 00000,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DScs9CRd4xeYG2Q=="
}

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "method": "QRPH",
        "sum": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 31,
        "type": "sale",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "created_date": "2022-03-25T11:19:53+0000",
        "request_id": "fff3d5f8d5d31bc460b68b57dc63f4b482e906eb",
        "sum_initial": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 00000,
            "payment_id": "0cf4215c-8978",
            "auth_code": ""
        }
    },
    "signature": "J7W15rkqrLzTCD4HkoM4qoEnl4z2iFYv58P4VnHANu445/jmY+g=="
}

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000000,
    "currency": "PHP"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000000,
    "currency": "PHP"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  }
}

Формат промежуточных оповещений для отображения QR-кодов пользователям

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

• type — тип передаваемых данных (в значении всегда передаётся qr_img);
• title — название передаваемых данных, которые необходимо отобразить пользователю (в значении всегда передаётся qr_img);
• data — строка, на основании которой на стороне веб-сервиса должен быть создан QR-код (в соответствии со стандартом ISO/IEC 18004:2015).

"display_data": [
            {
                "type": "qr_img",
                "title": "qr_img",
                "data": "data:image\/png;base64,iVB..."
            }
]

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

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

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "QRPH",
        "sum": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 00000,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DScs9CRd4xeYG2Q=="
}

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "method": "QRPH",
        "sum": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 31,
        "type": "sale",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "created_date": "2022-03-25T11:19:53+0000",
        "request_id": "fff3d5f8d5d31bc460b68b57dc63f4b482e906eb",
        "sum_initial": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "sum_converted": {
            "amount": 1000000,
            "currency": "PHP"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 00000,
            "payment_id": "0cf4215c-8978",
            "auth_code": ""
        }
    },
    "signature": "J7W15rkqrLzTCD4HkoM4qoEnl4z2iFYv58P4VnHANu445/jmY+g=="
}

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

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

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