Проверка доступности платежных методов

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

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

Чтобы проверить доступность платежных методов, отправьте платежной платформе PSPHost запрос через Gate API. О том, как отправить такой запрос и какую информацию вы получите в ответе на него, рассказывается далее в этой статье.

Запрос

Ниже представлена информация, необходимая для создания и отправки запроса на проверку доступности платежных методов:


HTTP-метод запроса	POST
Формат тела запроса	JSON
Конечная точка	/v2/info/available_methods_for_merchant/list

Табл. 1. Параметры запроса на проверку доступности платежных методов
Объект/Параметр		Описание
project_id integer strictly required		Идентификатор проекта, полученный от PSPHost при интеграции. Пример: `123`
directions array strictly required		Передавайте в этом массиве: `payin` — для получения списка платежных методов, доступных для оплаты; `payout` — для получения списка платежных методов, доступных для выплаты. Пример: `payin`
currency string optional		Код валюты платежа в формате ISO-4217 alpha-3. Добавьте этот параметр в запрос, чтобы в ответе получить список платежных методов, доступных для проведения платежа по указанной валюте. Пример: `USD`
amount integer optional		Сумма платежа в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют. Передавайте этот параметр в запросе вместе с параметром currency, чтобы в ответе получить список платежных методов, доступных для проведения платежа по указанной в запросе сумме и валюте. Пример: 10,00 USD передается как `1000`
show_unavailable_methods_by_rules boolean optional		Параметр, который вы можете добавить в запрос, чтобы в ответе получить список недоступных платежных методов. Если вы передадите в запросе этот параметр со значением `true`, в ответе вы получите массивы с платежными методами, недоступными из-за: расписания работы платежного метода. В массиве будет содержаться информация о том, когда платежный метод возобновит работу. несоответствия суммы запроса сумме лимита платежа. В массиве будет содержаться информация о том, какая у платежного метода допустимая минимальная и максимальная сумма платежа. Чтобы получить в ответе массив с этой информацией, передайте также в запросе параметры currency и amount. Пример: `true`
is_enable_check_by_trusted_pm_user_rules boolean optional		Параметр, который вы можете добавить в запрос, чтобы в ответе получить список платежных методов для отображения доверенному пользователю. Если вы передадите в запросе этот параметр со значением `true`, платежная платформа проверит, доверенный ли пользователь совершает оплату, и на основании результата проверки отправит вам в ответе соответствующий список платежных методов. Передавайте этот параметр в запросе вместе с параметром customer_id, чтобы в ответе получить платежные методы, доступные для конкретного пользователя. Пример: `true`
customer object optional	id string optional	Идентификатор пользователя, уникальный в рамках проекта. Передавайте этот параметр в запросе вместе с параметром is_enable_check_by_trusted_pm_user_rules, чтобы в ответе получить платежные методы, доступные для конкретного пользователя. Пример: `customer_123`
payment_method string optional		Код платежного метода, доступность которого нужно проверить. Используйте этот параметр в запросе, если хотите проверить доступность конкретного платежного метода. Код платежного метода указан в параметре method, содержащемся в оповещении (callback). Пример: `example_method`
signature string strictly required		Подпись запроса, составленная после определения всех параметров запроса. Подробнее о составлении подписи см. Подписывание и проверка подписи.

Вот пример основного набора параметров из запроса на проверку доступности платежных методов. В ответе на такой запрос платежная платформа отправит вам информацию о доступных платежных методах по указанному проекту:

Рис. 1. Пример основного набора параметров из запроса на проверку доступности платежных методов

 {
   "project_id": 1234,
   "directions": [
      "payin",
      "payout"
   ],
   "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
}

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

Рис. 2. Пример параметров из запроса на проверку доступности конкретного платежного метода

{
   "project_id": 1234,
   "directions": [
      "payin",
      "payout"
   ],
   "payment_method": "example_method",
   "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
}

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

Рис. 3. Пример запроса на проверку доступности платежных методов с дополнительными параметрами

{
   "project_id": 1234,
   "directions": [
      "payin",
      "payout"
   ],
   "currency": "RUB",
   "amount": 100000,
   "show_unavailable_methods_by_rules": true,
   "is_enable_check_by_trusted_pm_user_rules": true,
   "customer": {
      "id": "123"
   },
   "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
}

Ответ

Ответ на запрос на проверку доступности платежных методов отправляется синхронно, то есть в рамках одной HTTP-сессии. Если ваш запрос был составлен правильно, платежная платформа ответит на него кодом состояния HTTP 200 OK и передаст вам в ответе информацию о доступных платежных методах.

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

{
   "available_payment_methods_by_trusted_user_rules": {
      "RUB": [
         {
            "title": "method_1",
            "direction": "payin"
         },
         {
            "title": "method_2",
            "direction": "payin"
         }
      ]
   },
   "available_payment_methods": {
      "RUB": [
         {
            "title": "method_3",
            "direction": "payin",
            "limits": {
               "min_amount": 10000,
               "max_amount": 1000000
            }
         },
         {
            "title": "method_4",
            "direction": "payin",
            "limits": {
               "min_amount": 90000,
               "max_amount": 1000000
            }
         }
      ],
      "USD": [
         {
            "title": "method_5",
            "direction": "payin",
            "limits": {
               "min_amount": 10000,
               "max_amount": 1000000
            }
         }
      ]
   },
   "unavailable_payment_methods_by_limits": {
      "PHP": [
         {
            "title": "method_6",
            "direction": "payin",
            "min_amount": 10000,
            "max_amount": 560000,
            "currency": "PHP"
         }
      ]
   },
   "unavailable_payment_methods_by_schedule": {
      "PHP": [
         {
            "title": "method_7",
            "direction": "payin",
            "will_be_available": "13/10/2022 18:30 GMT+03:00"
         }
      ],
      "USD": [
         {
            "title": "method_8",
            "direction": "payin",
            "will_be_available": "11/11/2022 12:00 GMT +03:00"
         }
      ]
   }
}

Если запрос был составлен неправильно или платежная платформа не смогла обработать ваш запрос, ответ будет содержать:

код состояния HTTP, отличный от 200 OK;
статус обработки запроса error;
описание причины обнаруженной ошибки.

В таблице ниже перечислены возможные коды, которые вы можете получить в ответе на запрос на проверку доступности платежных методов:

Табл. 2. Возможные коды ответов
Код	Описание
`200`	Запрос успешен. В ответе содержится информация о платежных методах, доступных для проведения платежа, и их лимитах
`400`	Используется в нескольких случаях: Запрос составлен некорректно, отсутствуют обязательные параметры. Скорректируйте запрос Платежный метод не найден. Убедитесь, что в запросе переданы корректные код платежного метода и валюта
`403`	Невозможно выполнить запрос из-за отсутствия прав, например, если запрос был отправлен с IP-адреса, не включенного в список разрешенных адресов. Свяжитесь со службой технической поддержки
`422`	Некорректный JSON. Скорректируйте запрос
`500`	Внутренняя ошибка сервера. Повторите запрос