List checkouts

GET/v0.1/checkouts

Lists created checkout resources according to the applied checkout_reference.

OAuth scopes: Requires one of: payments, checkouts.read.

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes paymentscheckouts.read

Authorization guide

Query parameters

checkout_referencestring
Filters checkouts by the merchant-defined checkout_reference supplied when creating the checkout. This is separate from the SumUp-generated checkout id.

Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"

Responses

200application/json

Returns a list of checkout resources.

checkout_referencestring
maxLength: 64
Merchant-defined reference for the checkout. Use it to correlate the SumUp checkout with your own order, cart, subscription, or payment attempt in your systems.

Example: "f00a8f74-b05d-4605-bd73-2a901bae5802"
amountnumber
format: float
Amount to be charged to the payer, expressed in major units.

Example: 10.1
currencystring
Options:"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"
Three-letter ISO 4217 currency code of the amount.

Example: "EUR"
merchant_codestring
Short unique identifier for the merchant that receives the payment.

Example: "MH4H92C7"
descriptionstring
Short merchant-defined description shown in SumUp tools and reporting. Use it to make the checkout easier to recognize in dashboards, support workflows, and reconciliation.

Example: "Purchase"
return_urlstring
format: uri
Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with event_type and the checkout id. Retrieve the checkout to verify its current status before updating your order. See the webhook guide for the payload and response requirements.

Example: "http://example.com"
idstring
Unique SumUp identifier of the checkout resource.

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
statusstring
Options:"PENDING""FAILED""PAID""EXPIRED"
Current high-level state of the checkout. PENDING means the checkout exists but is not yet completed, PAID means a payment succeeded, FAILED means the latest processing attempt failed, and EXPIRED means the checkout can no longer be processed.

Example: "PENDING"
datestring
format: date-time
The timestamp of when the checkout was created.

Example: "2020-02-29T10:56:56+00:00"
valid_untilstringnullable
format: date-time
Optional expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. If omitted, the checkout does not have an explicit expiry time.

Example: "2030-12-31T23:59:59Z"
customer_idstring
Merchant-scoped identifier of the customer associated with the checkout. Use it when storing payment instruments or reusing saved customer context for recurring and returning-payer flows.

Example: "831ff8d4cd5958ab5670"
mandateobject
Details of the mandate linked to the saved payment instrument.

Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
Show 3 properties
- typestring
  Type of mandate stored for the checkout or payment instrument.
  
  Example: "recurrent"
- statusstring
  Options:"active""inactive"
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Short unique identifier for the merchant for which the mandate is valid.
  
  Example: "MH4H92C7"
hosted_checkout_urlstring
format: uri
URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout.

Example: "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676"
transactionsarray<unknown>
Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.

Example: [{"id":"410fc44a-5956-44e1-b5cc-19c6f8d727a4","transaction_code":"TEENSK4W2K","amount":10.1,"currency":"EUR","timestamp":"2020-02-29T10:56:56.876Z","status":"SUCCESSFUL","payment_type":"ECOM","installments_count":1,"merchant_code":"MH4H92C7","vat_amount":6,"tip_amount":3,"entry_mode":"CUSTOMER_ENTRY","auth_code":"012345"}]
Show 13 properties
- idstring
  Unique identifier of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  SumUp transaction code, for example TEENSK4W2K. Use it to look up the transaction with the transaction_code query parameter. This is separate from the transaction's id and the card issuer's auth_code.
  
  Example: "TEENSK4W2K"
- amountnumber
  format: float
  Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10.
  
  Example: 10.1
- currencystring
  Options:"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"
  Three-letter ISO 4217 currency code of the amount.
  
  Example: "EUR"
- timestampstring
  format: date-time
  The timestamp of when the transaction was created.
  
  Example: "2020-02-29T10:56:56.876Z"
- statusstring
  Options:"SUCCESSFUL""CANCELLED""FAILED""PENDING""REFUNDED"
  Current status of the transaction.
  
  PENDING: The transaction has been created but its final outcome is not known yet.
  
  SUCCESSFUL: The transaction completed successfully.
  
  CANCELLED: The transaction was cancelled or otherwise reversed before completion.
  
  FAILED: The transaction attempt did not complete successfully.
  
  REFUNDED: The transaction was refunded in full or in part.
  
  Example: "SUCCESSFUL"
