Banks of the Philippines

Введение

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

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

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

Схема работы

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

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

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

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

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

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

Проведение оплат с использованием метода Banks of the Philippines осуществляется с перенаправлением пользователей к сервису Banks of the Philippines, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.

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

100%

100%

Переход к оплате

Выбор метода

Выбор банка

Аутентификация

Подтверждение платежа

Возвращение к форме

Возвращение к веб-сервису

Общие сценарии проведения оплат и выплат можно представить следующим образом.

100%

100%

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

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

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

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

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

Вместе с тем, для оплат этим методом поддерживаются разные варианты выбора банка; они описаны в разделе Оплаты через Payment Page этой статьи.

Поддержка со стороны банков

В следующей таблице в ознакомительных целях приведены названия и идентификаторы банков, поддерживающих работу с методом Banks of the Philippines. Каждому банку соответствуют свой идентификатор, который используется при инициировании выплат через Gate, и буквенный код, который используется в оповещениях о результатах выплат для идентификации банка.

Поскольку со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать POST-запрос к конечной точкеконечным точкам /v2/info/banks/philippines/sale/list(для оплат) и /v2/info/banks/philippines/payout/list (для выплат), которые относятся к группе конечных точек /v2/info/banks/{payment_method}/{operationType}/list Gate API. В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений.

{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1500,
    "currency": "PHP"
  }
}

[
  {
    "id": 2241, // Индентификатор банка
    "abbr": "BDOC", // Служебная аббревиатура банка, используемая в платформе
    "name": "BDO Corporate Internet Banking", // Основное (международное) название банка
    "nativeName": "BDO Corporate Banking", // Локальное (национальное или региональное) название банка
    "currencies": [ // Массив с информацией о валютах, поддерживаемых банком
      {
        "id": 1076, // Идентификатор валюты в платёжной платформе
        "alpha_3_4217": "PHP", // Буквенный код валюты платежа в формате ISO-4217 alpha-3
        "number_3_4217": "608", // Цифровой код валюты платежа в формате ISO-4217 alpha-3
        "exponent": 2 // Число дробных разрядов валюты
      }
    ]
  },
  {
    "id": 1571, 
    "abbr": "CTBC", 
    "name": "Chinatrust", 
    "nativeName": "Chinatrust",
    "currencies": [
      {
        "id": 1076,
        "alpha_3_4217": "PHP",
        "number_3_4217": "608",
        "exponent": 2
      }
    ]
  },
  {
    "id": 2241, 
    "abbr": "MAY", 
    "name": "Maybank", 
    "nativeName": "Maybank",
    "currencies": [
      {
        "id": 1076,
        "alpha_3_4217": "PHP",
        "number_3_4217": "608",
        "exponent": 2
      }
    ]
  }
]

С вопросами о работе с банками, поддерживающими метод Banks of the Philippines, можно обращаться к курирующему менеджеру ecommpay.

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

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

Как правило, после того как пользователь на стороне веб-сервиса подтверждает готовность перейти к оплате, он перенаправляется к Payment Page, выбирает платёжный метод и, в случае работы с методом Banks of the Philippines, дополнительно выбирает один из доступных банков. Вместе с тем, в некоторых ситуациях могут быть актуальны другие варианты выбора платёжного метода и банка. Например, при открытии Payment Page можно сразу перенаправлять пользователя к выбору банка либо ограничивать список поддерживаемых банков для отдельного платежа и отображать пользователю только кнопки выбора целевых банков. Конкретный вариант выбора платёжного метода и банка определяется через параметры, указанные в запросе на открытие Payment Page (подробнее Формат запросов), при этом допустимы следующие варианты:

• 1 — при открытии платёжной формы в ней последовательно отображаются отдельные страницы для выбора метода и банка, и пользователь выбирает сначала метод, а затем банк (этот вариант используется по умолчанию);
• 2 — при открытии платёжной формы в ней отображается страница с кнопками выбора методов и банков для данного метода, и пользователь выбирает один из этих банков;
• 3 — при открытии платёжной формы в ней отображается страница с кнопками выбора всех доступных банков для данного метода, и пользователь выбирает один из этих банков;
• 4 — при открытии платёжной формы в ней отображается страница с кнопками выбора заданных банков для данного метода, и пользователь выбирает один из этих банков;
• 5 — при открытии платёжной формы в ней отображается страница подтверждения перенаправления к сервису заданного банка, и пользователь соглашается с этим перенаправлением.

100%

100%

1 — Выбор метода и банка

2 — Выбор банка среди доступных методов

3 — Выбор среди доступных банков

