sumup_api_client library

Enterprise-ready SumUp REST API client for Dart and Flutter.

Provides OAuth2 token management, rate limiting, retry, pagination, and response caching on top of the generated SumUp API classes.

final client = SumUpClient.withOAuth2(
  clientId: 'xxx',
  clientSecret: 'xxx',
);
final checkout = await client.checkouts.createReaderCheckout(...);

Classes

Address
An address somewhere in the world. The address fields used depend on the country conventions. For example, in Great Britain, city is post_town. In the United States, the top-level administrative unit used in addresses is state, whereas in Chile it's region. Whether an address is valid or not depends on whether the locally required fields are present. Fields not supported in a country will be ignored.
AddressLegacy
Profile's personal address information.
ApiErrorInterceptor
ApiKeySecurity
Attributes
Object attributes that are modifiable only by SumUp applications.
AuthInterceptor
BadRequest
400 Bad Request
BadRequestErrors
Object model for BadRequestErrors from the SumUp API spec.
BasePerson
Base schema for a person associated with a merchant. This can be a legal representative, business owner (ultimate beneficial owner), or an officer. A legal representative is the person who registered the merchant with SumUp. They should always have a user_id.
Branding
Settings used to apply the Merchant's branding to email receipts, invoices, checkouts, and other products.
BusinessProfile
Business information about the merchant. This information will be visible to the merchant's customers.
Card
Required when payment type is card. Details of the payment card.
CardResponse
Details of the payment card.
Checkout
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.
CheckoutAccepted
Response returned when checkout processing requires an additional payer action, such as a 3DS challenge or a redirect to an external payment method page.
CheckoutAcceptedNextStep
Instructions for the next action the payer or client must take.
CheckoutAcceptedNextStepPayload
Parameters required to complete the next step. The exact keys depend on the payment provider and flow type.
CheckoutCreateRequest
Request body for creating a checkout before processing payment. Define the payment amount, currency, merchant, and optional customer or redirect behavior here.
CheckoutsApi
CheckoutSuccess
Checkout resource returned after a synchronous processing attempt. In addition to the base checkout fields, it can include the resulting transaction identifiers and any newly created payment instrument token.
CheckoutSuccessInline1
Object model for CheckoutSuccessInline1 from the SumUp API spec.
CheckoutSuccessInline1PaymentInstrument
Details of the saved payment instrument created or reused during checkout processing.
CheckoutTransactionsItem
Object model for CheckoutTransactionsItem from the SumUp API spec.
ClassicMerchantIdentifiers
Object model for ClassicMerchantIdentifiers from the SumUp API spec.
Company
Information about the company or business. This is legal information that is used for verification.
CompanyIdentifier
Object model for CompanyIdentifier from the SumUp API spec.
CreateApplePaySessionBodyApplicationJson
Object model for CreateApplePaySessionBodyApplicationJson from the SumUp API spec.
CreateApplePaySessionResult
CreateApplePaySessionResultError
CreateApplePaySessionResultHttp200
CreateApplePaySessionResultHttp400
CreateApplePaySessionResultHttp404
CreateCheckoutResult
CreateCheckoutResultError
CreateCheckoutResultHttp201
CreateCheckoutResultHttp400
CreateCheckoutResultHttp401
CreateCheckoutResultHttp403
CreateCheckoutResultHttp409
CreateCustomerResult
CreateCustomerResultError
CreateCustomerResultHttp201
CreateCustomerResultHttp400
CreateCustomerResultHttp401
CreateCustomerResultHttp403
CreateCustomerResultHttp409
CreateMerchantMemberBodyApplicationJson
Object model for CreateMerchantMemberBodyApplicationJson from the SumUp API spec.
CreateMerchantMemberResult
CreateMerchantMemberResultError
CreateMerchantMemberResultHttp201
CreateMerchantMemberResultHttp400
CreateMerchantMemberResultHttp404
CreateMerchantMemberResultHttp429
CreateMerchantRoleBodyApplicationJson
Object model for CreateMerchantRoleBodyApplicationJson from the SumUp API spec.
CreateMerchantRoleResult
CreateMerchantRoleResultError
CreateMerchantRoleResultHttp201
CreateMerchantRoleResultHttp400
CreateMerchantRoleResultHttp404
CreateReaderBodyApplicationJson
Object model for CreateReaderBodyApplicationJson from the SumUp API spec.
CreateReaderCheckoutError
Error description
CreateReaderCheckoutErrorErrors
Object model for CreateReaderCheckoutErrorErrors from the SumUp API spec.
CreateReaderCheckoutRequest
Reader Checkout
CreateReaderCheckoutRequestAade
Optional object containing data for transactions from ERP integrators in Greece that comply with the AADE 1155 protocol. When such regulatory/business requirements apply, this object must be provided and contains the data needed to validate the transaction with the AADE signature provider.
CreateReaderCheckoutRequestAffiliate
Affiliate metadata for the transaction. It is a field that allow for integrators to track the source of the transaction.
CreateReaderCheckoutRequestAffiliateTags
Additional metadata for the transaction. It is key-value object that can be associated with the transaction.
CreateReaderCheckoutRequestTotalAmount
Amount structure.
CreateReaderCheckoutResponse
Object model for CreateReaderCheckoutResponse from the SumUp API spec.
CreateReaderCheckoutResponseData
Object model for CreateReaderCheckoutResponseData from the SumUp API spec.
CreateReaderCheckoutResult
CreateReaderCheckoutResultError
CreateReaderCheckoutResultHttp201
CreateReaderCheckoutResultHttp400
CreateReaderCheckoutResultHttp401
CreateReaderCheckoutResultHttp404
CreateReaderCheckoutResultHttp422
CreateReaderCheckoutUnprocessableEntity
Unprocessable entity
CreateReaderCheckoutUnprocessableEntityErrors
Object model for CreateReaderCheckoutUnprocessableEntityErrors from the SumUp API spec.
CreateReaderResult
CreateReaderResultError
CreateReaderResultHttp201
CreateReaderResultHttp400
CreateReaderResultHttp404
CreateReaderResultHttp409
CreateReaderTerminateError
Error description
CreateReaderTerminateErrorErrors
Object model for CreateReaderTerminateErrorErrors from the SumUp API spec.
CreateReaderTerminateResult
CreateReaderTerminateResultError
CreateReaderTerminateResultHttp202
CreateReaderTerminateResultHttp400
CreateReaderTerminateResultHttp401
CreateReaderTerminateResultHttp404
CreateReaderTerminateResultHttp422
CreateReaderTerminateUnprocessableEntity
Unprocessable entity
CreateReaderTerminateUnprocessableEntityErrors
Object model for CreateReaderTerminateUnprocessableEntityErrors from the SumUp API spec.
CursorPage<T>
CursorPaginatedResponse<T, C>
CursorPaginator<T>
Helper for cursor-based paginated SumUp APIs.
Customer
Saved customer details.
CustomersApi
DeactivateCheckoutResult
DeactivateCheckoutResultError
DeactivateCheckoutResultHttp200
DeactivateCheckoutResultHttp401
DeactivateCheckoutResultHttp404
DeactivateCheckoutResultHttp409
DeactivatePaymentInstrumentResult
DeactivatePaymentInstrumentResultError
DeactivatePaymentInstrumentResultHttp204
DeactivatePaymentInstrumentResultHttp400
DeactivatePaymentInstrumentResultHttp401
DeactivatePaymentInstrumentResultHttp403
DeactivatePaymentInstrumentResultHttp404
DeleteMerchantMemberResult
DeleteMerchantMemberResultError
DeleteMerchantMemberResultHttp200
DeleteMerchantMemberResultHttp404
DeleteMerchantRoleResult
DeleteMerchantRoleResultError
DeleteMerchantRoleResultHttp200
DeleteMerchantRoleResultHttp400
DeleteMerchantRoleResultHttp404
DeleteReaderResult
DeleteReaderResultError
DeleteReaderResultHttp200
DeleteReaderResultHttp404
DetailsError
Error message structure.
DetailsErrorFailedConstraintsItem
Object model for DetailsErrorFailedConstraintsItem from the SumUp API spec.
Device
Details of the device used to create the transaction.
ElvCardAccount
Details of the ELV card account associated with the transaction.
Error
Error message structure.
ErrorExtended
Error payload with the invalid parameter reference.
ErrorExtendedInline1
Object model for ErrorExtendedInline1 from the SumUp API spec.
ErrorForbidden
Error message for forbidden requests.
Event
High-level transaction event details.
FinancialPayout
A single payout-related record.
Get200Response
Object model for Get200Response from the SumUp API spec.
Get200ResponseAvailablePaymentMethodsItem
Object model for Get200ResponseAvailablePaymentMethodsItem from the SumUp API spec.
GetCheckoutResult
GetCheckoutResultError
GetCheckoutResultHttp200
GetCheckoutResultHttp401
GetCheckoutResultHttp404
GetCustomerResult
GetCustomerResultError
GetCustomerResultHttp200
GetCustomerResultHttp401
GetCustomerResultHttp403
GetCustomerResultHttp404
GetMerchantMemberResult
GetMerchantMemberResultError
GetMerchantMemberResultHttp200
GetMerchantMemberResultHttp404
GetMerchantResult
GetMerchantResultError
GetMerchantResultHttp200
GetMerchantResultHttp404
GetMerchantRoleResult
GetMerchantRoleResultError
GetMerchantRoleResultHttp200
GetMerchantRoleResultHttp404
GetPaymentMethodsResult
GetPaymentMethodsResultError
GetPaymentMethodsResultHttp200
GetPaymentMethodsResultHttp400
GetPersonResult
GetPersonResultError
GetPersonResultHttp200
GetPersonResultHttp404
GetReaderResult
GetReaderResultError
GetReaderResultHttp200
GetReaderResultHttp404
GetReaderStatusResult
GetReaderStatusResultError
GetReaderStatusResultHttp200
GetReaderStatusResultHttp400
GetReaderStatusResultHttp401
GetReaderStatusResultHttp404
GetReceiptResult
GetReceiptResultError
GetReceiptResultHttp200
GetReceiptResultHttp400
GetReceiptResultHttp401
GetReceiptResultHttp404
GetTransactionV21Result
GetTransactionV21ResultError
GetTransactionV21ResultHttp200
GetTransactionV21ResultHttp401
GetTransactionV21ResultHttp404
HostedCheckout
Hosted Checkout configuration. Enable it to receive a SumUp-hosted payment page URL in the checkout response.
IfModifiedSince
IfModifiedSinceVariant0
Sealed variant for IfModifiedSinceVariant0 in IfModifiedSince.
IfModifiedSinceVariant1
Sealed variant for IfModifiedSinceVariant1 in IfModifiedSince.
Invite
Pending invitation for membership.
Details of a link to a related resource.
ListCheckoutsResult
ListCheckoutsResultError
ListCheckoutsResultHttp200
ListCheckoutsResultHttp401
ListMembershipsResult
ListMembershipsResultError
ListMembershipsResultHttp200
ListMembershipsResultHttp400
ListMembershipsResultHttp401
ListMerchantMembersResult
ListMerchantMembersResultError
ListMerchantMembersResultHttp200
ListMerchantMembersResultHttp404
ListMerchantRolesResult
ListMerchantRolesResultError
ListMerchantRolesResultHttp200
ListMerchantRolesResultHttp404
ListPaymentInstrumentsResult
ListPaymentInstrumentsResultError
ListPaymentInstrumentsResultHttp200
ListPaymentInstrumentsResultHttp401
ListPaymentInstrumentsResultHttp403
ListPaymentInstrumentsResultHttp404
ListPayoutsV1Result
ListPayoutsV1ResultError
ListPayoutsV1ResultHttp200
ListPayoutsV1ResultHttp400
ListPayoutsV1ResultHttp401
ListPersonsResponseBody
Object model for ListPersonsResponseBody from the SumUp API spec.
ListPersonsResult
ListPersonsResultError
ListPersonsResultHttp200
ListPersonsResultHttp404
ListReadersResult
ListReadersResultError
ListReadersResultHttp200
ListReadersResultHttp401
ListTransactionsV21Result
ListTransactionsV21ResultError
ListTransactionsV21ResultHttp200
ListTransactionsV21ResultHttp400
ListTransactionsV21ResultHttp401
LoggingInterceptor
MandatePayload
Mandate details used when a checkout should create a reusable card token for future recurring or merchant-initiated payments.
MandateResponse
Details of the mandate linked to the saved payment instrument.
Member
A member is user within specific resource identified by resource id, resource type, and associated roles.
MembersApi
Membership
A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.
MembershipResource
Information about the resource the membership is in.
MembershipsApi
MembershipUser
Information about the user associated with the membership.
MembershipUserClassic
Classic identifiers of the user.
MemoryTokenStorage
In-memory TokenStorage implementation.
Merchant
Object model for Merchant from the SumUp API spec.
MerchantInline0
Object model for MerchantInline0 from the SumUp API spec.
MerchantsApi
Meta
A set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
Metadata
Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.
NotFound
404 Not Found
NotFoundErrors
Object model for NotFoundErrors from the SumUp API spec.
OAuth2Manager
Oauth2Security
OffsetPaginatedResponse<T>
Ownership
Object model for Ownership from the SumUp API spec.
PaginatedResponse<T>
PaymentInstrumentResponse
Payment Instrument Response
PaymentInstrumentResponseCard
Details of the payment card.
PayoutsApi
Person
Object model for Person from the SumUp API spec.
PersonalDetails
Personal details for the customer.
PersonalIdentifier
Object model for PersonalIdentifier from the SumUp API spec.
Post400Response
Post400Response1
Object model for Post400Response1 from the SumUp API spec.
Post400ResponseErrorExtendedVariant0
Sealed variant for Post400ResponseErrorExtendedVariant0 in Post400Response.
Post400ResponseVariant1
Sealed variant for Post400ResponseVariant1 in Post400Response.
Problem
A RFC 9457 problem details object.
ProcessCheckout
Request body for attempting payment on an existing checkout. The required companion fields depend on the selected payment_type, for example card details, saved-card data, or payer information required by a specific payment method.
ProcessCheckoutApplePay
Raw payment token object received from Apple Pay. Send the Apple Pay response payload as-is.
ProcessCheckoutGooglePay
Raw PaymentData object received from Google Pay. Send the Google Pay response payload as-is.
ProcessCheckoutResult
ProcessCheckoutResultError
ProcessCheckoutResultHttp200
ProcessCheckoutResultHttp202
ProcessCheckoutResultHttp400
ProcessCheckoutResultHttp401
ProcessCheckoutResultHttp404
ProcessCheckoutResultHttp409
Product
Purchase product.
Put200Response
Object model for Put200Response from the SumUp API spec.
Put400Response
Put400ResponseErrorExtendedVariant0
Sealed variant for Put400ResponseErrorExtendedVariant0 in Put400Response.
Put400ResponseVariant1
Sealed variant for Put400ResponseVariant1 in Put400Response.
Reader
A physical card reader device that can accept in-person payments.
ReaderCheckoutStatusChange
The callback payload containing the status change of the Reader Checkout.
ReaderCheckoutStatusChangePayload
The event payload.
ReaderDevice
Information about the underlying physical device.
ReadersApi
Receipt
Receipt details for a transaction.
ReceiptAcquirerData
Acquirer-specific metadata related to the card authorization.
ReceiptCard
Payment card details displayed on the receipt.
ReceiptEmvData
EMV-specific metadata returned for card-present payments.
ReceiptEvent
Transaction event details as rendered on the receipt.
ReceiptMerchantData
Receipt merchant data
ReceiptMerchantDataMerchantProfile
Merchant profile details displayed on the receipt.
ReceiptMerchantDataMerchantProfileAddress
Object model for ReceiptMerchantDataMerchantProfileAddress from the SumUp API spec.
ReceiptReader
Card reader details displayed on the receipt.
ReceiptsApi
ReceiptTransaction
Transaction information.
ReceiptTransactionProductsItem
Object model for ReceiptTransactionProductsItem from the SumUp API spec.
ReceiptTransactionVatRatesItem
Object model for ReceiptTransactionVatRatesItem from the SumUp API spec.
RefundTransactionBodyApplicationJson
Optional amount for partial refunds of transactions.
RefundTransactionResult
RefundTransactionResultError
RefundTransactionResultHttp204
RefundTransactionResultHttp404
RefundTransactionResultHttp409
ResourceParentType
Object model for ResourceParentType from the SumUp API spec.
RetryInterceptor
Role
A custom role that can be used to assign set of permissions to members.
RolesApi
StatusResponse
Status of a device
StatusResponseData
Object model for StatusResponseData from the SumUp API spec.
SumUpClient
Enterprise-ready SumUp REST API client.
Timestamps
Object model for Timestamps from the SumUp API spec.
Token
TokenStorage
TransactionBase
Details of the transaction.
TransactionCheckoutInfo
Checkout-specific fields associated with a transaction.
TransactionEvent
Detailed information about a transaction event.
TransactionFull
Full transaction resource with checkout, payout, and event details.
TransactionFullInline3
Object model for TransactionFullInline3 from the SumUp API spec.
TransactionFullInline3Location
Details of the payment location as received from the payment terminal.
TransactionFullInline3VatRatesItem
Object model for TransactionFullInline3VatRatesItem from the SumUp API spec.
TransactionHistory
Transaction entry returned in history listing responses.
TransactionHistoryInline2
Object model for TransactionHistoryInline2 from the SumUp API spec.
TransactionMixinHistory
Additional transaction fields used by history and detailed views.
TransactionsApi
Hypermedia link used for transaction history pagination.
Unauthorized
401 Unauthorized
UnauthorizedErrors
Object model for UnauthorizedErrors from the SumUp API spec.
UpdateCustomerBodyApplicationJson
Object model for UpdateCustomerBodyApplicationJson from the SumUp API spec.
UpdateCustomerResult
UpdateCustomerResultError
UpdateCustomerResultHttp200
UpdateCustomerResultHttp401
UpdateCustomerResultHttp403
UpdateCustomerResultHttp404
UpdateMerchantMemberBodyApplicationJson
Object model for UpdateMerchantMemberBodyApplicationJson from the SumUp API spec.
UpdateMerchantMemberBodyApplicationJsonUser
Allows you to update user data of managed users.
UpdateMerchantMemberResult
UpdateMerchantMemberResultError
UpdateMerchantMemberResultHttp200
UpdateMerchantMemberResultHttp400
UpdateMerchantMemberResultHttp403
UpdateMerchantMemberResultHttp404
UpdateMerchantMemberResultHttp409
UpdateMerchantRoleBodyApplicationJson
Object model for UpdateMerchantRoleBodyApplicationJson from the SumUp API spec.
UpdateMerchantRoleResult
UpdateMerchantRoleResultError
UpdateMerchantRoleResultHttp200
UpdateMerchantRoleResultHttp400
UpdateMerchantRoleResultHttp404
UpdateReaderBodyApplicationJson
Object model for UpdateReaderBodyApplicationJson from the SumUp API spec.
UpdateReaderResult
UpdateReaderResultError
UpdateReaderResultHttp200
UpdateReaderResultHttp403
UpdateReaderResultHttp404

