Checkouts | SumUp Developer

Checkouts represent online payment sessions that you create before attempting to charge a payer. A checkout captures the payment intent, such as the amount, currency, merchant, and optional customer or redirect settings, and then moves through its lifecycle as you process it.

Use this tag to:

create a checkout before collecting or confirming payment details
process the checkout with a card, saved card, wallet, or supported alternative payment method
retrieve or list checkouts to inspect their current state and associated payment attempts
deactivate a checkout that should no longer be used

Typical workflow:

create a checkout with the order amount, currency, and merchant information
process the checkout through SumUp client tools such as the Payment Widget and Swift Checkout SDK
retrieve the checkout or use the Transactions endpoints to inspect the resulting payment record

Checkouts are used to initiate and orchestrate online payments. Transactions remain the authoritative record of the resulting payment outcome.

Objects:

Checkout

Get available payment methodsGET/v0.1/merchants/{merchant_code}/payment-methods
Lists the payment methods available to the merchant for checkout payments. Use the optional amount and currency filters to check eligibility for a particular payment before presenting payment options to the payer.
List checkoutsGET/v0.1/checkouts
Lists created checkout resources according to the applied checkout_reference.

OAuth scopes: Requires one of: payments, checkouts.read.
Create a checkoutPOST/v0.1/checkouts
Creates a payment checkout for the specified merchant, amount, and currency. Supply a checkout_reference to identify the payment attempt in your own systems. Creating a checkout does not charge a payment instrument.

Set hosted_checkout.enabled to true to receive a Hosted Checkout URL where the customer can complete the payment. Use redirect_url for redirect-based payment and 3DS flows. If return_url is provided, SumUp sends processing updates to that backend callback URL.

Complete the payment through Hosted Checkout or the Payment Widget.

OAuth scopes: Requires one of: payments, checkouts.write.
Retrieve a checkoutGET/v0.1/checkouts/{checkout_id}
Retrieves a checkout by its SumUp checkout_id. After processing a payment, returning from a redirect, or receiving a checkout notification, retrieve the checkout to confirm its current status before updating your order or displaying the payment outcome to the payer.

OAuth scopes: Requires one of: payments, checkouts.read.
Process a checkoutPUT/v0.1/checkouts/{checkout_id}

PCI DSS compliance required

When you submit raw card details directly to the Checkout API, your systems store, process, or transmit cardholder data and are therefore subject to applicable PCI DSS requirements. You should only use this integration if your environment is appropriately PCI DSS compliant.

Processing a checkout will attempt to charge the provided payment instrument for the amount of the specified checkout resource initiated in the Create a checkout endpoint.

A processing response can require an additional payer action, such as a 3DS challenge or a payment-provider redirect. If next_step is returned, follow its instructions to continue the payment flow.

Retrieve the checkout afterwards to confirm its payment status. Acceptance of the processing request does not by itself mean the checkout is paid.

OAuth scopes: Requires one of: payments, checkouts.write.
Deactivate a checkoutDELETE/v0.1/checkouts/{checkout_id}
Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.

OAuth scopes: Requires one of: payments, checkouts.write.
Update a checkoutPATCH/v0.1/checkouts/{checkout_id}
Updates the amount, currency, description, reference, expiration, or customer associated with an existing checkout. Only the supplied fields are updated.

This request changes the checkout details; it does not charge a payment instrument. Process the checkout separately to attempt a payment.

OAuth scopes: Requires one of: payments, checkouts.write.
Create an Apple Pay sessionPUT/v0.2/checkouts/{checkout_id}/apple-pay-session
Creates an Apple Pay merchant session for the specified checkout.

Use this endpoint after the customer selects Apple Pay and before calling ApplePaySession.completeMerchantValidation(...) in the browser. SumUp validates the merchant session request and returns the Apple Pay session object that your frontend should pass to Apple's JavaScript API.