SumUp REST API

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

Use this tag to:

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

Typical workflow:

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

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

Objects:

• Checkout

Customers represent payers in your integration. Create a customer with your own customer_id to associate their personal details and saved payment instruments with your business records.

To save a card, create a checkout for that customer with purpose = SETUP_RECURRING_PAYMENT, then process it with the payer's consent and mandate details. See the tokenization guide.

Use the Customers endpoints to create, retrieve, or update customer details and to list or deactivate saved payment instruments. For subsequent payments, process a new checkout with the saved instrument's token and its associated customer_id.

Objects:

• Customer

Transactions represent completed or attempted payment operations processed for a merchant account. A transaction contains the core payment result, such as the amount, currency, payment method, creation time, and current high-level status.

In addition to the main payment outcome, a transaction can contain related events that describe what happened after the original payment attempt. These events provide visibility into the financial lifecycle of the transaction, for example:

• PAYOUT: the payment being prepared for payout or included in a payout to the merchant
• REFUND: money returned to the payer
• CHARGE_BACK: money reversed after the original payment
• PAYOUT_DEDUCTION: an amount deducted from a payout to cover a refund or chargeback

From an integrator's perspective, transactions are the authoritative record of payment outcomes. Use this tag to:

• list transactions for reporting, reconciliation, and customer support workflows
• retrieve a single transaction when you need the latest payment details
• inspect simple_status for the current merchant-facing outcome of the payment
• inspect events or transaction_events when you need refund, payout, or chargeback history

Typical workflow:

• create and process payments through the Checkouts endpoints
• use the Transactions endpoints to read the resulting payment records
• use the returned statuses and events to update your own order, accounting, or support systems

The Payouts model will allow you to track funds you’ve received from SumUp.

You can receive a detailed payouts list with information like dates, fees, references and statuses, using the List payouts endpoint.

Objects:

• FinancialPayouts

Retrieve structured receipt data for a transaction, including payment, merchant, and acquirer details. Use this data to display a receipt in your application. The response is JSON, rather than a rendered receipt document.

Objects:

• Receipt

A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.

Objects:

• Reader

Endpoints to manage account members. Members are users that have membership within merchant accounts.

Beta.

Objects:

• Member

Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.

Beta.

Objects:

• Membership

Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.

Beta.

Objects:

• Role

A Merchant represents a single business which can use SumUp products like payment processing.

Objects:

• Merchant

Operations related to reading sales data.

Objects:

• Sale
• PublicPaymentV10

Merchant tokens let your application accept card-present payments with SumUp SDKs that support token-based authentication. Use them when you want users to sign in to your application with your own authentication, then accept payments for a SumUp merchant account.

Create tokens on your backend using one of the supported authentication methods. Keep your authentication credentials on your backend. Return only the short-lived merchant token to your application and pass its access_token to the SDK.

Before returning a token, authenticate the user in your application and check that they can accept payments for the requested merchant account. A merchant token is limited to that account and the requested actions, and does not grant permissions beyond those of the identity that created it.

Tokens expire 15 minutes after creation. Use expires_in to determine the remaining lifetime and create a new token when needed. This endpoint does not return a refresh token. Treat merchant tokens as secrets: send them over HTTPS and keep them out of URLs, logs, and source code.

Objects:

• Token