Enums

BadRequestErrorsType
Key indicating type of error
CardExpiryMonth
Month from the expiration time of the payment card. Accepted format is MM.
CardType
Issuing card network of the payment card used for the transaction.
CheckoutAcceptedNextStepMechanismItem
Enum for CheckoutAcceptedNextStepMechanismItem from the SumUp API spec.
CheckoutCreateRequestPurpose
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.
CheckoutStatus
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.
CreateReaderCheckoutRequestCardType
The card type of the card used for the transaction. Is is required only for some countries (e.g: Brazil).
Currency
Three-letter ISO4217 code of the currency for the amount. Currently supported currency values are enumerated above.
EntryMode
Entry mode of the payment details.
EventStatus
Status of the transaction event.
EventType
Type of the transaction event.
FinancialPayoutStatus
Merchant-facing outcome of the payout record.
FinancialPayoutType
High-level payout record category.
Format
Enum for Format from the SumUp API spec.
MandatePayloadType
Type of mandate to create for the saved payment instrument.
MandateResponseStatus
Current lifecycle status of the mandate.
MembershipStatus
The status of the membership.
Order
Enum for Order from the SumUp API spec.
PaymentInstrumentResponseType
Type of the payment instrument.
PaymentType
Payment type used for the transaction.
ProcessCheckoutPaymentType
Payment method used for this processing attempt. It determines which additional request fields are required.
ReaderCheckoutStatusChangePayloadStatus
The current status of the transaction.
ReaderDeviceModel
Identifier of the model of the device.
ReaderStatus
The status of the reader object gives information about the current state of the reader.
ReceiptTransactionProcessAs
Debit/Credit.
StatusesItem
Enum for StatusesItem from the SumUp API spec.
StatusResponseDataConnectionType
Type of connection used by the device
StatusResponseDataState
Latest state of the device
StatusResponseDataStatus
Status of a device
TransactionBaseStatus
Current status of the transaction.
TransactionFullInline3PayoutType
Payout type for the transaction.
TransactionFullInline3ProcessAs
Debit/Credit.
TransactionFullInline3SimplePaymentType
Simple name of the payment type.
TransactionFullInline3SimpleStatus
High-level status of the transaction from the merchant's perspective.
TransactionFullInline3VerificationMethod
Verification method used for the transaction.
TransactionHistoryInline2PayoutType
Payout type.
TransactionHistoryInline2Type
Type of the transaction for the registered user specified in the user property.
TransactionMixinHistoryPayoutPlan
Payout plan of the registered user at the time when the transaction was made.
TypesItem
Enum for TypesItem from the SumUp API spec.
UnauthorizedErrorsType
Key indicating type of error. Present only for typed 401 responses (e.g. invalid token, invalid password). Absent for generic unauthorized responses.

