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.

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_referencestringmax 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.

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

Example: 10.1
currencyCurrency
Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

Example: "EUR"
merchant_codestring
Merchant account 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_urlstringformat: uri
Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

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

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
statusstring
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.

Example: "PENDING"
datestringformat: 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_untilstringformat: 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_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"
mandateMandate Response
Details of the mandate linked to the saved payment instrument.
Show attributes
Close
Mandate Response
- typestring
  Type of mandate stored for the checkout or payment instrument.
- statusstring
  Options: activeinactive
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Merchant account for which the mandate is valid.
  
  Example: "MH4H92C7"
Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
hosted_checkout_urlstringformat: uri, Read only
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"
transactions[]objectunique 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
- idstring
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- amountnumber
  Total amount of the transaction.
  
  Example: 10.1
- currencyCurrency
  Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- timestampstringformat: 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"
- statusTransaction Status
  Options: SUCCESSFULCANCELLEDFAILEDPENDINGREFUNDED
  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.
- payment_typePayment Type
  Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
  Payment type used for the transaction.
- installments_countintegerminimum: 1
  Current number of the installment for deferred payments.
- merchant_codestring
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- vat_amountnumber
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
- tip_amountnumber
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- entry_modeEntry Mode
  Options: BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A
  Entry mode of the payment details.
- auth_codestring
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"

1
{
2
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
3
  "amount": 10.1,
4
  "currency": "EUR",
5
  "merchant_code": "MH4H92C7",
6
  "description": "Purchase",
7
  "return_url": "http://example.com",
8
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
9
  "status": "PENDING",
10
  "date": "2020-02-29T10:56:56+00:00",
11
  "valid_until": "2020-02-29T10:56:56+00:00",
12
  "customer_id": "831ff8d4cd5958ab5670",
13
  "mandate": {
14
    "type": "recurrent",
15
    "status": "active",
16
    "merchant_code": "MH4H92C7"
17
  },
18
  "hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676",
19
  "transactions": [
20
    {
21
      "id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
22
      "transaction_code": "TEENSK4W2K",
23
      "amount": 10.1,
24
      "currency": "EUR",
25
      "timestamp": "2020-02-29T10:56:56.876Z",
26
      "status": "SUCCESSFUL",
27
      "payment_type": "ECOM",
28
      "installments_count": 1,
29
      "merchant_code": "MH4H92C7",
30
      "vat_amount": 6,
31
      "tip_amount": 3,
32
      "entry_mode": "CUSTOMER_ENTRY",
33
      "auth_code": "012345"
34
    }
35
  ]
36
}

Checkouts

List checkouts

GET/v0.1/checkouts

Lists created checkout resources according to the applied checkout_reference.

Required scopes:payments

Query Parameters

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

Response

Returns a list of checkout resources.

[]CheckoutSuccess

Show attributes

checkout_referencestringmax 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.

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

Example: 10.1
currencyCurrency
Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

Example: "EUR"
merchant_codestring
Merchant account 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_urlstringformat: uri
Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

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

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
statusstring
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.

Example: "PENDING"
datestringformat: 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_untilstringformat: 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_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"
mandateMandate Response
Details of the mandate linked to the saved payment instrument.
Show attributes
Close
Mandate Response
- typestring
  Type of mandate stored for the checkout or payment instrument.
- statusstring
  Options: activeinactive
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Merchant account for which the mandate is valid.
  
  Example: "MH4H92C7"
Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
hosted_checkout_urlstringformat: uri, Read only
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"
transactions[]objectunique 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
- idstring
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- amountnumber
  Total amount of the transaction.
  
  Example: 10.1
- currencyCurrency
  Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- timestampstringformat: 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"
- statusTransaction Status
  Options: SUCCESSFULCANCELLEDFAILEDPENDINGREFUNDED
  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.
- payment_typePayment Type
  Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
  Payment type used for the transaction.
- installments_countintegerminimum: 1
  Current number of the installment for deferred payments.
- merchant_codestring
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- vat_amountnumber
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
- tip_amountnumber
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- entry_modeEntry Mode
  Options: BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A
  Entry mode of the payment details.
- auth_codestring
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
transaction_codestringRead only
Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_idstringRead only
Transaction ID of the successful transaction with which the payment for the checkout is completed.

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 attributes
Close
Attributes
- tokenstring
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"

