Skip to content
SumUp Developer

Checkouts

SumUp API reference and code samples.

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.

The Checkout object

Core checkout resource returned by the Checkouts API. A checkout is created before payment processing and then updated as payment attempts, redirects, and resulting transactions are attached to it.

  • checkout_reference string max length: 90

    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.

  • amount number

    Amount to be charged to the payer, expressed in major units.

    Example: 10.1
  • currency Currency
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code string

    Merchant account that receives the payment.

    Example: "MH4H92C7"
  • description string

    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.

  • return_url string format: uri

    Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

  • id string Read only

    Unique SumUp identifier of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDINGFAILEDPAIDEXPIRED

    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.

  • date string format: date-time

    Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string format: date-time, nullable

    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: "2020-02-29T10:56:56+00:00"
  • customer_id string

    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"
  • mandate Mandate Response

    Details of the mandate linked to the saved payment instrument.

     Show attributes
     Close
    Mandate Response
    • type string

      Type of mandate stored for the checkout or payment instrument.

    • status string
      Options:  activeinactive

      Current lifecycle status of the mandate.

      Example: "active"
    • merchant_code string

      Merchant account for which the mandate is valid.

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code string

      Transaction code returned by the acquirer/processing entity after processing the transaction.

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency Currency
      Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • timestamp string format: date-time

      Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFULCANCELLEDFAILEDPENDING

      Current status of the transaction.

    • payment_type Payment Type
      Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

      Unique code of the registered merchant to whom the payment is made.

      Example: "MH4H92C7"
    • vat_amount number

      Amount of the applicable VAT (out of the total transaction amount).

      Example: 6
    • tip_amount number

      Amount of the tip (out of the total transaction amount).

      Example: 3
    • entry_mode Entry Mode
      Options:  BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A

      Entry mode of the payment details.

    • auth_code string

      Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
The Checkout object
{
  "checkout_reference": null,
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": null,
  "return_url": null,
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": null,
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MH4H92C7"
  },
  "transactions": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": null,
      "auth_code": "053201",
      "internal_id": 1763892018
    }
  ]
}
Checkouts

List checkouts

GET /v0.1/checkouts

Lists created checkout resources according to the applied checkout_reference.

Required scopes: payments

Query Parameters

  • checkout_reference string

    Filters the list of checkout resources by the unique ID of the checkout.

Response

Returns a list of checkout resources.

[]CheckoutSuccess
 Show attributes
 Close
Checkout Success
  • checkout_reference string max length: 90

    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.

  • amount number

    Amount to be charged to the payer, expressed in major units.

    Example: 10.1
  • currency Currency
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code string

    Merchant account that receives the payment.

    Example: "MH4H92C7"
  • description string

    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.

  • return_url string format: uri

    Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

  • id string Read only

    Unique SumUp identifier of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDINGFAILEDPAIDEXPIRED

    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.

  • date string format: date-time

    Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string format: date-time, nullable

    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: "2020-02-29T10:56:56+00:00"
  • customer_id string

    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"
  • mandate Mandate Response

    Details of the mandate linked to the saved payment instrument.

     Show attributes
     Close
    Mandate Response
    • type string

      Type of mandate stored for the checkout or payment instrument.

    • status string
      Options:  activeinactive

      Current lifecycle status of the mandate.

      Example: "active"
    • merchant_code string

      Merchant account for which the mandate is valid.

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code string

      Transaction code returned by the acquirer/processing entity after processing the transaction.

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency Currency
      Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • timestamp string format: date-time

      Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFULCANCELLEDFAILEDPENDING

      Current status of the transaction.

    • payment_type Payment Type
      Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

      Unique code of the registered merchant to whom the payment is made.

      Example: "MH4H92C7"
    • vat_amount number

      Amount of the applicable VAT (out of the total transaction amount).

      Example: 6
    • tip_amount number

      Amount of the tip (out of the total transaction amount).

      Example: 3
    • entry_mode Entry Mode
      Options:  BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A

      Entry mode of the payment details.

    • auth_code string

      Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • transaction_code string Read only

    Transaction code of the successful transaction with which the payment for the checkout is completed.

    Example: "TEENSK4W2K"
  • transaction_id string Read only

    Transaction ID of the successful transaction with which the payment for the checkout is completed.

    Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
  • merchant_name string

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url string

    URL where the payer is redirected after a redirect-based payment or SCA flow completes.

    Example: "https://mysite.com/completed_purchase"
  • payment_instrument object

    Details of the saved payment instrument created or reused during checkout processing.

     Show attributes
     Close
    Attributes
    • token string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
