Skip to content
SumUp Developer

Hosted Checkout

About Hosted Checkout

Section titled “About Hosted Checkout”

Hosted Checkout is an integration product that offers a complete checkout flow for payment collection. It’s called “Hosted Checkout”, because SumUp renders and hosts the entire checkout UI, which your customers can access via URL returned by our checkout API. The hosted checkout page aims at being easy to integrate and requires little to no code, offering a summary of the checkout details and provides a complete flow for handling payment collection, covering the possible outcomes of payment attempts all the way to the success page. All SumUp payment methods are available in Hosted Checkout, according to availability per merchant.

A screenshot of the Hosted Checkout form showing available payment options, including Google Pay, Apple Pay, and card payment
A screenshot of the Hosted Checkout form showing available payment options, including Google Pay, Apple Pay, and card payment

Prerequisites

Section titled “Prerequisites”

Hosted Checkouts is available to all SumUp merchants and getting started with it is really easy!

The only requirement to access Hosted Checkout is the ability to create online checkouts using SumUp checkout API, which returns the hosted checkout URL. SumUp API requires authorization with an API Key or Access Token - see the Authorization Guide for details.

Accessing Hosted Checkout

Section titled “Accessing Hosted Checkout”

Once you’re able to create checkouts via API calls, you can opt-in for Hosted Checkout by providing an extra parameter to your POST request payload. The parameter name should be hosted_checkout and the value should be an object with the following structure: { "enabled": true }.

The response should then include the Hosted Checkout properties:

  • hosted_checkout is returned as provided in the request
  • hosted_checkout_url provides the URL of the page handling the payment flow

  1. Send a request with the "hosted_checkout": { "enabled": true } in the body.

    curl -X POST https://api.sumup.com/v0.1/checkouts \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $SUMUP_API_KEY" \
        -d '{
            "amount": 12.00,
            "checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d",
            "currency": "EUR",
            "description": "A sample checkout",
            "merchant_code": "MCXXXXXX",
            "hosted_checkout": { "enabled": true }
        }'

    The response body contains the hosted_checkout and hosted_checkout_url parameters:

    {
        "amount": 12,
        "checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d",
        "checkout_type": "checkout",
        "currency": "EUR",
        "date":"2000-01-01T12:49:24.899+00:00",
        "description": "A sample checkout",
        "id": "64553e20-3f0e-49e4-8af3-fd0eca86ce91",
        "merchant_code": "MCXXXXXX",
        "merchant_country": "DE",
        "merchant_name": "Sample Shop",
        "purpose": "CHECKOUT",
        "status": "PENDING",
        "transactions": [],
        "hosted_checkout": { "enabled": true },
        "hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676"
    }

  2. Use the payment page provided under hosted_checkout_url to complete the flow you’re building. See Configuring Hosted Checkout for more information.

Configuring Hosted Checkout

Section titled “Configuring Hosted Checkout”

Redirecting users after successful payment

Section titled “Redirecting users after successful payment”

Hosted Checkout is meant to suit a broad range of use cases, from a simple self-contained payment solution, to a checkout step integrated within a longer flow. When creating a checkout, simply provide a redirect_url parameter to include a redirect link in the success page, under a “Redirect to merchant website” button.

Hosted Checkout status pages

Section titled “Hosted Checkout status pages”

With Hosted Checkout, your payment flow is covered from start to finish. All successful payments are presented with a success page, informing users of the completed payment. Hosted Checkout also accommodates other payment outcomes:

  • Successful payments. This page will include the “Back to merchant website” button only if the redirect_url was provided at checkout creation.
A screenshot of the Hosted Checkout payment successful confirmation form
A screenshot of the Hosted Checkout payment successful confirmation form
  • Failed payments will include express checkout payment methods for a quick retry.
A screenshot of the Hosted Checkout payment failed form
A screenshot of the Hosted Checkout payment failed form
  • Expired session page will be shown for all unpaid checkouts after session expiration or checkout expiration (currently 30 minutes).
A screenshot of the Hosted Checkout session expiry form
A screenshot of the Hosted Checkout session expiry form
  • Not found page, for all URLs that do not match any existing session in our system
A screenshot of the Hosted Checkout page not found form
A screenshot of the Hosted Checkout page not found form