1
curl https://api.sumup.com/v0.1/checkouts \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.checkouts.list();

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Checkouts.ListAsync();

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.checkouts().listCheckouts();

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.checkouts.list()

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->checkouts->list();

1
client := sumup.NewClient()
2

3
result, err := client.Checkouts.List(context.Background())

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.checkouts().list(sumup::ListCheckoutsParams{
6
    checkout_reference: Some("checkout_reference".to_string()),
7
}).await;

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

Error 401

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: 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."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Error 401

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

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. To use the Hosted Checkout page, set the hosted_checkout.enabled to true.

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

Required scopes:payments

Body Parameters

checkout_referencestringrequiredmax 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.

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

Example: 10.1
currencyCurrencyrequired
Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

Example: "EUR"
merchant_codestringrequired
Merchant account that should receive the payment.

Example: "MH4H92C7"
descriptionstring
Short merchant-defined description shown in SumUp tools and reporting for easier identification of the checkout.

Example: "Purchase"
return_urlstringformat: uri
Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

Example: "http://example.com/"
customer_idstring
Merchant-scoped customer identifier. Required when setting up recurring payments and useful when the checkout should be linked to a returning payer.

Example: "831ff8d4cd5958ab5670"
purposestringdefault: 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_untilstringformat: 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_urlstring
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"
hosted_checkoutHosted Checkout
Hosted Checkout configuration. Enable it to receive a SumUp-hosted payment page URL in the checkout response.
Show attributes
Close
Hosted Checkout
- enabledbooleanrequired
  Whether the checkout should include a SumUp-hosted payment page.
  
  Example: true

Response

Returns the created checkout resource. See Checkout object.

checkout_referencestringmax 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.

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

Example: 10.1
currencyCurrency
Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

Example: "EUR"
merchant_codestring
Merchant account 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_urlstringformat: uri
Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

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

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
statusstring
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.

Example: "PENDING"
datestringformat: 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_untilstringformat: 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_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"
mandateMandate Response
Details of the mandate linked to the saved payment instrument.
Show attributes
Close
Mandate Response
- typestring
  Type of mandate stored for the checkout or payment instrument.
- statusstring
  Options: activeinactive
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Merchant account for which the mandate is valid.
  
  Example: "MH4H92C7"
Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
hosted_checkout_urlstringformat: uri, Read only
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"
transactions[]objectunique 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
- idstring
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- amountnumber
  Total amount of the transaction.
  
  Example: 10.1
- currencyCurrency
  Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- timestampstringformat: 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"
- statusTransaction Status
  Options: SUCCESSFULCANCELLEDFAILEDPENDINGREFUNDED
  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.
- payment_typePayment Type
  Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
  Payment type used for the transaction.
- installments_countintegerminimum: 1
  Current number of the installment for deferred payments.
- merchant_codestring
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- vat_amountnumber
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
- tip_amountnumber
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- entry_modeEntry Mode
  Options: BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A
  Entry mode of the payment details.
- auth_codestring
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"