GET /v0.1/checkouts 
curl https://api.sumup.com/v0.1/checkouts \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.list();
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.ListAsync();
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().listCheckouts();
from sumup import Sumup


client = Sumup()


result = client.checkouts.list()
$sumup = new \SumUp\SumUp();


$result = $sumup->checkouts->list();
client := sumup.NewClient()


result, err := client.Checkouts.List(context.Background())
use sumup::Client;


let client = Client::default();


let result = client.checkouts().list(sumup::ListCheckoutsParams{
    checkout_reference: Some("checkout_reference".to_string()),
}).await;
List checkouts response
[
  {
    "checkout_reference": null,
    "amount": 10.1,
    "currency": "EUR",
    "merchant_code": "MH4H92C7",
    "description": null,
    "return_url": null,
    "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
    "status": null,
    "date": "2020-02-29T10:56:56+00:00",
    "valid_until": "2020-02-29T10:56:56+00:00",
    "customer_id": "831ff8d4cd5958ab5670",
    "mandate": {
      "type": "recurrent",
      "status": "active",
      "merchant_code": "MH4H92C7"
    },
    "transactions": [
      {
        "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
        "transaction_code": "TEENSK4W2K",
        "amount": 10.1,
        "currency": "EUR",
        "timestamp": "2020-02-29T10:56:56.876Z",
        "status": null,
        "payment_type": null,
        "installments_count": null,
        "merchant_code": "MH4H92C7",
        "vat_amount": 6,
        "tip_amount": 3,
        "entry_mode": null,
        "auth_code": "053201",
        "internal_id": 1763892018
      }
    ],
    "transaction_code": "TEENSK4W2K",
    "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
    "merchant_name": "Sample Merchant",
    "redirect_url": "https://mysite.com/completed_purchase",
    "payment_instrument": {
      "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
    }
  }
]

Content-Type: application/json

The request is not authorized.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 401
{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}
Checkouts

Create a checkout

POST /v0.1/checkouts

Creates a new payment checkout resource. The unique checkout_reference created by this request, is used for further manipulation of the checkout.

For 3DS checkouts, add the redirect_url parameter to your request body schema.

Follow by processing a checkout to charge the provided payment instrument.

Required scopes: payments

Body Parameters

  • checkout_reference string required max length: 90

    Merchant-defined reference for the new checkout. It should be unique enough for you to identify the payment attempt in your own systems.

  • amount number required

    Amount to be charged to the payer, expressed in major units.

  • currency Currency required
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code string required

    Merchant account that should receive the payment.

    Example: "MH4H92C7"
  • description string

    Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.

  • return_url string format: uri

    Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

  • customer_id string

    Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer.

  • purpose string default: CHECKOUT
    Options:  CHECKOUTSETUP_RECURRING_PAYMENT

    Business purpose of the checkout. Use CHECKOUT for a standard payment and SETUP_RECURRING_PAYMENT when collecting consent and payment details for future recurring charges.

  • valid_until string format: date-time, nullable

    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: "2020-02-29T10:56:56+00:00"
  • redirect_url string

    URL where the payer should be sent after a redirect-based payment or SCA flow completes. This is required for APMs and recommended for card checkouts that may require 3DS. If it is omitted, the Payment Widget can render the challenge in an iframe instead of using a full-page redirect.

    Example: "https://mysite.com/completed_purchase"

Response

