Получение платежных методов
Платежный метод - сущность, которая хранит в себе всю информацию о предстоящем платеже.
Для начала работы необходимо сделать запрос на получение платежного метода, подставив id платежного метода в URL.
Swagger - подробное API платежных методов.
Механика работы
- Подключить платежные методы в системе FirstPay к своему мерчанту.
- Данные по платежному методу можно получить по запросу POST
https://{firstpay_url}/api/payment_methods/v1/{id}. - Важно!!! Запрос за получением информации о платежном методе необходимо делать каждый раз перед тем как пользователь попадет на страницу платежа.
Так как информация в платежном методе динамическая (поле
account), необходимо ее актуализировать каждый раз. То есть когда пользователь заходит на страницу платежных методов или выбирает "иконку" одного из платежных методов - необходимо послать запрос в FirstPay и получить актуальную информацию по платежному методу.
API
Для получения платежного метода по id: POST запрос https://{firstpay_url}/api/payment_methods/v1/{id}.
Таблица query параметров:
| Параметр | Тип | Обязательный | Описание | Пример |
|---|---|---|---|---|
| type | array[string] | Нет | У параметра есть два значения PAY_IN и PAY_OUT. Это тип платежного метода. Параметр не передается при запросе платежного метода по id. | .../v1?type=PAY_IN |
| locale | string | Нет | Возможные значения: en, hi, bn, az и другие. Параметр используется для локализации данных по заполняемым полям. Если не передавать параметр, то по дефолту переводы будут на en. | .../v1?locale=ru |
Таблица body параметров:
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| publicKey | string | Да | Авторизация |
| merchantPaymentId | string | Да | Идентификатор платежа в системе мерчанта |
| merchantUserId | string | Да | Идентификатор пользователя в системе мерчанта |
| amount | float | Да | Сумма платежа |
| level | enum | Нет | Сообщает о виде направляемого трафика, принимает три возможных значения: FTD (first time deposit), STD (second time deposit) и TRUSTED (доверенные юзеры). О точных настройках направляемого трафика необходимо уточнить у тех.поддержки. |
| paymentPageInfo | object | Нет | Данные для конфигурации Payment Page |
| paymentPageInfo.successUrl | string | Да | Ссылка для перенаправления пользователя после успешной оплаты |
| paymentPageInfo.cancelUrl | string | Да | Ссылка для перенаправления пользователя в случае отмены |
| paymentPageInfo.pendingUrl | string | Да | Ссылка для перенаправления пользователя во время обработки платежа |
| paymentPageInfo.failUrl | string | Да | Ссылка для перенаправления пользователя после неудачной оплаты |
| paymentPageInfo.postBackUrl | string | Нет | URL для постбэка по аналогии с платежами |
| hash | string | Да | Авторизация |
Таблица возвращаемых ответов:
| code | Тело ответа | Описание |
|---|---|---|
| 200 | Платежный метод | При успешном запросе возвращаются данные по платежному методу (либо массив платежных данных, в зависимости от вызванного метода). |
| 400 | {"error": "some text here..."} | Ошибка возникает, если не удалось распарсить тело запроса и query параметры. (скорее всего они были переданы с ошибкой). |
| 401 | {"error": "NO_LOGIN"} | Ошибка возникает, если не передали в теле запроса поле publicKey. |
| 401 | {"error": "NO_TOKEN"} | Ошибка возникает, если не передали в теле запроса поле hash. |
| 401 | {"error": "NO_KEY"} | Ошибка возникает, если передан неправильный publicKey. |
| 401 | {"error": "UNAUTHORIZED"} | Ошибка возникает, если произошла ошибка при валидации publicKey и hash. |
| 404 | {"error": "ACCOUNT_NOT_FOUND"} | Ошибка возникает, когда в системе нет свободного аккаунта, куда можно отправлять средства в данный момент. |
| 404 | {"error": "NOT_FOUND"} | Ошибка возникает при запросе платежного метода по id, если такого метода нет в системе. |
| 500 | {"error": "some text here..."} | Ошибка возникает, когда сервер не смог обработать запрос и произошла какая-то не штатная ситуация. |
Описание полей платежного метода
Интерфейс платежного метода:
{
"id": "string",
"type": "PAY_IN",
"name": "string",
"currency": "string",
"logoUrl": "string",
"minPaymentAmount": 0,
"maxPaymentAmount": 0,
"paymentPageUrl": "string" | null,
"isAttachmentRequired": true,
"detailFieldsHint": "string",
"clientFieldsHint": "string",
"clientFields": [
{
"key": "string",
"name": "string",
"validation": {
"type": "string",
"minLength": 0,
"maxLength": 0
}
}
],
"account": {
"id": 0,
"detailFields": [
{
"key": "string",
"name": "string",
"value": "string"
}
]
}
}
Таблица с описанием всех полей:
| Поле | Тип | Описание | |||||
|---|---|---|---|---|---|---|---|
| id | String | ID платежного метода. | |||||
| type | Enum | Тип платежного метода. Значениями этого поля могут быть либо PAY_IN, либо PAY_OUT. PAY_IN - для дебетов, PAY_OUT - для выплат. | |||||
| name | String | Название платежного метода. | |||||
| currency | Enum | ISO код валюты: USD, INR, BDT, PKR и тд. | |||||
| logoUrl | String | URL логотипа платежного метода. | |||||
| minPaymentAmount | Number | Минимально допустимый размер платежа. Важно!: эта нас тройка устанавливается либо мерчантом, либо платежным методом. Предполагается, что это ограничение на ввод будет на стороне формы оплаты. Так как API метод на отправку платежа не имеет ограничения. | |||||
| maxPaymentAmount | Number | Максимально допустимый размер платежа. Важно!: эта настройка устанавливается либо мерчантом, либо платежным методом Предполагается, что это ограничение на ввод будет на стороне формы оплаты. Так как API метод на отправку платежа не имеет ограничения. | |||||
| paymentPageUrl | String | Опциональное поле. Возвращается только если платёжный метод поддерживает Payment Page и в запросе были переданы все поля для paymentPageInfo. Поле доступно только в запросе за платёжным методом по id. | |||||
| isAttachmentRequired | Boolean | Необходимо ли при создании пеймента указывать поле attachmentId. | |||||
| detailFieldsHint | String | Хинт/Подсказка к набору полей из объекта account. | |||||
| clientsFieldsHint | String | Хинт/Подсказка к набору полей из объекта clientFields. | |||||
| clientFields | Array | Массив полей-инпутов для ввода данных клиента. Каждое поле содержит свой тип и валидацию. | |||||
| key | String | Идентификатор/id поля, он пригодится при отправке платежа после заполнения формы. | |||||
| name | String | Название инпут поля. Можно использовать как placeholder или тайтл. | |||||
| validation | Object | Валидация инпут поля. Каждое поле имеет ограничение на вводимые символы. | |||||
| type | Enum | Тип валидации, на данный момент имеются два типа STRING (только строковые символы) и NUMBER (только цифры). | |||||
| minLength | Number | Минимальное кол-во символов для вводимого значения. | |||||
| maxLength | Number | Максимальное кол-во символов для вводимого значения. | |||||
| account | Object | Объект с информацией о том, куда необходимо перечислять средства. | |||||
| id | Number | ID аккаунта, он понадобится при отправки платежа. | |||||
| detailFields | Array | Массив полей с информацией об аккаунте. | |||||
| key | String | Идентификатор/id поля. | |||||
| name | String | Название поля. Можно использовать как placeholder или тайтла. | |||||
| value | String | Значение поля Это значение зачастую нужно дать пользователю скопировать из интерфейса формы. | |||||
Как работать с полями платежного метода
Здесь пример формы оплаты с полями из платежно го метода. Форма может быть в любом виде, это именно показательный пример как правильно интерпретировать поля.
- Блок с вводом кол-ва средств. Amount - всегда имеет тип number. На скрине 300 - это поле minPaymentAmount, 50000 - maxPaymentAmount, INR - currency.
- Подсказки/хинты. Здесь detailFieldsHint относится к верхнему блоку - detailFields, где указаны необходимые поля с информацией о перечислении средств для пользователя. А clientFieldsHint относится к блоку с полями, которые заполняет пользователь. detailFieldsHint/clientFieldsHint можно использовать как подсказки/пояснения к блокам.
- Блок с информацией о том, куда перечислять средства. Здесь могут быть несколько полей, все зависит от платежного метода. Желательно всем этим полям навешивать иконку "copy", чтобы пользователь мог скопировать значение из каждого поля (value). В данном случае "PhonePe wallet" - поле name, "test@upi" - value.
- Блок с полями, которые заполняет пользователь. Здесь могут быть несколько полей, все зависит от платежного метода. Каждое поле имеет свой тип валидации. В данном случае "UTR number" - name. А type/minLength/maxLength валидация, которая применяется к вводимому значению "123456789012".