1
curl https://api.sumup.com/v0.1/checkouts \
2
 -X POST \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{
5
    "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
6
    "amount": 10.1,
7
    "currency": "EUR",
8
    "merchant_code": "MH4H92C7"
9
  }'

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.checkouts.create({
6
  checkout_reference: "f00a8f74-b05d-4605-bd73-2a901bae5802",
7
  amount: 10.1,
8
  currency: "EUR",
9
  merchant_code: "MH4H92C7",
10
});

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Checkouts.CreateAsync(
6
    new CheckoutCreateRequest
7
    {
8
        CheckoutReference = "f00a8f74-b05d-4605-bd73-2a901bae5802",
9
        Amount = 10.1,
10
        Currency = "EUR",
11
        MerchantCode = "MH4H92C7",
12
    }
13
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.checkouts().createCheckout(
6
  CheckoutCreateRequest.builder()
7
    .checkoutReference("f00a8f74-b05d-4605-bd73-2a901bae5802")
8
    .amount(10.1f)
9
    .currency(Currency.fromValue("EUR"))
10
    .merchantCode("MH4H92C7")
11
    .build()
12
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.checkouts.create(CreateCheckoutBody(
6
  checkout_reference="f00a8f74-b05d-4605-bd73-2a901bae5802",
7
  amount=10.1,
8
  currency="EUR",
9
  merchant_code="MH4H92C7",
10
))

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->checkouts->create([
4
  'checkout_reference' => 'f00a8f74-b05d-4605-bd73-2a901bae5802',
5
  'amount' => 10.1,
6
  'currency' => 'EUR',
7
  'merchant_code' => 'MH4H92C7',
8
]);

1
client := sumup.NewClient()
2

3
result, err := client.Checkouts.Create(context.Background(), sumup.CheckoutsCreateParams{
4
  CheckoutReference: "f00a8f74-b05d-4605-bd73-2a901bae5802",
5
  Amount: 10.1,
6
  Currency: "EUR",
7
  MerchantCode: "MH4H92C7",
8
})

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.checkouts().create(sumup::CreateCheckoutBody{
6
  checkout_reference: "f00a8f74-b05d-4605-bd73-2a901bae5802".to_string(),
7
  amount: 10.1,
8
  currency: "EUR".to_string(),
9
  merchant_code: "MH4H92C7".to_string(),
10
}).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"
    }
  ]
}
{
  "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"
    }
  ]
}
{
  "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"
    }
  ]
}
{
  "checkout_reference": "b50pr914-6k0e-3091-a592-890010285b3d",
  "amount": 12,
  "currency": "EUR",
  "merchant_code": "MCXXXXXX",
  "merchant_country": "DE",
  "merchant_name": "Sample Shop",
  "description": "A sample checkout",
  "id": "64553e20-3f0e-49e4-8af3-fd0eca86ce91",
  "status": "PENDING",
  "date": "2000-01-01T12:49:24.899+00:00",
  "purpose": "CHECKOUT",
  "hosted_checkout": {
    "enabled": true
  },
  "hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676",
  "transactions": []
}

Content-Type: application/json

The request body is invalid.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"
paramstring
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.

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: 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."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Content-Type: application/json

The request isn't sufficiently authorized to create a checkout.

error_messagestring
Short description of the error.

Example: "request_not_allowed"
error_codestring
Platform code for the error.

Example: "FORBIDDEN"
status_codestring
HTTP status code for the error.

Example: "403"

Content-Type: application/json

A checkout already exists for the provided unique parameters.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

1
{
2
  "message": "Validation error",
3
  "error_code": "MISSING",
4
  "param": "merchant_code"
5
}

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_message": "checkout_payments_not_allowed",
3
  "error_code": "FORBIDDEN",
4
  "status_code": "403"
5
}

1
{
2
  "error_code": "DUPLICATED_CHECKOUT",
3
  "message": "Checkout with this checkout reference and pay to email already exists"
4
}

Checkouts

Retrieve a checkout