- payment_typestring
  Options:"CASH""POS""ECOM""RECURRING""BITCOIN""BALANCE""MOTO""BOLETO""DIRECT_DEBIT""APM""UNKNOWN"
  Payment category recorded on a transaction, for example POS for a point-of-sale card payment, ECOM for an online card payment, or RECURRING for a recurring card payment. These reporting values are separate from the lowercase payment_type values used to process checkouts.
  
  Example: "ECOM"
- installments_countinteger
  minimum: 1
  Number of installments for a deferred payment.
  
  Example: 1
- merchant_codestring
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- vat_amountnumber
  format: float
  VAT included in the total transaction amount, in major units of the transaction's currency.
  
  Example: 6
- tip_amountnumber
  format: float
  Tip included in the total transaction amount, in major units of the transaction's currency.
  
  Example: 3
- entry_modestring
  Options:"BOLETO""SOFORT""IDEAL""BANCONTACT""EPS""MYBANK""SATISPAY""BLIK""P24""GIROPAY""PIX""QR_CODE_PIX""APPLE_PAY""GOOGLE_PAY""PAYPAL""TWINT""NONE""CHIP""MANUAL_ENTRY""CUSTOMER_ENTRY""MAGSTRIPE_FALLBACK""MAGSTRIPE""DIRECT_DEBIT""CONTACTLESS""MOTO""CONTACTLESS_MAGSTRIPE""N/A"
  How the payment details were captured, for example CHIP or CONTACTLESS for card-present payments and CUSTOMER_ENTRY for card details entered by the payer. For wallet and alternative payment methods, this can identify the method, such as APPLE_PAY or BLIK.
  
  Example: "CUSTOMER_ENTRY"
- auth_codestring
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
transaction_codestring
Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_idstring
Unique identifier of the successful transaction that completed payment for the checkout.

Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
merchant_namestring
Name of the merchant.

Example: "Sample Merchant"
redirect_urlstring
URL where the payer is redirected after a redirect-based payment or SCA flow completes.

Example: "https://mysite.com/completed_purchase"
payment_instrumentobject
Details of the saved payment instrument created or reused during checkout processing.
Show 1 property
- tokenstring
  Unique token of the saved payment instrument.
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"

401application/json

The request is not authorized.

typestringrequired
format: uri
A URI reference that identifies the problem type.

Example: "https://developer.sumup.com/problem/not-found"
titlestring
A short, human-readable summary of the problem type.

Example: "Requested resource couldn't be found."
statusinteger
The HTTP status code generated by the origin server for this occurrence of the problem.

Example: 404
detailstring
A human-readable explanation specific to this occurrence of the problem.

Example: "The requested resource doesn't exist or does not belong to you."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

GET

Code sample

curl --request GET \
  --url https://api.sumup.com/v0.1/checkouts \
  --header 'Authorization: Bearer <token>'

import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

  const result = await client.checkouts.list(
    {
      "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802"
    }
  );
  console.log(result);
}

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Checkouts.ListAsync(
            new CheckoutsListOptions
            {
                CheckoutReference = "example",
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

public final class ListCheckoutsSample {
  public static void main(String[] args) throws Exception {
    var client = new SumUpClient();

    var result = client.checkouts().list();
    System.out.println(result);
  }
}

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$sumup = new \SumUp\SumUp('sup_sk_your_api_key');

$queryParams = new \SumUp\Services\CheckoutsListParams();
$queryParams->checkoutReference = 'f00a8f74-b05d-4605-bd73-2a901bae5802';

$result = $sumup->checkouts()->list(
    $queryParams,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

	"github.com/sumup/sumup-go"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Checkouts.List(context.TODO(), sumup.CheckoutsListParams{
		CheckoutReference: new("f00a8f74-b05d-4605-bd73-2a901bae5802"),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let response = client
        .checkouts()
        .list(sumup::resources::checkouts::ListParams::builder().build())
        .await
        .expect("list request failed");
    println!("{response:#?}");
}

Response example

[
  {
    "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
    "amount": 10.1,
    "currency": "EUR",
    "merchant_code": "MH4H92C7",
    "description": "Purchase",
    "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
    "status": "PENDING",
    "date": "2020-02-29T10:56:56+00:00"
  }
]

{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}