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
- Keep the resource IDs and your own payment-attempt reference with the order before processing payment.
- 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_referenceto look for the existing resource. - For an in-person payment, retrieve the transaction using the identifier supplied by your integration. Depending on the flow, this can be
foreign_transaction_idorclient_transaction_id. - 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.
- 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.