Returns the created checkout resource. See Checkout object .

  • checkout_reference string max length: 90

    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.

  • amount number

    Amount to be charged to the payer, expressed in major units.

    Example: 10.1
  • currency Currency
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code string

    Merchant account that receives the payment.

    Example: "MH4H92C7"
  • description string

    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.

  • return_url string format: uri

    Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

  • id string Read only

    Unique SumUp identifier of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDINGFAILEDPAIDEXPIRED

    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.

  • date string format: date-time

    Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string format: date-time, nullable

    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: "2020-02-29T10:56:56+00:00"
  • customer_id string

    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"
  • mandate Mandate Response

    Details of the mandate linked to the saved payment instrument.

     Show attributes
     Close
    Mandate Response
    • type string

      Type of mandate stored for the checkout or payment instrument.

    • status string
      Options:  activeinactive

      Current lifecycle status of the mandate.

      Example: "active"
    • merchant_code string

      Merchant account for which the mandate is valid.

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code string

      Transaction code returned by the acquirer/processing entity after processing the transaction.

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency Currency
      Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • timestamp string format: date-time

      Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFULCANCELLEDFAILEDPENDING

      Current status of the transaction.

    • payment_type Payment Type
      Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

      Unique code of the registered merchant to whom the payment is made.

      Example: "MH4H92C7"
    • vat_amount number

      Amount of the applicable VAT (out of the total transaction amount).

      Example: 6
    • tip_amount number

      Amount of the tip (out of the total transaction amount).

      Example: 3
    • entry_mode Entry Mode
      Options:  BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A

      Entry mode of the payment details.

    • auth_code string

      Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