Typedefs

AnyStatusCodeCallback = void Function(int statusCode, Response response)
ChangeStatus = String
Named type for ChangeStatus from the SumUp API spec.
CompanyIdentifiers = List<CompanyIdentifier>
List wrapper for CompanyIdentifiers from the SumUp API spec.
CountryCode = String
Named type for CountryCode from the SumUp API spec.
EventID = int
Named type for EventID from the SumUp API spec.
FinancialPayouts = List<FinancialPayout>
List wrapper for FinancialPayouts from the SumUp API spec.
HorizontalAccuracy = double
Named type for HorizontalAccuracy from the SumUp API spec.
IfModifiedSince0 = String
Named type for IfModifiedSince0 from the SumUp API spec.
IfModifiedSince1 = DateTime
Named type for IfModifiedSince1 from the SumUp API spec.
Lat = double
Named type for Lat from the SumUp API spec.
LegalType = String
Named type for LegalType from the SumUp API spec.
Lon = double
Named type for Lon from the SumUp API spec.
PhoneNumber = String
Named type for PhoneNumber from the SumUp API spec.
Put400Response1 = List<ErrorExtended>
List wrapper for Put400Response1 from the SumUp API spec.
ReaderID = String
Named type for ReaderID from the SumUp API spec.
ReaderName = String
Named type for ReaderName from the SumUp API spec.
ReaderPairingCode = String
Named type for ReaderPairingCode from the SumUp API spec.
ResourceType = String
Named type for ResourceType from the SumUp API spec.
StatusCodeCallback = void Function(Response response)
TransactionID = String
Named type for TransactionID from the SumUp API spec.
Version = String
Named type for Version from the SumUp API spec.

Exceptions / Errors

TokenException