4 — Выбор среди заданных банков

5 — Перенаправление к сервису заданного банка

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

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

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

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. Дополнительно рекомендуется указывать адрес электронной почты пользователя в параметре customer_email. Также может потребоваться указание имени и фамилии пользователя в параметрах customer_first_name и customer_last_name соответственно. Необходимость использования этих параметров следует уточнять у курирующего менеджера ecommpay. Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений (подробнее — в разделе Дополнение информации о платежах).

4. Вариант выбора банка может определяться следующим образом:

   1. Через выбор в Payment Page метода и банка (1) — как вариант по умолчанию, применяемый, если не указываются параметр force_payment_method и объект payment_methods_options, упоминаемые в подпунктах 2–5.
   2. Через выбор в Payment Page банка среди доступных методов (2) — для этого в объекте payment_methods_options необходимо указывать объект online_philippines_banks, содержащий параметр split_banks со значением true:

      "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true}}"

   3. Через выбор в Payment Page банка из числа доступных (3) — для этого в параметре force_payment_method необходимо указывать код предварительного выбора метода online-philippines-banks.
   4. Через выбор в Payment Page банка из числа заданных (4) — для этого необходимо указывать:
      • код online-philippines-banks в параметре force_payment_method;
      • объект payment_methods_options с объектом online_philippines_banks, который должен содержать параметр split_banks со значением true и объект banks_id с массивом, включающим в себя идентификаторы целевых банков:

        "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true, \"banks_id\": [2261, 2271]}}"

   5. Через подтверждение в Payment Page перенаправления к сервису заданного банка (5) — для этого необходимо указывать:
      • код online-philippines-banks в параметре force_payment_method;
      • объект payment_methods_options с объектом online_philippines_banks, который должен содержать параметр split_banks со значением true и объект banks_id с массивом, включающим в себя идентификатор целевого банка:

        "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true, \"banks_id\": [2261]}}"

5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PHP",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PHP",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Вместе с тем, в случае с выбором из заданных банков (4), запрос на открытие Payment Page может содержать расширенный набор данных.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "PHP",
   "customer_id": "customer1",
   "customer_email": "test@example.com",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "force_payment_method": "online-philippines-banks",
   "payment_methods_options": {"online_philippines_banks": {"split_banks": true, "banks_id": [2261, 2271]}}
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfd",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 464,
            "type": "sale",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA=="
    }
}

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

 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfc",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 465,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000002",
            "sum_initial": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGob=="
    }
}

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

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

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

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

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

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

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

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

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

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

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке v2/payment/banks/philippines/sale. Эта точка относится к группе /v2/payment/banks/{payment_method}/sale.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
     • email — адрес электронной почты пользователя,
   • account — объект, содержащий сведения о банковском счёте пользователя:
     • bank_id — идентификатор банка;
   • return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис мерчанта:
     • success — URL для перенаправления пользователя в случае успешной оплаты.
3. Дополнительно рекомендуется указывать следующие объекты и параметры:
   • customer — объект, содержащий сведения о пользователе:
     • first_name — имя пользователя,
     • last_name — фамилия пользователя.

   Необходимость использования этих параметров следует уточнять у курирующего менеджера ecommpay. Если какие-либо из этих параметров отсутствуют в запросе, список с названиями недостающих параметров может отправляться в оповещении на уточнение (подробнее — в статье Дополнение информации о платеже).

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

Таким образом, корректный запрос на оплату с применением метода Banks of the Philippines должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, идентификатор банка и URL для перенаправления, а также подпись.

{
    "general": {
        "project_id": 580,
        "payment_id": "test_philippines_sale",
        "signature": "pgwRHcfv2OTsdILn33R5Nr/yMx/9FSeIqYHTTd6YhIiLWw=="
    },
    "payment": {
        "amount": 1000,
        "currency": "PHP"
    },
    "customer": {
        "id": "123",
        "email": "test_customer@example.com",
        "ip_address": "192.0.2.0",
        "first_name": "John",
        "last_name": "Doe"
    },
    "account": {
        "bank_id": 2681
    },
    "return_url": {
        "success": "http://example.com/success"
    }
}

{
    "general": {
        "project_id": 580,
        "payment_id": "test_philippines_sale",
        "signature": "pgwRHcfv2OTsdILn33R5Nr/yMx/9FSeIqYHTTd6YhIiLWw=="
    },
    "payment": {
        "amount": 1000,
        "currency": "PHP"
    },
    "customer": {
        "id": "123",
        "email": "test_customer@example.com",
        "ip_address": "192.0.2.0",
        "first_name": "John",
        "last_name": "Doe"
    },
    "account": {
        "bank_id": 2681
    },
    "return_url": {
        "success": "http://example.com/success"
    }
}

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

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

