Response Handling

Interpret API responses, check uncertain payment results, and choose when a request can be retried safely.

Overview

An HTTP response tells you whether SumUp accepted or completed an API request. It does not always tell you whether the customer paid. Use the resource’s payment status to make that decision.

Each operation’s API reference documents its response codes and body. See API errors for Problem Details and other error formats.

Successful Requests

HTTP response What it means What to do next
200 OK The request succeeded. Read the response and check the resource’s status.
201 Created A resource was created. Save its ID. A newly created checkout still needs to be paid.
202 Accepted Processing was accepted and may still be running. Wait for the final result or retrieve the resource.
204 No Content The operation succeeded and has no response body. Do not try to parse a JSON body. Follow the operation’s documented behavior.

A checkout response can include next_step, meaning the customer needs to complete another action. Let your checkout integration handle that action, including any 3D Secure challenge.

For an online checkout, only treat status: "PAID" as confirmation of payment. A redirect, a widget callback, or an HTTP success code alone is not enough.

Client-Side Issues

Read the error body before deciding whether to retry:

Response Next action
400 or 422 Correct the request using the returned validation details. Repeating the same payload will not fix it.
401 Check the credential. If an OAuth token expired, refresh it or ask the merchant to authorize again.
403 Check merchant access, permissions, and any required scope activation.
409 Inspect the conflicting resource or reference before creating another request.
429 Wait before retrying. If the response includes Retry-After, follow it. Limit the number of attempts.

For example, this response identifies a missing merchant code:

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

Server-Side Issues

A timeout, lost connection, or 5xx response can leave a payment result uncertain. The server might have processed the operation even though your application did not receive its result.

Choose the next action based on the operation:

Operation How to recover
Retrieve a checkout or transaction Retry the read with a delay and a fixed attempt limit. Increase the delay between attempts.
Create or process a payment Retrieve the existing checkout or transaction before submitting another payment.
Refund a transaction Inspect the transaction and its refund events before sending another refund request.

Do not apply one automatic retry policy to every API call.

Check an uncertain payment

  1. Keep the resource IDs and your own payment-attempt reference with the order before processing payment.
  2. If an online checkout ID is known, retrieve the checkout. If checkout creation timed out before returning an ID, list checkouts with the original checkout_reference to look for the existing resource.
  3. For an in-person payment, retrieve the transaction using the identifier supplied by your integration. Depending on the flow, this can be foreign_transaction_id or client_transaction_id.
  4. If payment succeeded, update the existing order. If it is still pending or the final result is unavailable, keep the order unpaid while you reconcile it.
  5. Start another payment attempt only after checking the previous attempt’s result. Give each new attempt a unique reference and keep the link to the same order.

For Cloud API, the initial response only confirms that the reader checkout was accepted. Follow the Cloud API result flow for its final result.

Check an uncertain refund

Retrieve the transaction and inspect its refund events or refunded amount where available. Compare them with the refund your application requested. Use the refund guide and the endpoint’s documented response before deciding whether another refund is needed.

If you still cannot establish the result, retain the IDs and references for reconciliation and contact SumUp(Opens in a new tab). Do not automatically repeat the payment or refund while its result is unknown.

Type to search…