GET/v0.1/checkouts/{checkout_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

checkout_idstringrequired
Unique ID of the checkout resource.

Response

Returns the requested checkout resource.

checkout_referencestringmax 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.

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

Example: 10.1
currencyCurrency
Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

Example: "EUR"
merchant_codestring
Merchant account 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_urlstringformat: uri
Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

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

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
statusstring
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.

Example: "PENDING"
datestringformat: 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_untilstringformat: 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_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"
mandateMandate Response
Details of the mandate linked to the saved payment instrument.
Show attributes
Close
Mandate Response
- typestring
  Type of mandate stored for the checkout or payment instrument.
- statusstring
  Options: activeinactive
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Merchant account for which the mandate is valid.
  
  Example: "MH4H92C7"
Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
hosted_checkout_urlstringformat: uri, Read only
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"
transactions[]objectunique 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
- idstring
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- amountnumber
  Total amount of the transaction.
  
  Example: 10.1
- currencyCurrency
  Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- timestampstringformat: 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"
- statusTransaction Status
  Options: SUCCESSFULCANCELLEDFAILEDPENDINGREFUNDED
  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.
- payment_typePayment Type
  Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
  Payment type used for the transaction.
- installments_countintegerminimum: 1
  Current number of the installment for deferred payments.
- merchant_codestring
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- vat_amountnumber
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
- tip_amountnumber
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- entry_modeEntry Mode
  Options: BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A
  Entry mode of the payment details.
- auth_codestring
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
transaction_codestringRead only
Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_idstringRead only
Transaction ID of the successful transaction with which the payment for the checkout is completed.

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 attributes
Close
Attributes
- tokenstring
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"

1
curl https://api.sumup.com/v0.1/checkouts/{checkout_id} \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.checkouts.get("checkout_id");

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Checkouts.GetAsync(
6
    "checkout_id"
7
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.checkouts().getCheckout(
6
  "checkout_id"
7
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.checkouts.get("checkout_id")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->checkouts->get('checkout_id');

1
client := sumup.NewClient()
2

3
result, err := client.Checkouts.Get(context.Background(), "checkout_id")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.checkouts().get("checkout_id").await;

1
{
2
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
3
  "amount": 10.1,
4
  "currency": "EUR",
5
  "merchant_code": "MH4H92C7",
6
  "description": "Purchase",
7
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
8
  "status": "PENDING",
9
  "date": "2020-02-29T10:56:56+00:00",
10
  "transaction_code": "TEENSK4W2K",
11
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4"
12
}

Error 401
Error 404

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: 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."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

Error 401
Error 404

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}

Checkouts

Process a checkout

PUT/v0.1/checkouts/{checkout_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

checkout_idstringrequired
Unique ID of the checkout resource.

Body Parameters

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

Example: "card"
installmentsintegerminimum: 1, maximum: 12
Number of installments for deferred payments. Available only to merchant users in Brazil.

Example: 1
mandateMandate 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
- typestringrequired
  Options: recurrent
  Type of mandate to create for the saved payment instrument.
  
  Example: "recurrent"
- user_agentstringrequired
  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_ipstring
  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"}
cardCard
Required when payment type is card. Details of the payment card.
Show attributes
Close
Card
- namestringrequiredWrite only
  Name of the cardholder as it appears on the payment card.
  
  Example: "FIRSTNAME LASTNAME"
- numberstringrequiredWrite only
  Number of the payment card (without spaces).
  
  Example: "1234567890123456"
- expiry_yearstringrequiredmin 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_monthstringrequiredWrite only
  Options: 010203040506070809101112
  Month from the expiration time of the payment card. Accepted format is MM.
- cvvstringrequiredmin length: 3, max length: 4, Write only
  Three or four-digit card verification value (security code) of the payment card.
  
  Example: "123"
- zip_codestringmin length: 5, max length: 5, Write only
  Required five-digit ZIP code. Applicable only to merchant users in the USA.
  
  Example: "12345"
- typeCard Typerequired
  Options: ALELOAMEXCONECSCUPDINERSDISCOVEREFTPOSELOELVGIROCARDHIPERCARDINTERACJCBMAESTROMASTERCARDPLUXEESWILETICKETVISAVISA_ELECTRONVISA_VPAYVPAYVRUNKNOWN
  Issuing card network of the payment card used for the transaction.
google_payobject
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_payobject
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"}}
tokenstring
Saved-card token to use instead of raw card details when processing with a previously stored payment instrument.

Example: "ba85dfee-c3cf-48a6-84f5-d7d761fbba50"
customer_idstring
Customer identifier associated with the saved payment instrument. Required when token is provided.

Example: "MEDKHDTI"
personal_detailsPersonal Details
Personal details for the customer.
Show attributes
Close
Personal Details
- first_namestring
  First name of the customer.
  
  Example: "John"
- last_namestring
  Last name of the customer.
  
  Example: "Doe"
- emailstring
  Email address of the customer.
  
  Example: "user@example.com"
- phonestring
  Phone number of the customer.
  
  Example: "+491635559723"
- birth_datestringformat: date
  Date of birth of the customer.
  
  Example: "1993-12-31"
- tax_idstringmax length: 255
  An identification number user for tax purposes (e.g. CPF)
  
  Example: "423.378.593-47"
- addressAddress Legacy
  Profile's personal address information.
  
  Show attributes
  Close
  Address Legacy
  citystring
  City name from the address.
  
  Example: "Berlin"
  countrystring
  Two letter country code formatted according to ISO3166-1 alpha-2.
  
  Example: "DE"
  line_1string
  First line of the address with details of the street name and number.
  
  Example: "Sample street"
  line_2string
  Second line of the address with details of the building, unit, apartment, and floor numbers.
  
  Example: "ap. 5"
  postal_codestring
  Postal code from the address.
  
  Example: "10115"
  statestring
  State name or abbreviation from the address.
  
  Example: "Berlin"

Response

Returns the checkout resource after a processing attempt.

checkout_referencestringmax 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.

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

Example: 10.1
currencyCurrency
Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

Example: "EUR"
merchant_codestring
Merchant account 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_urlstringformat: uri
Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

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

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
statusstring
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.

Example: "PENDING"
datestringformat: 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_untilstringformat: 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_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"
mandateMandate Response
Details of the mandate linked to the saved payment instrument.
Show attributes
Close
Mandate Response
- typestring
  Type of mandate stored for the checkout or payment instrument.
- statusstring
  Options: activeinactive
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Merchant account for which the mandate is valid.
  
  Example: "MH4H92C7"
Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
hosted_checkout_urlstringformat: uri, Read only
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"
transactions[]objectunique 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
- idstring
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- amountnumber
  Total amount of the transaction.
  
  Example: 10.1
- currencyCurrency
  Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- timestampstringformat: 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"
- statusTransaction Status
  Options: SUCCESSFULCANCELLEDFAILEDPENDINGREFUNDED
  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.
- payment_typePayment Type
  Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
  Payment type used for the transaction.
- installments_countintegerminimum: 1
  Current number of the installment for deferred payments.
- merchant_codestring
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- vat_amountnumber
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
- tip_amountnumber
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- entry_modeEntry Mode
  Options: BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A
  Entry mode of the payment details.
- auth_codestring
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"
transaction_codestringRead only
Transaction code of the successful transaction with which the payment for the checkout is completed.

Example: "TEENSK4W2K"
transaction_idstringRead only
Transaction ID of the successful transaction with which the payment for the checkout is completed.

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 attributes
Close
Attributes
- tokenstring
  Token value
  
  Example: "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"

1
curl https://api.sumup.com/v0.1/checkouts/{checkout_id} \
2
 -X PUT \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{
5
    "payment_type": "card"
6
  }'

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.checkouts.process("checkout_id", {
6
  payment_type: "card",
7
});

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Checkouts.ProcessAsync(
6
    "checkout_id",
7
    new ProcessCheckout
8
    {
9
        PaymentType = "card",
10
    }
11
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.checkouts().processCheckout(
6
  "checkout_id",
7
  ProcessCheckout.builder()
8
    .paymentType(PaymentType.fromValue("card"))
9
    .build()
10
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.checkouts.process("checkout_id", ProcessCheckoutBody(
6
  payment_type="card",
7
))

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->checkouts->process('checkout_id', [
4
  'payment_type' => 'card',
5
]);

1
client := sumup.NewClient()
2

3
result, err := client.Checkouts.Process(context.Background(), "checkout_id", sumup.CheckoutsProcessParams{
4
  PaymentType: "card",
5
})

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.checkouts().process("checkout_id", sumup::ProcessCheckoutBody{
6
  payment_type: "card".to_string(),
7
}).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"
    }
  ],
  "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"
    }
  ]
}
{
  "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
    }
  ]
}
{
  "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.

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: 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."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

Content-Type: application/json

The request conflicts with the current state of the resource.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

1
{
2
  "message": "Validation error",
3
  "error_code": "INVALID",
4
  "param": "card.expiry_year"
5
}

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}