POST /v0.1/checkouts 
curl https://api.sumup.com/v0.1/checkouts \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "checkout_reference": "",
    "amount": 0,
    "currency": "EUR",
    "merchant_code": "MH4H92C7"
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.create({
  checkout_reference: "",
  amount: 0,
  currency: "EUR",
  merchant_code: "MH4H92C7",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.CreateAsync(
    new CheckoutCreateRequest
    {
        CheckoutReference = "",
        Amount = 0,
        Currency = "EUR",
        MerchantCode = "MH4H92C7",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().createCheckout(
  CheckoutCreateRequest.builder()
    .checkoutReference("")
    .amount(0f)
    .currency(Currency.fromValue("EUR"))
    .merchantCode("MH4H92C7")
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.create(CreateCheckoutBody(
  checkout_reference="",
  amount=0,
  currency="EUR",
  merchant_code="MH4H92C7",
))
$sumup = new \SumUp\SumUp();


$result = $sumup->checkouts->create([
  'checkout_reference' => '',
  'amount' => 0,
  'currency' => 'EUR',
  'merchant_code' => 'MH4H92C7',
]);
client := sumup.NewClient()


result, err := client.Checkouts.Create(context.Background(), sumup.CheckoutsCreateParams{
  CheckoutReference: "",
  Amount: 0,
  Currency: "EUR",
  MerchantCode: "MH4H92C7",
})
use sumup::Client;


let client = Client::default();


let result = client.checkouts().create(sumup::CreateCheckoutBody{
  checkout_reference: "".to_string(),
  amount: 0,
  currency: "EUR".to_string(),
  merchant_code: "MH4H92C7".to_string(),
}).await;
Response
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "merchant_country": "DE",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MH4H92C7"
  },
  "transactions": [
    {
      "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",
      "internal_id": 0
    }
  ]
}
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "redirect_url": "https://mysite.com/completed_purchase",
  "transactions": [
    {
      "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",
      "internal_id": 0
    }
  ]
}
{
  "checkout_reference": "8ea25ec3-3293-40e9-a165-6d7f3b3073c5",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "My Checkout",
  "return_url": "http://example.com",
  "id": "88fcf8de-304d-4820-8f1c-ec880290eb92",
  "status": "PENDING",
  "date": "2021-06-29T11:08:36.000+00:00",
  "merchant_name": "My company",
  "merchant_country": "DE",
  "redirect_url": "https://sumup.com",
  "purpose": "CHECKOUT",
  "transactions": [
    {
      "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",
      "internal_id": 0
    }
  ]
}

Content-Type: application/json

The request body is invalid.

  • message string

    Short description of the error.

  • error_code string

    Platform code for the error.

  • param string

    Parameter name (with relative location) to which the error applies. Parameters from embedded resources are displayed using dot notation. For example, card.name refers to the name parameter embedded in the card object.
Error 400
{
  "message": "Validation error",
  "error_code": "MISSING",
  "param": "merchant_code"
}
Checkouts

Retrieve a checkout

GET /v0.1/checkouts/{id}

Retrieves an identified checkout resource. Use this request after processing a checkout to confirm its status and inform the end user respectively.

Required scopes: payments

Path Parameters

  • id string required

    Unique ID of the checkout resource.

Response

Returns the requested checkout resource.

  • checkout_reference string max length: 90

    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.

  • amount number

    Amount to be charged to the payer, expressed in major units.

    Example: 10.1
  • currency Currency
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code string

    Merchant account that receives the payment.

    Example: "MH4H92C7"
  • description string

    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.

  • return_url string format: uri

    Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

  • id string Read only

    Unique SumUp identifier of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDINGFAILEDPAIDEXPIRED

    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.

  • date string format: date-time

    Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string format: date-time, nullable

    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: "2020-02-29T10:56:56+00:00"
  • customer_id string

    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"
  • mandate Mandate Response

    Details of the mandate linked to the saved payment instrument.

     Show attributes
     Close
    Mandate Response
    • type string

      Type of mandate stored for the checkout or payment instrument.

    • status string
      Options:  activeinactive

      Current lifecycle status of the mandate.

      Example: "active"
    • merchant_code string

      Merchant account for which the mandate is valid.

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code string

      Transaction code returned by the acquirer/processing entity after processing the transaction.

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency Currency
      Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • timestamp string format: date-time

      Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFULCANCELLEDFAILEDPENDING

      Current status of the transaction.

    • payment_type Payment Type
      Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

      Unique code of the registered merchant to whom the payment is made.

      Example: "MH4H92C7"
    • vat_amount number

      Amount of the applicable VAT (out of the total transaction amount).

      Example: 6
    • tip_amount number

      Amount of the tip (out of the total transaction amount).

      Example: 3
    • entry_mode Entry Mode
      Options:  BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A

      Entry mode of the payment details.

    • auth_code string

      Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • transaction_code string Read only

    Transaction code of the successful transaction with which the payment for the checkout is completed.

    Example: "TEENSK4W2K"
  • transaction_id string Read only

    Transaction ID of the successful transaction with which the payment for the checkout is completed.

    Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
  • merchant_name string

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url string

    URL where the payer is redirected after a redirect-based payment or SCA flow completes.

    Example: "https://mysite.com/completed_purchase"
  • payment_instrument object

    Details of the saved payment instrument created or reused during checkout processing.

     Show attributes
     Close
    Attributes
    • token string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
GET /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.get("id");
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.GetAsync(
    "id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().getCheckout(
  "id"
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.get("id")
$sumup = new \SumUp\SumUp();


$result = $sumup->checkouts->get('id');
client := sumup.NewClient()


result, err := client.Checkouts.Get(context.Background(), "id")
use sumup::Client;


let client = Client::default();


let result = client.checkouts().get("id").await;
Retrieve a checkout response
{
  "checkout_reference": null,
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": null,
  "return_url": null,
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": null,
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MH4H92C7"
  },
  "transactions": [
    {
      "id": "6b425463-3e1b-431d-83fa-1e51c2925e99",
      "transaction_code": "TEENSK4W2K",
      "amount": 10.1,
      "currency": "EUR",
      "timestamp": "2020-02-29T10:56:56.876Z",
      "status": null,
      "payment_type": null,
      "installments_count": null,
      "merchant_code": "MH4H92C7",
      "vat_amount": 6,
      "tip_amount": 3,
      "entry_mode": null,
      "auth_code": "053201",
      "internal_id": 1763892018
    }
  ],
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "merchant_name": "Sample Merchant",
  "redirect_url": "https://mysite.com/completed_purchase",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  }
}

Content-Type: application/json

The request is not authorized.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 401
{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}
Checkouts

Process a checkout

PUT /v0.1/checkouts/{id}

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.

Follow this request with Retrieve a checkout to confirm its status.

Path Parameters

  • id string required

    Unique ID of the checkout resource.

Body Parameters

  • payment_type string required
    Options:  cardboletoidealblikbancontactgoogle_payapple_pay

    Payment method used for this processing attempt. It determines which additional request fields are required.

  • installments integer minimum: 1, maximum: 12

    Number of installments for deferred payments. Available only to merchant users in Brazil.

  • mandate Mandate Payload

    Mandate details used when a checkout should create a reusable card token for future recurring or merchant-initiated payments.

     Show attributes
     Close
    Mandate Payload
    • type string required
      Options:  recurrent

      Type of mandate to create for the saved payment instrument.

      Example: "recurrent"
    • user_agent string required

      Browser or client user agent observed when consent was collected.

      Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36"
    • user_ip string

      IP address of the payer when the mandate was accepted.

      Example: "172.217.169.174"
    Example: {"type":"recurrent","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36","user_ip":"172.217.169.174"}
  • card Card

    Required when payment type is card. Details of the payment card.

     Show attributes
     Close
    Card
    • name string required Write only

      Name of the cardholder as it appears on the payment card.

      Example: "FIRSTNAME LASTNAME"
    • number string required Write only

      Number of the payment card (without spaces).

      Example: "1234567890123456"
    • expiry_year string required min length: 2, max length: 4, Write only

      Year from the expiration time of the payment card. Accepted formats are YY and YYYY.

      Example: "2023"
    • expiry_month string required Write only
      Options:  010203040506070809101112

      Month from the expiration time of the payment card. Accepted format is MM.

    • cvv string required min length: 3, max length: 4, Write only

      Three or four-digit card verification value (security code) of the payment card.

      Example: "123"
    • zip_code string min length: 5, max length: 5, Write only

      Required five-digit ZIP code. Applicable only to merchant users in the USA.

      Example: "12345"
    • type Card Type required
      Options:  ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN

      Issuing card network of the payment card used for the transaction.

  • google_pay object

    Raw PaymentData object received from Google Pay. Send the Google Pay response payload as-is.

    Example: {"apiVersionMinor":0,"apiVersion":2,"paymentMethodData":{"description":"Visa •••• 1111","tokenizationData":{"type":"PAYMENT_GATEWAY","token":"token-data"},"type":"CARD","info":{"cardNetwork":"VISA","cardDetails":"1111"}}}
  • apple_pay object

    Raw payment token object received from Apple Pay. Send the Apple Pay response payload as-is.

    Example: {"token":{"paymentData":{"data":"si2xuT2ArQo689SfE-long-token","signature":"MIAGCSqGSIb3DQEHA-long-signature","header":{"publicKeyHash":"PWfjDi3TSwgZ20TY/A7f3V6J/1rhHyRDCspbeljM0io=","ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEaBtz7UN2MNV0qInJVEEhXy10PU0KfO6KxFjXm93oKWL6lCsxZZGDl/EKioUHVSlKgpsKGin0xvgldfxeJVgy0g==","transactionId":"62e0568bc9258e9d0e059d745650fc8211d05ef7a7a1589a6411bf9b12cdfd04"},"version":"EC_v1"},"paymentMethod":{"displayName":"MasterCard 8837","network":"MasterCard","type":"debit"},"transactionIdentifier":"62E0568BC9258E9D0E059D745650FC8211D05EF7A7A1589A6411BF9B12CDFD04"}}
  • token string

    Saved-card token to use instead of raw card details when processing with a previously stored payment instrument.

  • customer_id string

    Customer identifier associated with the saved payment instrument. Required when token is provided.

  • personal_details Personal Details

    Personal details for the customer.

     Show attributes
     Close
    Personal Details
    • first_name string

      First name of the customer.

      Example: "John"
    • last_name string

      Last name of the customer.

      Example: "Doe"
    • email string

      Email address of the customer.

      Example: "user@example.com"
    • phone string

      Phone number of the customer.

      Example: "+491635559723"
    • birth_date string format: date

      Date of birth of the customer.

      Example: "1993-12-31"
    • tax_id string max length: 255

      An identification number user for tax purposes (e.g. CPF)

      Example: "423.378.593-47"
    • address Address Legacy

      Profile's personal address information.

       Show attributes
       Close
      Address Legacy
      • city string

        City name from the address.

        Example: "Berlin"
      • country string

        Two letter country code formatted according to ISO3166-1 alpha-2.

        Example: "DE"
      • line_1 string

        First line of the address with details of the street name and number.

        Example: "Sample street"
      • line_2 string

        Second line of the address with details of the building, unit, apartment, and floor numbers.

        Example: "ap. 5"
      • postal_code string

        Postal code from the address.

        Example: "10115"
      • state string

        State name or abbreviation from the address.

        Example: "Berlin"

Response

Returns the checkout resource after a processing attempt.

  • checkout_reference string max length: 90

    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.

  • amount number

    Amount to be charged to the payer, expressed in major units.

    Example: 10.1
  • currency Currency
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code string

    Merchant account that receives the payment.

    Example: "MH4H92C7"
  • description string

    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.

  • return_url string format: uri

    Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

  • id string Read only

    Unique SumUp identifier of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDINGFAILEDPAIDEXPIRED

    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.

  • date string format: date-time

    Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string format: date-time, nullable

    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: "2020-02-29T10:56:56+00:00"
  • customer_id string

    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"
  • mandate Mandate Response

    Details of the mandate linked to the saved payment instrument.

     Show attributes
     Close
    Mandate Response
    • type string

      Type of mandate stored for the checkout or payment instrument.

    • status string
      Options:  activeinactive

      Current lifecycle status of the mandate.

      Example: "active"
    • merchant_code string

      Merchant account for which the mandate is valid.

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code string

      Transaction code returned by the acquirer/processing entity after processing the transaction.

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency Currency
      Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • timestamp string format: date-time

      Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFULCANCELLEDFAILEDPENDING

      Current status of the transaction.

    • payment_type Payment Type
      Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

      Unique code of the registered merchant to whom the payment is made.

      Example: "MH4H92C7"
    • vat_amount number

      Amount of the applicable VAT (out of the total transaction amount).

      Example: 6
    • tip_amount number

      Amount of the tip (out of the total transaction amount).

      Example: 3
    • entry_mode Entry Mode
      Options:  BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A

      Entry mode of the payment details.

    • auth_code string

      Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
  • transaction_code string Read only

    Transaction code of the successful transaction with which the payment for the checkout is completed.

    Example: "TEENSK4W2K"
  • transaction_id string Read only

    Transaction ID of the successful transaction with which the payment for the checkout is completed.

    Example: "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
  • merchant_name string

    Name of the merchant

    Example: "Sample Merchant"
  • redirect_url string

    URL where the payer is redirected after a redirect-based payment or SCA flow completes.

    Example: "https://mysite.com/completed_purchase"
  • payment_instrument object

    Details of the saved payment instrument created or reused during checkout processing.

     Show attributes
     Close
    Attributes
    • token string

      Token value

      Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
PUT /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X PUT \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "payment_type": ""
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.process("id", {
  payment_type: "",
});
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.ProcessAsync(
    "id",
    new ProcessCheckout
    {
        PaymentType = "",
    }
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().processCheckout(
  "id",
  ProcessCheckout.builder()
    .paymentType(PaymentType.fromValue(""))
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.process("id", ProcessCheckoutBody(
  payment_type="",
))
$sumup = new \SumUp\SumUp();


$result = $sumup->checkouts->process('id', [
  'payment_type' => '',
]);
client := sumup.NewClient()


result, err := client.Checkouts.Process(context.Background(), "id", sumup.CheckoutsProcessParams{
  PaymentType: "",
})
use sumup::Client;


let client = Client::default();


let result = client.checkouts().process("id", sumup::ProcessCheckoutBody{
  payment_type: "".to_string(),
}).await;
Response
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase",
  "return_url": "http://example.com",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MH4H92C7"
  },
  "transactions": [
    {
      "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": "053201",
      "internal_id": 1763892018
    }
  ],
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
}
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase with token",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "merchant_name": "Sample Merchant",
  "redirect_url": "https://mysite.com/completed_purchase",
  "customer_id": "831ff8d4cd5958ab5670",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  },
  "transactions": [
    {
      "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": "053201",
      "internal_id": 1763892018
    }
  ]
}
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "BRL",
  "merchant_code": "MH4H92C7",
  "description": "Boleto checkout",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": "PENDING",
  "date": "2021-07-06T12:34:02.000+00:00",
  "merchant_name": "Sample shop",
  "boleto": {
    "barcode": "34191090081790614310603072340007886840000000200",
    "url": "https://checkouts.sample.com/v0.1/checkouts/2e7a36cc-7897-446b-a966-952ab5f049ea/boleto"
  },
  "redirect_url": "https://website.com",
  "purpose": "CHECKOUT",
  "transactions": [
    {
      "id": "debd2986-9852-4e86-8a8e-7ea9c87dd679",
      "transaction_code": "TEN3E696NP",
      "merchant_code": "MH4H92C9",
      "amount": 10.1,
      "vat_amount": 6,
      "tip_amount": 3,
      "currency": "BRL",
      "timestamp": "2021-07-06T12:34:16.460+00:00",
      "status": "PENDING",
      "payment_type": "BOLETO",
      "entry_mode": "BOLETO",
      "installments_count": 1,
      "internal_id": 1763892018
    }
  ]
}
{
  "next_step": {
    "url": "https://r3.girogate.de/ti/simideal",
    "method": "GET",
    "payload": {
      "tx": "961473700",
      "rs": "ILnaUeQTKJ184fVrjGILrLjePX9E4rmz",
      "cs": "c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5"
    },
    "full": "https://r3.girogate.de/ti/simideal?tx=961473700&rs=ILnaUeQTKJ184fVrjGILrLjePX9E4rmz&cs=c8bc0ea231f8372431ca22d6f8319f8de0263d0b1705759ed27155f245f193c5",
    "mechanism": [
      "browser"
    ]
  }
}
{
  "next_step": {
    "url": "https://r3.girogate.de/ti/simbcmc",
    "method": "GET",
    "payload": {
      "tx": "624788471",
      "rs": "5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB",
      "cs": "697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc"
    },
    "full": "https://r3.girogate.de/ti/simbcmc?tx=624788471&rs=5MioXoKt2Gwj9dLgqAX1bMRBuT5xTSdB&cs=697edacdd9175f3f99542500fa0ff08280b66aaff3c2641a2e212e4b039473cc",
    "mechanism": [
      "browser"
    ]
  }
}

