Handling Postback Requests

Payment and complaint verification is built on a postback request system. FirstPay sends requests to the merchant with information about payments or user complaints.

This is the current postback format you need to use. If you have been using a deprecated format, information about it can be found here.

Swagger - detailed postback API.

Payment Workflow Mechanism

1. In the Merchant Registration section, you specify the URL to receive postback requests from FirstPay.
2. The merchant implements the API according to the contract. The endpoint must handle POST requests with parameters as specified in the API section.
3. After processing the user's payment, FirstPay sends a POST request to the URL provided during payment creation or to the URL specified in the system.
4. The merchant validates incoming requests and processes the transmitted information accordingly. The request body contains information about the payments made by the user.
5. FirstPay expects a response with HTTP status code 200 to the request (the response body can be empty). Only in this case will FirstPay consider that the information has been successfully received by the merchant. If the response code is anything other than 200, FirstPay will periodically retry sending the request until it receives a 200 status code.
6. In some cases, the payment status may change again after some time—for example, from SUCCESS to FAILED or vice versa. As a result, a repeated POST request will be sent with the updated status. The handling mechanism for such requests is the same as described in steps 3–5.

Payment API

FirstPay sends a POST request to the postback_url provided during payment creation. If no postback_url was specified, the request is sent to the URL the merchant registered in the system during onboarding.

Request Body Interface

{
  "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"
}

Table Describing All Fields in the Request Body

Field						Type	Required	Description
publicKey						String	Yes	FirstPay public key required for validating the request body.
hash						String	Yes	Encoded request body string. For validation instructions, see the "Authorization" section.
id						String	Yes	Payment ID in the FirstPay system.
status						Enum	Yes	Payment status in the FirstPay system. The response will always include either SUCCESS or FAILED.
failedCode						Enum	Yes	This field describes the error encountered during the payment. If status = SUCCESS, this field will be null. If status = FAILED, the failedCode will contain one of the following values: INCORRECT_AMOUNT (incorrect amount of funds transferred), NO_AMOUNT (no funds were transferred), INCORRECT_FIELDS (form fields were filled incorrectly), ANOTHER_REASON (another error not related to the above).
paymentMethodId						String	Yes	Payment method ID.
amount						Number	Yes	Payment amount.
currency						Enum	Yes	ISO currency code: USD, INR, BDT, PKR, etc.
clientFieldsValues						Array	Yes	List of fields filled by the user. All these fields are sent by the merchant when creating the payment.
	key					String	Yes	Field identifier/ID.
	value					String	Yes	Value entered by the user.
merchantPaymentId						String	No	Optional field. Payment ID in the merchant’s system. Provided if specified during payment creation.
merchantUserId						String	No	Optional field. User ID in the merchant’s system. Provided if specified during payment creation.
createdAt						String	Yes	UTC timestamp of payment creation.

Complaint Handling Workflow

1. The merchant implements the API according to the contract. The endpoint must handle POST requests with parameters from the API section.
2. After processing a complaint from a user, FirstPay sends a POST request to the URL provided during complaint creation.
3. The merchant validates the incoming requests and processes the provided information. The request body contains information about updated user complaints.
4. FirstPay expects a response with HTTP status code 200 (the response body may be empty). Only then will FirstPay consider the information received by the merchant. If the response code differs from 200, FirstPay will periodically retry sending the request until it receives code 200.
5. In some cases, the complaint status may change again after some time—for example, from COMPLETED to DECLINED or vice versa. Consequently, a repeated POST request will be sent with the updated status. The handling mechanism for such requests is the same as described in steps 2–4.

Complaint API

FirstPay sends a POST request to the postback_url provided during complaint creation.

Request Body Interface

{
   "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"
}

Table Describing All Fields in the Request Body

Field						Type	Required	Description
publicKey						String	Yes	FirstPay public key required for validating the request body.
hash						String	Yes	Encoded request body string. For validation details, see the "Authorization" section.
id						String	Yes	Complaint ID in the FirstPay system.
merchantId						String	Yes	Merchant ID in the FirstPay system.
paymentMethodId						String	No	Optional field. Payment method ID.
currency						Enum	No	Optional field. ISO currency code: USD, INR, BDT, PKR, etc.
merchantPaymentId						String	No	Optional field. Merchant system payment ID. Provided if specified during payment creation.
merchantUserId						String	No	Optional field. User ID in the merchant’s system. Provided if specified during payment creation.
paymentId						String	No	Optional field. Payment ID in the FirstPay system.
status						Enum	Yes	Complaint status in the FirstPay system. The response will always include either COMPLETED or DECLINED.
comment						Strung	No	Optional field. Additional comment.
amount						Number	No	Optional field. Payment amount.
createdAt						String	Yes	UTC timestamp of complaint creation.
updatedAt						String	Yes	UTC timestamp of complaint update.