Sending complaint

A complaint creation request is sent in case of technical issues or other problems related to payments.

Swagger - detailed complaint API.

Mechanism of operation

An unexpected issue occurs.
The merchant sends a request to create a complaint.

API

To submit a complaint: send a POST request to https://{firstpay_url}/api/complaints/v1/init.

Complaint Creation Request Body Interface

{
   "publicKey": "string",
   "hash": "string",
   "merchantPaymentId": "string",
   "merchantUserId": "string" || null,
   "paymentMethodId": "string" || null,
   "attachmentId": "string" || null,
   "paymentId": "string" || null,
   "amount": "number" || null,
   "clientFieldsValues": [
     {
       "key": "string",
       "value": "string"
     }
   ] | null,
   "comment": "string" || null,
   "postBackUrl": "string" || null
}

Table Describing All Fields in the Request Body

Field		Type	Required	Description
publicKey		String	Yes	The public key issued during merchant registration on the FirstPay platform (the key is provided in a file; the entire contents of the file must be included).
hash		String	Yes	Encoded string of the request body. For instructions on how to generate it, see the "Authorization" section.
merchantPaymentId		String	No	Optional field. You can specify the payment Id from your own system.
merchantUserId		String	No	Optional field. You can specify the user Id from your own system.
paymentMethodId		String	Yes	Payment method Id.
attachmentId		String	No	If the payment method’s isAttachmentRequired field is set to true, this field becomes mandatory. You must upload an image as proof of payment — see the "Media Upload" section. The response will include an id field, which must be specified when creating the payment.
paymentId		String	No	Optional field. Payment ID in the FirstPay system.
amount		Number	Yes	Payment amount.
clientFieldsValues		Array	Yes	List of fields filled out by the user. All these fields are received within the payment method.
	key	String	Yes	Field identifier/Id.
	value	String	Yes	Value entered by the user.
comment		Strung	No	Optional field. Additional comment.
postBackUrl		Strung	No	Optional field. When postBackUrl is specified, FirstPay will send a request to the provided URL after the payment is confirmed. If this parameter is not provided, the request will be sent to the URL registered on the merchant's page.

Table of Returned Responses:

code	Response body	Description
200	Response body	If the request is successful, the response will contain data about the created complaint.
400	`{"error": "some text here..."}`	An error occurs if the request body and query parameters could not be parsed (most likely due to incorrect formatting).
401	`{"error": "NO_LOGIN"}`	An error occurs if the `publicKey` field is not included in the request body.
401	`{"error": "NO_TOKEN"}`	An error occurs if the `hash` field is not included in the request body.
401	`{"error": "NO_KEY"}`	An error occurs if an incorrect `publicKey` is provided.
401	`{"error": "UNAUTHORIZED"}`	An error occurs if there is a validation failure for `publicKey` and `hash`.
403	`{"error": "ACCESS_DENIED"}`	An error occurs if the merchant specifies a payment method in the request to which they do not have access.
404	`{"error": "NOT_FOUND"}`	An error occurs when requesting a payment method by id if that method does not exist in the system.
500	`{"error": "some text here..."}`	An error occurs when the server fails to process the request due to an unexpected situation.

Complaint Creation Response Body Interface:

{
   "id": "string",
   "merchantId": "string",
   "merchantPaymentId": "string",
   "merchantUserId": "string" || null,
   "paymentMethodId": "string" || null,
   "currencyCode": "string" || null,
   "paymentId": "string" || null,
   "status": "string",
   "amount": "number" || null,
   "comment": "number" || null,
   "createdAt": "string",
   "updatedAt": "string"
}

Table Describing All Fields:

Field	Type	Description
id	String	Complaint ID in the FirstPay system.
merchantId	String	Merchant ID in the FirstPay system.
merchantPaymentId	String	Payment ID in the merchant system.
merchantUserId	String	Optional field. User ID in the merchant system.
paymentMethodId	String	Optional field. Payment method ID.
currencyCode	String	Optional field. Currency code.
paymentId	String	Optional field. Payment ID in the FirstPay system.
status	String	Complaint status in the FirstPay system.
amount	Number	Optional field. Payment amount.
comment	String	Optional field. Additional comment.
createdAt	String	Date and time the complaint was created.
updatedAt	String	Date and time the complaint was changed.

Mechanism of operation​

API​

Complaint Creation Request Body Interface​

Table Describing All Fields in the Request Body​

Table of Returned Responses:​

Complaint Creation Response Body Interface:​

Table Describing All Fields:​