• body — объект с данными для отправки в теле запроса;
• method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
• url — параметр со ссылкой для перенаправления.

"redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
  }

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

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

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

 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfd",
            "type": "purchase",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 464,
            "type": "sale",
            "status": "success",
            "date": "2020-03-06T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA=="
    }
}

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

 {
        "project_id": 239,
        "payment": {
            "id": "EPfa87-bcfc",
            "type": "purchase",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "description": ""
        },
        "operation": {
            "id": 465,
            "type": "sale",
            "status": "decline",
            "date": "2020-03-07T14:11:00+0000",
            "created_date": "2020-03-06T14:10:34+0000",
            "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000002",
            "sum_initial": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 200000000,
                "currency": "PHP"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
            "provider": {
                "id": 1369,
                "payment_id": "7QKID3P3",
                "auth_code": "",
                "endpoint_id": "BOG",
                "date": "2020-03-06T14:10:54+0000"
            }
        },
        "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGob=="
    }
}

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

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

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

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

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

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

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

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

1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/philippines/payout. Эта точка относится к группе /v2/payment/banks/{payment_method}/payout.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма выплаты в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
     • description — описание платежа;
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;,
   • account — объект, содержащий сведения о банковском счёте пользователя:
     • bank_id — идентификатор банка,
     • customer_name — имя держателя банковского счета,
     • number — номер счёта.
3. Валютой платежа может быть только PHP.
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {
    "project_id": 445,
    "payment_id": "1000003",
    "signature": "PJkV8ej\/UG0Di8hTng6fBaNIipTv+AWoXW\/9MTO8yJA=="
  },
 "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "PHP",
    "description": "Payout description"
  },
    "account": {
    "bank_id": 486,
    "customer_name": "John Doe",
    "number": "1670033323"
  }
}

{
  "general": {
    "project_id": 445,
    "payment_id": "1000003",
    "signature": "PJkV8ej\/UG0Di8hTng6fBaNIipTv+AWoXW\/9MTO8yJA=="
  },
 "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 1000,
    "currency": "PHP",
    "description": "Payout description"
  },
    "account": {
    "bank_id": 486,
    "customer_name": "John Doe",
    "number": "1670033323"
  }
}

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

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

К особенностям метода Banks of the Philippines можно отнести то, что название банка, в котором открыт счёт пользователя, указывается в параметре endpoint_id объекта operation.provider (информация о банках и соответствующих им буквенных кодах представлена в пункте Поддержка со стороны банков).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 445 для пользователя 123 была проведена выплата в размере 10,00 PHP на счёт 1670033323, открытый в банке Banco de Oro CA/SA.

 {
        "project_id": 445,
        "payment": {
            "id": "100011",
            "type": "payout",
            "status": "success",
            "date": "2019-03-18T08:06:13+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "payout"
        },
        "account": {
            "number": "1670033323"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 147,
            "type": "payout",
            "status": "success",
            "date": "2019-03-18T08:06:13+0000",
            "created_date": "2019-03-18T08:06:06+0000",
            "request_id": "9499286583e3d1102f752a9cd47d2fb7469cc613e11",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1346,
                "payment_id": "6Q2G5D83",
                "date": "2019-03-18T08:06:11+0000",
                "auth_code": "",
                "endpoint_id": "BDO"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "oFGfjOtZZkFxi7Pd1yikCw01b0BsedgKr8z/E8qfizh1A=="
    }

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

{
        "project_id": 445,
        "payment": {
            "id": "100014",
            "type": "payout",
            "status": "decline",
            "date": "2019-03-18T10:49:50+0000",
            "method": "Philippines banks",
            "sum": {
                "amount": 900,
                "currency": "PHP"
            },
            "description": "payout"
        },
        "account": {
            "number": "1670033323"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 148,
            "type": "payout",
            "status": "decline",
            "date": "2019-03-18T10:49:51+0000",
            "created_date": "2019-03-18T10:49:46+0000",
            "request_id": "d626cece0855a8863f687985e6c57935d9872183c",
            "sum_initial": {
                "amount": 900,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 900,
                "currency": "PHP"
            },
            "provider": {
                "id": 1346,
                "payment_id": "YDK0QS4X",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "fz0Yu5BFLRLJez747kDfZHgmKGIOgMa5DAzPE/4GLWlZSzCwkdkqyrTqUQvLp6A=="
    }

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

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

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