Отправление платежа

Запрос на создание платежа отправляется после того как пользователь заполнит все необходимые поля из платежного метода. Существует два типа платежа: PAY_IN (депозиты) и PAY_OUT (выплаты).

Swagger - подробное API платежей.

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

1. Пользователь заполняет форму данными, согласно полям платежного метода, полученного ранее. После чего подтверждает форму (нажимает подтвердить/оплатить и тд.).
2. В зависимости от типа платежного метода (PAY_IN или PAY_OUT) мерчант отправляет запрос на создание платежа:
   • POST запрос https://{firstpay_url}/api/payments/v1/pay_in - платеж при депозите.
   • POST запрос https://{firstpay_url}/api/payments/v1/pay_out - платеж при выплате.
3. Если запрос относится к платёжной системе (BKash и т.п.), в запросе можно указать "successRedirectUrl" и "failureRedirectUrl" - ссылки, куда будет перенаправлен пользователь после работы с платёжной системой. В противном случае, ответ будет с кодом 200.
4. Некоторые платежи могут потребовать SMS-подтверждение, подробнее тут.

API

Для отправки платежа на депозит: POST запрос https://{firstpay_url}/api/payments/v1/pay_in.

Для отправки платежа на выплату: POST запрос https://{firstpay_url}/api/payments/v1/pay_out.

Интерфейс тела запроса на создание платежа

{
   "publicKey": "string",
   "hash": "string",
   "accountId": 0,
   "paymentMethodId": "string",
   "amount": 0,
   "clientFieldsValues": [
      {
         "key": "string",
         "value": "string"
      }
   ],
   "merchantPaymentId": "string", // optional
   "merchantUserId": "string", // optional
   "successRedirectUrl": "string", // optional
   "failureRedirectUrl": "string", // optional
   "postBackUrl": "string", // optional
   "attachmentId": "string" // optional
}

Таблица с описанием всех полей тела запроса

Поле						Тип	Обязательный	Описание
publicKey						String	Да	Публичный ключ, который выдавался при регистрации мерчанта на платформе FirstPay (Ключ передается в файле, нужно передать все его содержимое).
hash						String	Да	Закодированная строка тела запроса. О том как ее сформировать - см. в разделе "Авторизация".
accountId						Number	Да	Id аккаунта, который приходит в платежном методе.
paymentMethodId						String	Да	Id платежного метода.
amount						Number	Да	Сумма платежа.
clientFieldsValues						Array	Да	Список заполненных полей пользователем. Все эти поля приходят в платежном методе.
	key					String	Да	Идентификатор/id поля.
	value					String	Да	Значение, заполненное пользователем.
merchantPaymentId						String	Нет	Опциональное поле. Можно указать id платежа в своей системе.
merchantUserId						String	Нет	Опциональное поле. Можно указать id пользователя в своей системе.
redirectUrl						String	Нет	Опциональное поле. При указании redirectUrl после создании платежа FirstPay сделает редирект на переданный url.
postBackUrl						String	Нет	Опциональное поле. При указании postBackUrl FirstPay после подтверждения платежа отправит запрос на переданный url. Если параметр не передан, то запрос будет отправлен на зарегистрированный url на странице мерчанта.
attachmentId						String	Нет	Если у платёжного метода поле isAttachmentRequired равняется true, то это поле становится обязательным. Необходимо загрузить изображение с подтверждением оплаты - см. в разделе "Загрузка медиа". В ответе придёт поле id, его как раз и нужно будет указать при создании платежа.

Таблица возвращаемых ответов:

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.
403	{"error": "ACCESS_DENIED"}	Ошибка возникает, если мерчант в запросе указал метод платежа, к которому не имеет доступа.
404	{"error": "NOT_FOUND"}	Ошибка возникает при запросе платежного метода по id, если такого метода нет в системе.
500	{"error": "some text here..."}	Ошибка возникает, когда сервер не смог обработать запрос и произошла какая-то не штатная ситуация.

Интерфейс тела ответа создания платежа:

{
   "isSucceed": true,
   "formUrl": "string",
   "paymentId": "string",
   "info": {
      "isSMSRequired": true, // optional
      "instruction": "string" || null, // optional
      "withDeepLink": "boolean", // optional
      "showQR": "boolean", // optional
      "deepLink": { // optional
         "paytm": "string" || null, // optional
         "phonepe": "string" || null, // optional
         "gpay": "string" || null // optional
      } || null
   }
}

Таблица с описанием всех полей:

Поле						Тип	Описание
isSucceed						Boolean	Успех.
formUrl						String	Опциональное поле, если платёж был создан на основе платёжной системы.
paymentId						String	Id платежа в системе FirstPay.
info						Object	Объект с дополнительной информацией.
	isSMSRequired					Boolean	Опциональное поле. Необходим ли дополнительный запрос на подтверждение платежа через SMS.
	instruction					String	Опциональное поле. Комментарий от системы получения платежа.
	withDeepLink					Boolean	Опциональное поле. Работает ли Deeplink для оплаты, и нужно ли отображать пользователю кнопку перехода в приложение.
	showQR					Boolean	Опциональное поле. Отображать ли QR-код на странице оплаты.
	deepLink					Object	Опциональное поле. Объект с ссылками приложений для оплаты. Если ссылка определена, нужно отображать соответствующую кнопку перехода в приложение для оплаты (диплинк).
		paytm				String	Ссылка для Paytm.
		phonepe				String	Ссылка для Phonepe.
		gpay				String	Ссылка для Ggpay.