Responses

This page describes the structure of responses returned by the CURO Payments RESTful API, including the default response format, error responses, and a list of error codes.

📘
Note
The HTTP response code of a RESTful API request will contain the processing status of your request. Make sure you check for the correct value (200) or error (4XX).

Default Response

Every response contains the root elements described below.

Element	Type Length	Description
`success`	boolean 1	`true` or `false` indicating the result of the call
`code` (optional)	string ≤ 48	Error code. See List of Error Codes
`message` (optional)	string ≤ 255	Textual message indicating what went wrong in case the call was unsuccessful

Example — Response for a correct JSON payment request

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "payment": {
    "action": "redirect",
    "external": true,
    "url": "redirect_url",
    "testmode": 0,
    "transaction_id": "T26123456789"
  }
}

Default Error Responses

When there is an error, the header information contains an appropriate HTTP 400 ERROR status code (4XX). The body of the response also contains information about the error; details depend on the operation and payment module.

The table below shows the basic structure of response elements common to all REST error responses.

Element	Type Length	Description
`[container]`	container	General container for this resource (eg. payment, recurring, refund etc.).
`[error]`	container	Response container for all error elements.
`code`	string ≤ 48	The error code is a string that uniquely identifies an error condition. It is meant to be read and understood by programs that detect and handle errors by type. For more information, see List of Error Codes.
`message`	string ≤ 255	The error message contains a generic description of the error condition in English. It is intended for a human audience. Simple programs display the message directly to the end user if they encounter an error condition they don't know how or don't care to handle. Sophisticated programs with more exhaustive error handling and proper internationalization are more likely to ignore the error message.
`success`	boolean 1	`TRUE` or `FALSE` indicating the result of the call
`warning` (optional)	string ≤ 255	English message depending on context, mostly about optional/missing data.

Example — Response for an error JSON payment request

HTTP/1.1 400 ERROR
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "Payment.Type.Invalid",
    "message": "invalid payment type"
  }
}

List of Error Codes

General transaction errors

Error Code	Description	HTTP Status Code
`Access.Denied`	Access Denied for a certain resource.	403
`Transaction.Generic.Error`	Generic transaction error.	400
`Transaction.Database.Error`	Database error while processing the transaction.	400
`Transaction.Prepare.Failure`	Information was invalid to prepare the transaction.	400
`Transaction.Register.Failure`	Unable to register the transaction at the acquirer.	400
`Transaction.Process.Failure`	Failure while processing the transaction.	400
`Transaction.Cancel.Failure`	The transaction could not be cancelled.	400
`Transaction.Abuse`	Abuse module was triggered for this transaction.	400
`Transaction.Invalid`	Invalid information was provided.	400
`Transaction.Invalid.State`	The transaction was in an unexpected state.	400
`Transaction.Missing`	Required arguments are missing.	400
`Transaction.Internal.Error`	Internal error while processing.	400
`Transaction.3rdParty.Error`	Third party error.	400
`Transaction.Acquirer.Error`	Acquirer error while processing.	400
`Transaction.NotSupported`	The requested action was not supported.	400
`Transaction.Cart.Invalid`	Given cart was invalid.	400

Recurring errors

Error Code	Description	HTTP Status Code
`Transaction.Error.NoMaster`	Master transaction was not found.	400
`Transaction.Error.NoRecur`	Recurring is not allowed or possible.	400

Refund errors

Error Code	Description	HTTP Status Code
`Transaction.Error.RefundTooHigh`	Refund was higher that the available amount.	400
`Transaction.Error.Refund.Negative`	Refund amount can not be negative.	400
`Transaction.Error.Refund.Unavailable`	Refund is not supported for this transaction.	400
`Transaction.Error.Refund.Complete`	Transaction was already refunded completely.	400

Subscription errors

Error Code	Description	HTTP Status Code
`Transaction.Error.Subscription.Unavailable`	Subscription option is not available.	400
`Transaction.Error.Subscription.Not.Active`	Subscription is not active.	400
`Transaction.Subscription.Cancel.Failure`	Cancel of subscription failed.	400