HTTP response codes
The Checkout API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
200: Request was successful.4xx: This code range indicate an error that failed given the information provided (e.g., a required parameter was omitted).5xxThis code range indicate an error with the API's servers.
HTTP error response format
Requests that result in an error will return an HTTP status code in the 4xx or 5xx range. The body of the response will contain additional information. The JSON response format includes the following fields:
| Field | Type | Description |
|---|---|---|
code | Number | The three digit HTTP status code. |
details | Object | Optional. This field may include additional information about the error and can be used for debugging. |
message | String | A human-readable message providing more information about the error. |
timestamp | Number | The date and time when the error occurred. This field is shown in Unix time. |
HTTP error codes
| Http Error code | OnlinePay Error code | Message | Details/redirection schema |
|---|---|---|---|
| 400 Bad Request | 107 | At least one parameter is invalid. Examine the details property for more information. Invalid parameters are listed and prefixed accordingly: body for parameters submitted in the request's body, query for parameters appended to the request's URL, and params for templated parameters of the request's URL. | The request payload contains one or more parameters with an invalid format. Revise request payload and ensure that you have used the expected format for each field. For example: body.amount: should be a positive integer. |
| 400 Bad Request | 110 | The submitted or requested resource is invalid. If you submitted a resource, please check for invalid fields, which will be listed in the details property. If you requested a resource, ensure the latter is valid, as well as its sub-resources. | Revise the request payload and ensure it's in proper JSON format (check for trailing commas, missing quotes, etc). |
| 400 Bad Request | 126 | At least one parameter is missing from the request body. Revise request payload, API docs and refer to the integration guides for the payment methods to check for any conditionally required fields which might be necessary. | For example: { "missingParameters": ["body.amount"] } |
| 400 Bad Request | 123 | The transaction has been rejected by the processor. The request reached the processor, but it failed the validation checks required by the processor. Please examine your request. If the error persists, contact an administrator. | The payment has failed due to a technical failure in one of the upstream services involved in the payment. Please review additional details, which are stored in checkout.eventsredirects with query and reach out to OnlinePay Support teams for assistance parameter: errorCode=123&checkoutId={checkoutId} |
| 400 Bad Request | 127 | At least one parameter is unexpected, or invalid. If you're trying to update a resource, be sure to include only parameters that you want to, and may, update. Some parameters are read-only or create-only. | For example: { "unexpectedParameters": ["parameterNotPresentInSchema"] } |
| 400 Bad Request | 137 | Parameters in the request body are conflicting with one another. It's likely that they are valid individually, yet they can't be submitted together, as that would lead to invalid combinations. | Please make sure the IDs inserted are correct. For example: { "parameters": ["entityId", "configurations.card.paymentContractId"], "reason": "The entityUid of the PaymentProviderContract(s) does not match the body.entityId" } |
| 400 Bad Request | 166 | The checkout you are trying to use has reached max notification attempts | - |
| 400 Bad Request | 167 | Reached maximum theme creations allowed. Delete existing themes to create a new one | The maximum number of themes that can be created on an organization level is set to 15. To create an additional theme, you will have to delete an existing theme |
| 401 Unauthorized | 116 | Access is restricted to authenticated users only. The query can't be made without a valid JWT (check the Authorization header of your request), or a valid session (in which case session cookies are automatically set by the browser). | For obtaining your authentication credentials, see Get started with the OnlinePay API |
| 403 Forbidden | 111 | The submitted transaction has been blocked by a ruleset specified by the organization owning the account, or by a superior organization. Further information is available by querying the relevant ValidationRuleSetMatch, or by examining the blocked transaction in the user interface. | Redirects with query parameter as: errorCode=111&checkoutId={checkoutId}&transactionId={transactionId} |
| 403 Forbidden | 113 | Insufficient permissions. Your current user roles don't allow you to perform this query. Should you believe this error to be incorrect, please contact an administrator | The roles of the user performing the request are not sufficient for the requested operation. Ensure that the user contains MERCHANT_SUPERVISOR or MERCHANT_CASHIER to be able to to create Checkouts. Ensure that MERCHANT_USER role is present if doing read operations. |
| 403 Forbidden | 121 | The transaction has been declined by the processor. The request reached the processor, but it was not accepted. A decline reason code is available in the details property. | Redirects with query parameter: errorCode=121&checkoutId={checkoutId}. Please review additional details which are stored in checkout.eventsredirects with query and reach out to OnlinePay Support teams for assistance. |
| 403 Forbidden | 141 | The checkout you are trying to use has already reached the maximum number of failed 3D secure processing attempts done through it and is not accessible anymore. | - |
| 403 Forbidden | 165 | The checkout you are trying to use has already reached the maximum number of failed transaction attempts done through it and is not accessible anymore. | A Checkout link can be used three times to initiate a transaction. After the failed third request, a new link should be generated to place a transaction. |
| 403 Forbidden | 168 | The checkout you are trying to use has already been completed. | Payment has already been completed using that specific checkout link In order to place a new transaction a new link must be generated. A payment link can only be used once for payments. |
| 403 Forbidden | 169 | The checkout you are trying to use has expired. | The maximum value for a checkout link expiration time is 30 days |
| 403 Forbidden | 171 | The checkout you are trying to use has been cancelled. | - |
| 404 Not Found | 109 | The requested resource, or one of its sub-resources, can't be found. If the submitted query is valid, this error is likely to be caused by a problem with a nested resource that has been deleted or modified. Check the details property for additional insights. | One or more values in the request does not exist, or cannot be accessed by the user performing the request. Resource can vary, depending on which type of data cannot be found. { "resource": "Checkout", "id": "a6b45428-0296-4394-8ddd-0b50b5b20aa9" } |
| 500 Internal Server | 100 | Unexpected error: if the error persists, please contact an administrator, quoting the code and timestamp of this error | - |
| 500 Internal Server | 140 | An error occurred during 3D Secure processing. For more information, please refer to the details property. | The payment has failed due to a technical failure in one of the upstream services involved in the payment. Please review additional details, which are stored in checkout.eventsredirects with query and reach out to OnlinePay Support teams for assistance. |
| 500 Internal Server | 170 | Timeout of API call. | Please retry the API call. If the second request fails, reach out to OnlinePay Support teams for assistance. |