Content-Type: application/json

The request body is invalid for processing the checkout.
Error 400
{
  "message": "Validation error",
  "error_code": "INVALID",
  "param": "card.expiry_year"
}
Checkouts

Deactivate a checkout

DELETE /v0.1/checkouts/{id}

Deactivates an identified checkout resource. If the checkout has already been processed it can not be deactivated.

Required scopes: payments

Path Parameters

  • id string required

    Unique ID of the checkout resource.

Response

Returns the checkout object after successful deactivation. See Checkout object .

  • checkout_reference string max length: 90

    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.

  • amount number

    Amount to be charged to the payer, expressed in major units.

    Example: 10.1
  • currency Currency
    Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

    Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

    Example: "EUR"
  • merchant_code string

    Merchant account that receives the payment.

    Example: "MH4H92C7"
  • description string

    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.

  • return_url string format: uri

    Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

  • id string Read only

    Unique SumUp identifier of the checkout resource.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
  • status string
    Options:  PENDINGFAILEDPAIDEXPIRED

    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.

  • date string format: date-time

    Date and time of the creation of the payment checkout. Response format expressed according to ISO8601 code.

    Example: "2020-02-29T10:56:56+00:00"
  • valid_until string format: date-time, nullable

    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: "2020-02-29T10:56:56+00:00"
  • customer_id string

    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"
  • mandate Mandate Response

    Details of the mandate linked to the saved payment instrument.

     Show attributes
     Close
    Mandate Response
    • type string

      Type of mandate stored for the checkout or payment instrument.

    • status string
      Options:  activeinactive

      Current lifecycle status of the mandate.

      Example: "active"
    • merchant_code string

      Merchant account for which the mandate is valid.

      Example: "MH4H92C7"
    Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
  • transactions []object unique items

    Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.

     Show attributes
     Close
    Attributes
    • id string

      Unique ID of the transaction.

      Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
    • transaction_code string

      Transaction code returned by the acquirer/processing entity after processing the transaction.

      Example: "TEENSK4W2K"
    • amount number

      Total amount of the transaction.

      Example: 10.1
    • currency Currency
      Options:  BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD

      Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

      Example: "EUR"
    • timestamp string format: date-time

      Date and time of the creation of the transaction. Response format expressed according to ISO8601 code.

      Example: "2020-02-29T10:56:56.876Z"
    • status string
      Options:  SUCCESSFULCANCELLEDFAILEDPENDING

      Current status of the transaction.

    • payment_type Payment Type
      Options:  CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN

      Payment type used for the transaction.

    • installments_count integer minimum: 1

      Current number of the installment for deferred payments.

    • merchant_code string

      Unique code of the registered merchant to whom the payment is made.

      Example: "MH4H92C7"
    • vat_amount number

      Amount of the applicable VAT (out of the total transaction amount).

      Example: 6
    • tip_amount number

      Amount of the tip (out of the total transaction amount).

      Example: 3
    • entry_mode Entry Mode
      Options:  BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A

      Entry mode of the payment details.

    • auth_code string

      Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.

      Example: "053201"
    • internal_id integer

      Internal unique ID of the transaction on the SumUp platform.

      Example: 1763892018
