📤 Process Response

🔍 Understanding Payment Response

📤

Response Processing

The response returned from the Payment Gateway contains encrypted data in a field called data. This data is encrypted using the same AES encryption with your IV & Secret Keys and must be decrypted using the HesabeCrypt library's decrypt function.

📄 Sample Response Structure

Here's an example of a successful payment response after decryption:

{
    "status": true,
    "code": 1,
    "message": "Transaction Success",
    "response": {
        "data": {
            "resultCode": "CAPTURED",
            "amount": 10,
            "paymentToken": "1569830677725743478",
            "paymentId": "100201927384634224",
            "paidOn": "2019-09-30 11:05:16",
            "orderReferenceNumber": null,
            "variable1": null,
            "variable2": null,
            "variable3": null,
            "variable4": null,
            "variable5": null,
            "method": 1,
            "administrativeCharge": "5"
        }
    }
}

📊 Response Parameters Reference

🏷️ Field	📋 Type	📝 Description
status	Boolean	Payment status (true for success; false for failure)
resultCode	String	Success transactions have values "CAPTURED", "ACCEPT", or "SUCCESS"
amount	Numeric	Amount must be greater than zero
paymentToken	Numeric	14-digit Payment Token returned from Hesabe
paymentId	Alphanumeric	Payment Id returned from Hesabe
paidOn	Alphanumeric	Date and Time of Payment
orderReferenceNumber	Alphanumeric	Custom user parameter passed in the request
variable1-5	Alphanumeric	Custom user parameters included in the response
method	Numeric	1 or 2 (1 for KNET; 2 for MPGS)
administrativeCharge	Numeric	Administrative Charge

🌐 Common REST API Status Codes

These widely used HTTP status codes are relevant to REST API operations and represent standard responses from the server regarding the outcome of HTTP requests.

🔢 Status Code	📋 Description
200	OK – The request has succeeded. Used for successful GET or POST responses.
201	Created – The request has succeeded, and a new resource has been created. Common in POST requests that create data.
204	No Content – The server successfully processed the request, but there is no content to send in response.
400	Bad Request – The server could not understand the request due to an invalid syntax. Often used when required fields are missing.
401	Unauthorized – Authentication is required and has failed or has not yet been provided.
403	Forbidden – The server understands the request but refuses to authorize it.
404	Not Found – The requested resource could not be found on the server.
405	Method Not Allowed – The request method is known by the server but has been disabled for the requested resource.
408	Request Timeout – The server timed out waiting for the request.
409	Conflict – The request conflicts with the current state of the resource.
415	Unsupported Media Type – The media format of the requested data is not supported by the server.
429	Too Many Requests – The user has sent too many requests in a given amount of time (rate limiting).
500	Internal Server Error – A generic error message, given when an unexpected condition is encountered.
502	Bad Gateway – The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503	Service Unavailable – The server is not ready to handle the request, often due to maintenance or overload.

⚠️ Custom Application Error Codes

Application-specific error codes used to identify and describe issues related to merchant transactions, authentication, authorization, and payment processing. Each code corresponds to a unique system error or validation failure.

🚨 Error Code	📝 Description
422	The input data provided is either invalid or incomplete.
501	The specified merchant is not recognized or registered.
503	The merchant does not have access to the requested service.
504	Incorrect login credentials provided by the merchant.
505	The payment token is invalid or has expired.
506	The request contains data that is not formatted or structured correctly.
507	A generic error occurred during the transaction process.
508	The transaction amount exceeds the allowed limit.
509	The number of transactions for the day exceeds the permitted limit.
510	The total transaction amount for the day has been exceeded.
511	The number of transactions for the month exceeds the permitted limit.
512	A threshold has been reached, but the transaction can still proceed.
513	The session has expired due to inactivity.
514	The amount captured is less than what was originally authorized.
515	The captured amount exceeds the authorized amount.
516	The captured amount is more than the available authorized balance.
517	The authorization has expired and is no longer valid.
518	Authorization must be enabled before proceeding with this transaction.
519	The currency used in the transaction is not supported or invalid.
520	The transaction was cancelled by the user or system.
521	This transaction has already been captured and cannot be captured again.
522	Terminal ID is missing from the request or is invalid.
523	The account details provided are incorrect or incomplete.
524	The KNET card used is not valid or unsupported.
525	The commission structure provided is invalid or does not match the expected format.