Handling Status & Codes
Sample API Response
Below is a sample API response format which will be obtained from an executed API request. This example serves to showcase the structure and content of the responses received from the API calls.
A. API Status & Codes
Part 1: HTTP Codes
Here is a list of most common API hits HTTP codes.
500: This error will only come in case any of the internal service is down. Some examlples are newtork issue, server crashes, etc.
401: In case of signature mismatch or invalid credentials.
200: For all other queries. Any business logic or validation error can have a response as "200 OK" but the data will have "status = FAILURE". Details of this behaviour is explained on this page in Part 3: API Response Code.
These are specific to our logic. While all other HTTP error codes are still valid.
x-response-signature and udfParameters will be only present in responses where HTTP response code is 200.
Part 2: API Status
Every valid API response will have a valid json as a response body. The response json should contain a key called "status". The value of this key can be "SUCCESS" or "FAILURE". Merchants should first look at this key and decide whether querying was a success or not.
If status is "SUCCESS", there will be another key as "payload" which will be the output for the API being consumed.
Where PSP interact with third-party systems like NPCI or CBS, the response will include three additional parameters: "gatewayResponseStatus" to indicate the status returned by the third party, "gatewayResponseCode" for the specific error code from the third party, and "gatewayResponseMessage" providing a human-readable error message associated with that error code. (Read more in part 4)In case status is "FAILURE", check the keys called "responseCode" and "responseMessage" which will give details around the reason for querying failure. (Read more in part 3)
Part 3: API Response Code
Here is a list of common API responseCode and their meanings when "status" is "FAILURE"
Common responseCode
|
responseCode
|
HTTP Code
|
Meaning
|
|---|---|---|
INTERNAL_SERVER_ERROR
| 500
| This error will be returned in case something went wrong with internal PSP components. For example, the database server went down. Ideally this error should never come.
|
UNAUTHORIZED
| 401
| This error will come in case the validation of merchant signature fails at PSP.
|
INVALID_MERCHANT
| 401
| Invalid merchant id or merchant channel id
|
BAD_REQUEST
| 200
| This error will be returned in case a mandatory parameter is missing from the request or some regex mismatch happens.
|
INVALID_DATA
| 200
| In case all madantory keys are passed, but they contain an incorrect value.
|
SERVICE_UNAVAILABLE
| 200
| This error will be returned in case the third party servers are not reachable from PSP. Like NPCI or any other Bank system etc. Error will be the HTTP error returned by the third party servers like 406, timeout, reset, etc.
|
GATEWAY_TIMEOUT
| 200
| Timed out from NPCI
|
DEVICE_FINGERPRINT_MISMATCH
| 200
| This error will come in case the customer device fingerprint is not valid.
|
DUPLICATE_REQUEST
| 200
| Same merchantRequestId or upiRequestId used for multiple requests. Usually given for Idempotent API.
|
In case of BAD_REQUEST and INVALID_DATA errors, the responseMessage field will have more details on the error.
Transaction Status responseCode
|
responseCode
|
HTTP Code
|
Meaning
|
|---|---|---|
REQUEST_NOT_FOUND
| 200
| This error will be given in case transaction was not created using any such merchantRequestId or upiRequestId
|
REQUEST_EXPIRED
| 200
| This error will be returned for user dropout based on sent expiry time during Register Intent.
|
DROPOUT
| 200
| Only given for UPI Plugin flow based on InApp SDK response [errorCode-errorMessage]
|
REQUEST_PENDING
| 200
| Indicates that the transaction is still in progress. Applicable when the UPI flow hasn't reached a terminal state yet.
|
Refund responseCode
|
responseCode
|
HTTP Code
|
Meaning
|
|---|---|---|
INVALID_TRANSACTION_ID
| 200
| Transaction id on which refund is initiated is not valid
|
UNINITIATED_REQUEST
| 200
| Transaction on which refund is initiated was not successful
|
INVALID_REFUND_AMOUNT
| 200
| Sum of all the refunds initiated on the transaction exceed the amount of the transaction
|
DUPLICATE_REQUEST
| 200
| Same merchantRequestId used for multiple requests.
|
B. Transaction Status & Codes
Part 4: Transaction - Gateway Response Code & Status
A transaction can have 6 different status as given in 2nd column of below table. PSP will be giving gatewayResponseCode & gatewayResponseStatus in payload of API response / callbacks / status check. Exact description & nature of decline can be referred from the NPCI Error & Response Codes doc
.
|
gatewayResponseCode
|
gatewayResponseStatus
|
Descriptions
|
|---|---|---|
00
| SUCCESS
| Depending upon specific API, successful message will be given.
|
01
| PENDING
| Depending upon specific API, pending message will be given.
|
RB
| DEEMED
| Benificiar bank system is unable to respond at present
|
ZA
| DECLINED
| Transaction declined
|
U69
| EXPIRED
| Your collect request has expired
|
Else
| FAILURE
| Depending upon specific API, failure message will be given.
|
ZH
| FAILURE
| Beneficiary payment address incorrect
|
X1
| FAILURE
| Transaction is declined because merchant intent was expired.
|
YG
| FAILURE
| Validation error (Amount mismatch / Direct Pay / tr or tid change)
|
Part 5: Mandates - Gateway Response Code & Status
A mandate can have multiple different status as given in 2nd column of below table. PSP will be giving gatewayResponseCode & gatewayResponseStatus in payload of API response / callbacks / status check. Exact description & nature of decline can be referred from the NPCI Error & Response Codes doc.
|
gatewayResponseCode
|
gatewayResponseStatus
|
Description
|
|---|---|---|
00
| SUCCESS
| Mandate is in active state
|
01
| PENDING
| Mandate is in pending state
|
JPMR
| REVOKED
| Mandate is revoked
|
JPMP
| PAUSED
| Mandate is paused
|
JPMC
| COMPLETED
| Mandate is completed
|
JPMD
| DECLINED
| Mandate is declined by payer
|
JPMX
| EXPIRED
| Mandate is expired due to no action by payer
|
Else
| FAILURE
| Any other reason.
|
Part 6: Monitoring setup
Merchants can setup monitoring of API & Transaction responses at their end. HTTP response codes, API Status, API Response Status, Gateway Response Status, Gateway Response Code can be monitored as described above.