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

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

Для начала работы необходимо сделать запрос на получение платежного метода, подставив id платежного метода в URL.

Swagger - подробное API платежных методов.

Механика работы

1. Подключить платежные методы в системе FirstPay к своему мерчанту.
2. Данные по платежному методу можно получить по запросу POST https://{firstpay_url}/api/payment_methods/v1/{id}.
3. Важно!!! Запрос за получением информации о платежном методе необходимо делать каждый раз перед тем как пользователь попадет на страницу платежа. Так как информация в платежном методе динамическая (поле 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) (опционально)
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,
    "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 метод на отправку платежа не имеет ограничения.
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	Значение поля Это значение зачастую нужно дать пользователю скопировать из интерфейса формы.

Как работать с полями платежного метода

Здесь пример формы оплаты с полями из платежного метода. Форма может быть в любом виде, это именно показательный пример как правильно интерпретировать поля.

1. Блок с вводом кол-ва средств. Amount - всегда имеет тип number. На скрине 300 - это поле minPaymentAmount, 50000 - maxPaymentAmount, INR - currency.
2. Подсказки/хинты. Здесь detailFieldsHint относится к верхнему блоку - detailFields, где указаны необходимые поля с информацией о перечислении средств для пользователя. А clientFieldsHint относится к блоку с полями, которые заполняет пользователь. detailFieldsHint/clientFieldsHint можно использовать как подсказки/пояснения к блокам.
3. Блок с информацией о том, куда перечислять средства. Здесь могут быть несколько полей, все зависит от платежного метода. Желательно всем этим полям навешивать иконку "copy", чтобы пользователь мог скопировать значение из каждого поля (value). В данном случае "PhonePe wallet" - поле name, "test@upi" - value.
4. Блок с полями, которые заполняет пользователь. Здесь могут быть несколько полей, все зависит от платежного метода. Каждое поле имеет свой тип валидации. В данном случае "UTR number" - name. А type/minLength/maxLength валидация, которая применяется к вводимому значению "123456789012".