DELETE /v0.1/checkouts/{id} 
curl https://api.sumup.com/v0.1/checkouts/{id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.deactivate("id");
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.DeactivateAsync(
    "id"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().deactivateCheckout(
  "id"
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.deactivate("id")
$sumup = new \SumUp\SumUp();


$result = $sumup->checkouts->deactivate('id');
client := sumup.NewClient()


result, err := client.Checkouts.Deactivate(context.Background(), "id")
use sumup::Client;


let client = Client::default();


let result = client.checkouts().deactivate("id").await;
Response
{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "id": "817340ce-f1d9-4609-b90a-6152f8ee267j",
  "amount": 2,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Deletion example",
  "purpose": "CHECKOUT",
  "status": "EXPIRED",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "merchant_name": "Sample Merchant",
  "transactions": []
}

Content-Type: application/json

The request is not authorized.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 401
{
  "detail": "Unauthorized.",
  "status": 401,
  "title": "Unauthorized",
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
  "type": "https://developer.sumup.com/problem/unauthorized"
}
Checkouts

Get available payment methods

GET /v0.1/merchants/{merchant_code}/payment-methods

Get payment methods available for the given merchant to use with a checkout.

Path Parameters

  • merchant_code string required

    The SumUp merchant code.

    Example: "MH4H92C7"

Query Parameters

  • amount number

    The amount for which the payment methods should be eligible, in major units.

    Example: 9.99
  • currency string

    The currency for which the payment methods should be eligible.

    Example: "EUR"

Response

Available payment methods

  • available_payment_methods []object
     Show attributes
     Close
    Attributes
    • id string required

      The ID of the payment method.

      Example: "qr_code_pix"
GET /v0.1/merchants/{merchant_code}/payment-methods 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/payment-methods \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


const result = await client.checkouts.listAvailablePaymentMethods("MH4H92C7");
using SumUp;


var client = new SumUpClient();


var result = await client.Checkouts.ListAvailablePaymentMethodsAsync(
    "MH4H92C7"
);
import com.sumup.sdk.SumUpClient;


SumUpClient client = SumUpClient.builder().build();


var result = client.checkouts().getPaymentMethods(
  "MH4H92C7"
);
from sumup import Sumup


client = Sumup()


result = client.checkouts.list_available_payment_methods("MH4H92C7")
$sumup = new \SumUp\SumUp();


$result = $sumup->checkouts->listAvailablePaymentMethods('MH4H92C7');
client := sumup.NewClient()


result, err := client.Checkouts.ListAvailablePaymentMethods(context.Background(), "MH4H92C7")
use sumup::Client;


let client = Client::default();


let result = client.checkouts().list_available_payment_methods("MH4H92C7", sumup::GetPaymentMethodsParams{
    amount: Some(9.99),
    currency: Some("EUR".to_string()),
}).await;
Response
{
  "available_payment_methods": [
    {
      "id": "apple_pay"
    },
    {
      "id": "blik"
    }
  ]
}

Content-Type: application/json

The request is invalid for the submitted query parameters.

  • title string

    Short title of the error.

  • details string

    Details of the error.

  • status number

    The status code.

  • failed_constraints []object

    List of violated validation constraints.

     Show attributes
     Close
    Attributes
    • message string
    • reference string
Error 400
{
  "failed_constraints": [
    {
      "message": "Currency must also be specified when filtering by amount",
      "reference": "currency"
    }
  ],
  "status": 400,
  "title": "Bad Request"
}