Работа с postback запросами

Верификация платежей и жалоб построена по системе postback запросов. FirstPay отправляет запросы мерчанту с информацией о платежах или жалоб пользователя.

Это актуальный формат postback'ов, который вам необходимо использовать. Если вы использовали устаревший формат, информация о нём находится тут.

Swagger - подробное API postback'ов.

Механика работы для платежей

1. В разделе Регистрация мерчанта указывается URL для принятия postback запросов от FirstPay.
2. Мерчант реализует API согласно контракту. Эндпоинт должен обрабатывать POST запрос с параметрами из раздела API.
3. После обработки платежа от пользователя FirstPay отправляет POST запрос на переданный URL при создании платежа либо на указанный URL в системе.
4. Мерчант валидирует запросы и обрабатывает переданную информацию. В теле запроса приходит информация о совершенных платежах пользователя.
5. FirstPay ожидает ответ с кодом 200 на запрос (тело ответа может быть пустым). Только в этом случае FirstPay будет считать, что информация получена мерчантом. Если код ответа будет отличен от 200, то FirstPay будет с некоторой периодичностью пытаться отправлять запрос до тех пор, пока не получит код 200.
6. В некоторых случаях спустя какое-то время статус платежа может измениться повторно: с SUCCESS на FAILED или наоборот. Как следствие, будет отправлен повторный POST запрос с уже обновлённым статусом. Механизм работы с таким запросом аналогичен пунктам 3-5.

API платежей

FirstPay отправляет POST запрос на postback_url, который передали при создании платежа. Если его не передавали, то запрос отправляется на url, который мерчант указывал при регистрации в системе.

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

{
  "publicKey": "string",
  "hash": "string",

  "id": "string",

  "status": "string",
  "failedCode": "string" || null,

  "paymentMethodId": "string",
  "amount": 0,
  "currency": "string",

  "clientFieldsValues": [
    {
      "key": "string",
      "value": "string"
    }
  ],

  "merchantPaymentId": "string",
  "merchantUserId": "string",

  "createdAt": "2023-11-13T20:20:15.221Z"
}

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

Поле						Тип	Обязательный	Описание
publicKey						String	Да	Публичный ключ FirstPay, который необходим для валидации тела запроса.
hash						String	Да	Закодированная строка тела запроса. О том как ее валидировать - см. в разделе "Авторизация".
id						String	Да	ID платежа в системе FirstPay.
status						Enum	Да	Status платежа в системе FirstPay. В ответе всегда будет приходить либо SUCCESS, либо FAILED.
failedCode						Enum	Да	Данное поле характеризует ошибку при осуществлении платежа. Если status=`SUCCESS`, то в данном поле придет `null`. Если же status=`FAILED`, то failedCode будет содержать одно из значений: `INCORRECT_AMOUNT` (перечислено некорректное кол-во денежных средств), `NO_AMOUNT` (денежные средства не были перечислены), `INCORRECT_FIELDS` (поля в форме были заполнены неправильно), `ANOTHER_REASON` (другая ошибка, не относящаяся к вышеперечисленным).
paymentMethodId						String	Да	ID платежного метода.
amount						Number	Да	Сумма платежа.
currency						Enum	Да	ISO код валюты: USD, INR, BDT, PKR и тд.
clientFieldsValues						Array	Да	Список заполненных полей пользователем. Все эти поля отправляются при создании платежа мерчантом.
	key					String	Да	Идентификатор/id поля.
	value					String	Да	Значение, заполненное пользователем.
merchantPaymentId						String	Нет	Опциональное поле. ID платежа в системе мерчанта. Передается, если было указано при создании платежа.
merchantUserId						String	Нет	Опциональное поле. ID пользователя в системе мерчанта. Передается, если было указано при создании платежа.
createdAt						String	Да	UTC Timestamp создания платежа.

Механика работы для жалоб

1. Мерчант реализует API согласно контракту. Эндпоинт должен обрабатывать POST запрос с параметрами из раздела API.
2. После обработки жалобы от пользователя FirstPay отправляет POST запрос на переданный URL при создании жалобы.
3. Мерчант валидирует запросы и обрабатывает переданную информацию. В теле запроса приходит информация об обновлённых жалобах пользователя.
4. FirstPay ожидает ответ с кодом 200 на запрос (тело ответа может быть пустым). Только в этом случае FirstPay будет считать, что информация получена мерчантом. Если код ответа будет отличен от 200, то FirstPay будет с некоторой периодичностью пытаться отправлять запрос до тех пор, пока не получит код 200.
5. В некоторых случаях спустя какое-то время статус жалобы может измениться повторно: с COMPLETED на DECLINED или наоборот. Как следствие, будет отправлен повторный POST запрос с уже обновлённым статусом. Механизм работы с таким запросом аналогичен пунктам 2-4.

API жалоб

FirstPay отправляет POST запрос на postback_url, который передали при создании жалобы.

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

{
   "publicKey": "string",
   "hash": "string",

   "id": "string",

   "merchantId": "string",

   "paymentMethodId": "string" || null,
   "currency": "string" || null,

   "merchantPaymentId": "string",
   "merchantUserId": "string" || null,

   "paymentId": "string" || null,

   "status": "string",

   "comment": "string" || null,

   "amount": "number" || null,

   "createdAt": "string",
   "updatedAt": "string"
}

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

Поле						Тип	Обязательный	Описание
publicKey						String	Да	Публичный ключ FirstPay, который необходим для валидации тела запроса.
hash						String	Да	Закодированная строка тела запроса. О том как ее валидировать - см. в разделе "Авторизация".
id						String	Да	ID жалобы в системе FirstPay.
merchantId						String	Да	ID мерчанта в системе Firstpay.
paymentMethodId						String	Нет	Опциональное поле. ID платежного метода.
currency						Enum	Нет	Опциональное поле. ISO код валюты: USD, INR, BDT, PKR и тд.
merchantPaymentId						String	Нет	Опциональное поле. ID платежа в системе мерчанта. Передается, если было указано при создании платежа.
merchantUserId						String	Нет	Опциональное поле. ID пользователя в системе мерчанта. Передается, если было указано при создании платежа.
paymentId						String	Нет	Опциональное поле. ID платежа в системе FirstPay.
status						Enum	Да	Статус жалобы в системе FirstPay. В ответе всегда будет приходить либо COMPLETED, либо DECLINED.
comment						Strung	Нет	Опциональное поле. Дополнительный комментарий.
amount						Number	Нет	Опциональное поле. Сумма платежа.
createdAt						String	Да	UTC Timestamp создания жалобы.
updatedAt						String	Да	UTC Timestamp обновления жалобы.