1
{
2
  "error_code": "CHECKOUT_PROCESSED",
3
  "message": "Checkout is already processed"
4
}

Checkouts

Deactivate a checkout

DELETE/v0.1/checkouts/{checkout_id}

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

Required scopes:payments

Path Parameters

checkout_idstringrequired
Unique ID of the checkout resource.

Response

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

checkout_referencestringmax 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.

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

Example: 10.1
currencyCurrency
Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.

Example: "EUR"
merchant_codestring
Merchant account 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_urlstringformat: uri
Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

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

Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"
statusstring
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.

Example: "PENDING"
datestringformat: 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_untilstringformat: 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_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"
mandateMandate Response
Details of the mandate linked to the saved payment instrument.
Show attributes
Close
Mandate Response
- typestring
  Type of mandate stored for the checkout or payment instrument.
- statusstring
  Options: activeinactive
  Current lifecycle status of the mandate.
  
  Example: "active"
- merchant_codestring
  Merchant account for which the mandate is valid.
  
  Example: "MH4H92C7"
Example: {"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}
hosted_checkout_urlstringformat: uri, Read only
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"
transactions[]objectunique 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
- idstring
  Unique ID of the transaction.
  
  Example: "6b425463-3e1b-431d-83fa-1e51c2925e99"
- transaction_codestring
  Transaction code returned by the acquirer/processing entity after processing the transaction.
  
  Example: "TEENSK4W2K"
- amountnumber
  Total amount of the transaction.
  
  Example: 10.1
- currencyCurrency
  Options: BGNBRLCHFCLPCOPCZKDKKEURGBPHRKHUFNOKPLNRONSEKUSD
  Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
  
  Example: "EUR"
- timestampstringformat: 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"
- statusTransaction Status
  Options: SUCCESSFULCANCELLEDFAILEDPENDINGREFUNDED
  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.
- payment_typePayment Type
  Options: CASHPOSECOMRECURRINGBITCOINBALANCEMOTOBOLETODIRECT_DEBITAPMUNKNOWN
  Payment type used for the transaction.
- installments_countintegerminimum: 1
  Current number of the installment for deferred payments.
- merchant_codestring
  Unique code of the registered merchant to whom the payment is made.
  
  Example: "MH4H92C7"
- vat_amountnumber
  Amount of the applicable VAT (out of the total transaction amount).
  
  Example: 6
- tip_amountnumber
  Amount of the tip (out of the total transaction amount).
  
  Example: 3
- entry_modeEntry Mode
  Options: BOLETOSOFORTIDEALBANCONTACTEPSMYBANKSATISPAYBLIKP24GIROPAYPIXQR_CODE_PIXAPPLE_PAYGOOGLE_PAYPAYPALTWINTNONECHIPMANUAL_ENTRYCUSTOMER_ENTRYMAGSTRIPE_FALLBACKMAGSTRIPEDIRECT_DEBITCONTACTLESSMOTOCONTACTLESS_MAGSTRIPEN/A
  Entry mode of the payment details.
- auth_codestring
  Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
  
  Example: "053201"

1
curl https://api.sumup.com/v0.1/checkouts/{checkout_id} \
2
 -X DELETE \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.checkouts.deactivate("checkout_id");

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Checkouts.DeactivateAsync(
6
    "checkout_id"
7
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.checkouts().deactivateCheckout(
6
  "checkout_id"
7
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.checkouts.deactivate("checkout_id")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->checkouts->deactivate('checkout_id');

1
client := sumup.NewClient()
2

3
result, err := client.Checkouts.Deactivate(context.Background(), "checkout_id")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.checkouts().deactivate("checkout_id").await;

1
{
2
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
3
  "id": "817340ce-f1d9-4609-b90a-6152f8ee267j",
4
  "amount": 2,
5
  "currency": "EUR",
6
  "merchant_code": "MH4H92C7",
7
  "description": "Deletion example",
8
  "purpose": "CHECKOUT",
9
  "status": "EXPIRED",
10
  "date": "2020-02-29T10:56:56+00:00",
11
  "valid_until": "2020-02-29T10:56:56+00:00",
12
  "merchant_name": "Sample Merchant",
13
  "transactions": []
14
}

Content-Type: application/json

The request is not authorized.

typestringrequiredformat: 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."
instancestringformat: uri
A URI reference that identifies the specific occurrence of the problem.

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

Content-Type: application/json

The request conflicts with the current state of the resource.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

1
{
2
  "detail": "Unauthorized.",
3
  "status": 401,
4
  "title": "Unauthorized",
5
  "trace_id": "3c77294349d3b5647ea2d990f0d8f017",
6
  "type": "https://developer.sumup.com/problem/unauthorized"
7
}

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}

1
{
2
  "error_code": "CHECKOUT_PROCESSED",
3
  "message": "Checkout is already processed"
4
}

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_codestringrequired
The SumUp merchant code.

Example: "MH4H92C7"

Query Parameters

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

Example: 9.99
currencystring
The currency for which the payment methods should be eligible.

Example: "EUR"

Response

Available payment methods

available_payment_methods[]object
Show attributes
Close
Attributes
- idstringrequired
  The ID of the payment method.
  
  Example: "qr_code_pix"

1
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/payment-methods \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

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

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Checkouts.ListAvailablePaymentMethodsAsync(
6
    "MH4H92C7"
7
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.checkouts().getPaymentMethods(
6
  "MH4H92C7"
7
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.checkouts.list_available_payment_methods("MH4H92C7")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->checkouts->listAvailablePaymentMethods('MH4H92C7');

1
client := sumup.NewClient()
2

3
result, err := client.Checkouts.ListAvailablePaymentMethods(context.Background(), "MH4H92C7")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.checkouts().list_available_payment_methods("MH4H92C7", sumup::GetPaymentMethodsParams{
6
    amount: Some(9.99),
7
    currency: Some("EUR".to_string()),
8
}).await;

Response
{
  "available_payment_methods": [
    {
      "id": "apple_pay"
    },
    {
      "id": "blik"
    }
  ]
}

Error 400

Content-Type: application/json

The request is invalid for the submitted query parameters.

titlestring
Short title of the error.

Example: "Bad Request"
detailsstring
Details of the error.

Example: "One or more of the parameters are invalid."
statusnumber
The status code.

Example: 400
failed_constraints[]object
List of violated validation constraints.
Show attributes
Close
Attributes
- messagestring
- referencestring

Error 400

1
{
2
  "failed_constraints": [
3
    {
4
      "message": "Currency must also be specified when filtering by amount",
5
      "reference": "currency"
6
    }
7
  ],
8
  "status": 400,
9
  "title": "Bad Request"
10
}

Checkouts

Create an Apple Pay session

PUT/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.

Path Parameters

checkout_idstringrequired
Unique ID of the checkout resource.

Body Parameters

contextstringrequiredformat: hostname
the context to create this apple pay session.

Example: "example.com"
targetstringrequiredformat: uri
The target url to create this apple pay session.

Example: "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"

Response

Successful request. Returns the Apple Pay merchant session object that should be forwarded to the Apple Pay JS SDK to complete merchant validation and continue the payment flow.

1
curl https://api.sumup.com/v0.2/checkouts/{checkout_id}/apple-pay-session \
2
 -X PUT \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{
5
    "context": "example.com",
6
    "target": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"
7
  }'

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.checkouts.createApplePaySession("checkout_id", {
6
  context: "example.com",
7
  target: "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
8
});

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Checkouts.CreateApplePaySessionAsync(
6
    "checkout_id",
7
    new CreateApplePaySessionBody
8
    {
9
        Context = "example.com",
10
        Target = "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
11
    }
12
);

1
import com.sumup.sdk.SumUpClient;
2

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

5
var result = client.checkouts().createApplePaySession(
6
  "checkout_id",
7
  CreateApplePaySessionBody.builder()
8
    .context("example.com")
9
    .target("https://apple-pay-gateway-cert.apple.com/paymentservices/startSession")
10
    .build()
11
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.checkouts.create_apple_pay_session("checkout_id", CreateApplePaySessionBody(
6
  context="example.com",
7
  target="https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
8
))

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->checkouts->createApplePaySession('checkout_id', [
4
  'context' => 'example.com',
5
  'target' => 'https://apple-pay-gateway-cert.apple.com/paymentservices/startSession',
6
]);

1
client := sumup.NewClient()
2

3
result, err := client.Checkouts.CreateApplePaySession(context.Background(), "checkout_id", sumup.CheckoutsCreateApplePaySessionParams{
4
  Context: "example.com",
5
  Target: "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
6
})

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.checkouts().create_apple_pay_session("checkout_id", sumup::CreateApplePaySessionBody{
6
  context: "example.com".to_string(),
7
  target: "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession".to_string(),
8
}).await;

1
{
2
  "displayName": "Test Account",
3
  "domainName": "pay.sumup.com",
4
  "epochTimestamp": 1775323532665,
5
  "expiresAt": 1775327132665,
6
  "merchantIdentifier": "7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB",
7
  "merchantSessionIdentifier": "SSH92CC412E5FCF4FAB88684914C953C0D4_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
8
  "nonce": "a968a2bf",
9
  "operationalAnalyticsIdentifier": "Test Account:7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB",
10
  "pspId": "7801D328E6637EFC1ADE6CE01C671D2CD318E32CA4ED1F9FC390D170D827D9AB",
11
  "retries": 0,
12
  "signature": "<apple-pay-signature>"
13
}

Error 400
Error 404

Content-Type: application/json

Bad Request

Content-Type: application/json

The requested resource does not exist.

messagestring
Short description of the error.

Example: "Resource not found"
error_codestring
Platform code for the error.

Example: "NOT_FOUND"

Error 400
Error 404

1
{
2
  "error_code": "INVALID",
3
  "message": "Bad Request"
4
}

1
{
2
  "error_code": "NOT_FOUND",
3
  "message": "Resource not found"
4
}