Response Handling

Once an API call is submitted to SumUp, you will receive a response informing you if your request has been successful or not. In most cases the HTTP codes are accompanied by a response body in JSON format.

Returned codes in the 2xx range indicate success. Returned codes in the 4xx range indicate errors where the information provided results in a failure. Returned codes in the 5xx range are rare and indicate server-side errors.

Successful requests

Successfully processed requests return one of the following HTTP status codes: 200 OK, 201 Created, 202 Accepted, 204 No Content. Depending on the use case response bodies may not be present at all. A response body can look like this:

{
  "next_step": {
    "url": "https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A",
    "method": "POST",
    "redirect_url": "https://mysite.com/completed_purchase",
    "mechanism": "iframe",
    "payload": {
      "PaReq": "eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/..f16+jLt/gPhUvGGw==",
      "MD": "b1a536c0-29b9-11eb-adc1-0242ac120002"
    }
  }
}

Client-side issues

4xx are occasions where you can take action to correct your application requests. Typically, these codes are returned upon user error, such as invalid API calls, incorrect values, missing parameters, etc. The response you receive will provide an indication to the root cause that triggered it. Here's an example of a 4xx response:

{
  "message": "Validation error",
  "error_code": "MISSING",
  "param": "pay_to_email"
}

Server-side issues

5xx stand for server errors. Although rare, if you receive such code, we recommend retrying your request. Should the returned codes continue to be in the 5xx range, reach out to us.