Payment status

Swagger - detailed payment API.

Payment Status Check Request Body Interface:

{
   "publicKey": "string",
   "hash": "string",
   "paymentId": "string", // optional
   "merchantPaymentId": "string" // optional
}

Table Describing All Fields in the Request Body:

Field						Type	Required	Description
publicKey						String	Yes	Public key issued during merchant registration on the FirstPay platform (the key is provided as a file; the entire contents must be included).
hash						String	Yes	Encoded request body string. For instructions on how to generate it, see the "Authorization" section.
paymentId						String	As appropriate	Payment ID in the FirstPay system. The request must include either paymentId or merchantPaymentId. If both fields are provided, the server first checks for the payment by paymentId, then by merchantPaymentId.
merchantPaymentId						String	As appropriate	Payment ID in the merchant’s system, as specified in the merchantPaymentId field during payment creation.

Table of returned responses:

code	Response body	Description
200	Payment	Upon a successful request, payment data is returned.
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 missing in the request body.
401	{"error": "NO_TOKEN"}	An error occurs if the hash field is missing in the request body.
401	{"error": "NO_KEY"}	An error occurs if an invalid publicKey is provided.
401	{"error": "UNAUTHORIZED"}	An error occurs if there is a validation error with the publicKey and hash.
404	{"error": "NOT_FOUND"}	An error occurs if the specified payment 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 or non-standard situation.

Payment Fields Description

Payment Interface:

{
    "id": "string",
    "currencyCode": "string",
    "paymentMethodId": "string",
    "status": "string",
    "amount": 0,
    "clientFieldsValues": [{
        "key": "string",
        "value": "string"
    }],
    "merchantPaymentId": "string", // optional
    "merchantUserId": "string", // optional
    "failedCode": "string", // optional
    "attachment": {
        "id": "string",
        "url": "string"
    }, // optional
    "postBackUrl": "string", // optional
    "createdAt": "string"
}

Table Describing All Fields:

Field						Type	Description
id						String	Payment ID.
currencyCode						Enum	ISO currency code: USD, INR, BDT, PKR, etc.
paymentMethodId						String	Payment method ID.
status						Enum	Payment status: SUCCESS, PENDING, FAILED, NEED_CHECK.
amount						Number	Amount in the specified currency.
clientFieldsValues						Array	Array of client data fields. Created based on the payment method’s clientFields. Each field contains its own key and value.
	key					String	Field identifier/id as specified in the payment method’s clientFields.
	value					String	Field value that passes validation according to the payment method’s clientFields.
merchantPaymentId						String	Optional field. Matches the specified merchantPaymentId provided during payment creation.
merchantUserId						String	Optional field. Matches the specified merchantUserId provided during payment creation.
failedCode						Enum	Optional field. Reason for payment failure: INCORRECT_AMOUNT, NO_AMOUNT, INCORRECT_FIELDS, RECIPIENT_LIMIT, ANOTHER_REASON.
attachment						Object	Optional field. Contains information about the payment confirmation image if it was uploaded.
	id					String	Media ID.
	url					String	Image URL.
createdAt						string	Payment creation date.