/v0.1/checkouts/{checkout_id}PCI DSS compliance required
When you submit raw card details directly to the Checkout API, your systems store, process, or transmit cardholder data and are therefore subject to applicable PCI DSS requirements. You should only use this integration if your environment is appropriately PCI DSS compliant.
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.
A processing response can require an additional payer action, such as a 3DS challenge or a payment-provider redirect. If next_step is returned, follow its instructions to continue the payment flow.
Retrieve the checkout afterwards to confirm its payment status. Acceptance of the processing request does not by itself mean the checkout is paid.
OAuth scopes: Requires one of: payments, checkouts.write.
Path parameters
SumUp-generated
idreturned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.Example:
"4e425463-3e1b-431d-83fa-1e51c2925e99"
Body parameters
application/jsonrequiredDetails of the payment instrument for processing the checkout.
- Options:
"card""boleto""ideal""blik""bancontact""google_pay""apple_pay"Payment method used for this processing attempt. It determines which additional request fields are required.
Example:
"card" - installmentsintegerminimum:
1maximum:12Number of installments for deferred payments. Available only to merchant users in Brazil.
Example:
1 - mandateobject
Mandate details used when a checkout should create a reusable card token for future recurring or merchant-initiated payments.
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"}Show 3 properties
- Options:
"recurrent"Type of mandate to create for the saved payment instrument.
Example:
"recurrent" 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"
- cardobject
Required when payment type is
card. Details of the payment card.Show 7 properties
Name of the cardholder as it appears on the payment card.
Example:
"FIRSTNAME LASTNAME"Number of the payment card (without spaces).
Example:
"1234567890123456"- pattern:
^[0-9]{2}([0-9]{2})?$Two- or four-digit expiration year in
YYorYYYYformat.Example:
"2030" - minLength:
2maxLength:2pattern:^(0[1-9]|1[0-2])$Two-digit expiration month, from
01through12.Example:
"12" - minLength:
3maxLength:4Three or four-digit card verification value (security code) of the payment card.
Example:
"123" - Options:
"ALELO""AMEX""BANCOMAT""CONECS""CUP""DINERS""DISCOVER""EFTPOS""ELO""ELV""GIROCARD""HIPERCARD""INTERAC""JCB""MAESTRO""MASTERCARD""PLUXEE""SUMUP""SWILE""TICKET""VISA""VISA_ELECTRON""VISA_VPAY""VPAY""VR""UNKNOWN"Issuing card network of the payment card used for the transaction.
Example:
"VISA" - zip_codestringminLength:
5maxLength:5Required five-digit ZIP code. Applicable only to merchant users in the USA.
Example:
"12345"
- google_payobject
Raw
PaymentDataobject 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
Token of a saved payment instrument returned by checkout processing or the customer's payment-instruments endpoint. To charge a saved card, set
payment_typetocardand provide both thistokenand the associatedcustomer_idinstead of raw card details.Example:
"ba85dfee-c3cf-48a6-84f5-d7d761fbba50" - customer_idstring
Customer identifier associated with the saved payment instrument. Required when
tokenis provided.Example:
"MEDKHDTI" - personal_detailsobject
Personal details for the customer.
Show 7 properties
- 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:
dateDate of birth of the customer in
YYYY-MM-DDformat, without a time or timezone.Example:
"1993-12-31" - tax_idstringmaxLength:
255Identification number used for tax purposes, such as a CPF in Brazil.
Example:
"423.378.593-47" - addressobject
Profile's personal address information.
Show 6 properties
- 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"
Request examples
Process a checkout with a card
ProcessCard
{
"payment_type": "card",
"installments": 1,
"mandate": {
"type": "recurrent",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.104 Safari/537.36",
"user_ip": "172.217.169.174"
},
"card": {
"type": "VISA",
"name": "John Doe",
"number": "1234567890123456",
"expiry_year": "2023",
"expiry_month": "01",
"cvv": "123",
"zip_code": "12345"
}
}Process a checkout with a token
ProcessToken
{
"payment_type": "card",
"installments": 1,
"token": "ba85dfee-c3cf-48a6-84f5-d7d761fbba50",
"customer_id": "MEDKHDTI"
}Process a checkout with Boleto
ProcessBoleto
{
"payment_type": "boleto",
"personal_details": {
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"tax_id": "423.378.593-47",
"address": {
"country": "BR",
"city": "São Paulo",
"line1": "Rua Gilberto Sabino, 215",
"state": "SP",
"postal_code": "05425-020"
}
}
}Process a checkout with iDeal
ProcessiDeal
{
"payment_type": "ideal",
"personal_details": {
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"address": {
"country": "NL"
}
}
}Process a checkout with Bancontact
ProcessBancontact
{
"payment_type": "bancontact",
"personal_details": {
"email": "user@example.com",
"first_name": "John",
"last_name": "Doe",
"address": {
"country": "BE"
}
}
}Responses
200application/json
Returns the checkout resource after a processing attempt.
- checkout_referencestringmaxLength:
64Merchant-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" - amountnumberformat:
floatAmount to be charged to the payer, expressed in major units.
Example:
10.1 - currencystringOptions:
"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"Three-letter ISO 4217 currency code of the amount.
Example:
"EUR" - merchant_codestring
Short unique identifier for the merchant that receives the payment.
Example:
"MH4H92C7" - descriptionstring
Short merchant-defined description shown in SumUp tools and reporting. Use it to make the checkout easier to recognize in dashboards, support workflows, and reconciliation.
Example:
"Purchase" - return_urlstringformat:
uriOptional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with
event_typeand the checkoutid. Retrieve the checkout to verify its current status before updating your order. See the webhook guide for the payload and response requirements.Example:
"http://example.com" - idstring
Unique SumUp identifier of the checkout resource.
Example:
"4e425463-3e1b-431d-83fa-1e51c2925e99" - statusstringOptions:
"PENDING""FAILED""PAID""EXPIRED"Current high-level state of the checkout.
PENDINGmeans the checkout exists but is not yet completed,PAIDmeans a payment succeeded,FAILEDmeans the latest processing attempt failed, andEXPIREDmeans the checkout can no longer be processed.Example:
"PENDING" - datestringformat:
date-timeThe timestamp of when the checkout was created.
Example:
"2020-02-29T10:56:56+00:00" - format:
date-timeOptional expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable. If omitted, the checkout does not have an explicit expiry time.
Example:
"2030-12-31T23:59:59Z" - customer_idstring
Merchant-scoped identifier of the customer associated with the checkout. Use it when storing payment instruments or reusing saved customer context for recurring and returning-payer flows.
Example:
"831ff8d4cd5958ab5670" - mandateobject
Details of the mandate linked to the saved payment instrument.
Example:
{"type":"recurrent","status":"active","merchant_code":"MH4H92C7"}Show 3 properties
- typestring
Type of mandate stored for the checkout or payment instrument.
Example:
"recurrent" - statusstringOptions:
"active""inactive"Current lifecycle status of the mandate.
Example:
"active" - merchant_codestring
Short unique identifier for the merchant for which the mandate is valid.
Example:
"MH4H92C7"
- hosted_checkout_urlstringformat:
uriURL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout.
Example:
"https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676" - transactionsarray<unknown>
Payment attempts and resulting transaction records linked to this checkout. Use the Transactions endpoints when you need the authoritative payment result and event history.
Example:
[{"id":"410fc44a-5956-44e1-b5cc-19c6f8d727a4","transaction_code":"TEENSK4W2K","amount":10.1,"currency":"EUR","timestamp":"2020-02-29T10:56:56.876Z","status":"SUCCESSFUL","payment_type":"ECOM","installments_count":1,"merchant_code":"MH4H92C7","vat_amount":6,"tip_amount":3,"entry_mode":"CUSTOMER_ENTRY","auth_code":"012345"}]Show 13 properties
- idstring
Unique identifier of the transaction.
Example:
"6b425463-3e1b-431d-83fa-1e51c2925e99" - transaction_codestring
SumUp transaction code, for example
TEENSK4W2K. Use it to look up the transaction with thetransaction_codequery parameter. This is separate from the transaction'sidand the card issuer'sauth_code.Example:
"TEENSK4W2K" - amountnumberformat:
floatTotal amount of the transaction in major units of
currency, for example10.1for EUR 10.10.Example:
10.1 - currencystringOptions:
"BRL""CHF""CLP""COP""CZK""DKK""EUR""GBP""HRK""HUF""NOK""PLN""RON""SEK""USD"Three-letter ISO 4217 currency code of the amount.
Example:
"EUR" - timestampstringformat:
date-timeThe timestamp of when the transaction was created.
Example:
"2020-02-29T10:56:56.876Z" - statusstringOptions:
"SUCCESSFUL""CANCELLED""FAILED""PENDING""REFUNDED"Current status of the transaction.
PENDING: The transaction has been created but its final outcome is not known yet.SUCCESSFUL: The transaction completed successfully.CANCELLED: The transaction was cancelled or otherwise reversed before completion.FAILED: The transaction attempt did not complete successfully.REFUNDED: The transaction was refunded in full or in part.
Example:
"SUCCESSFUL" - payment_typestringOptions:
"CASH""POS""ECOM""RECURRING""BITCOIN""BALANCE""MOTO""BOLETO""DIRECT_DEBIT""APM""UNKNOWN"Payment category recorded on a transaction, for example
POSfor a point-of-sale card payment,ECOMfor an online card payment, orRECURRINGfor a recurring card payment. These reporting values are separate from the lowercasepayment_typevalues used to process checkouts.Example:
"ECOM" - installments_countintegerminimum:
1Number of installments for a deferred payment.
Example:
1 - merchant_codestring
Unique code of the registered merchant to whom the payment is made.
Example:
"MH4H92C7" - vat_amountnumberformat:
floatVAT included in the total transaction amount, in major units of the transaction's currency.
Example:
6 - tip_amountnumberformat:
floatTip included in the total transaction amount, in major units of the transaction's currency.
Example:
3 - entry_modestringOptions:
"BOLETO""SOFORT""IDEAL""BANCONTACT""EPS""MYBANK""SATISPAY""BLIK""P24""GIROPAY""PIX""QR_CODE_PIX""APPLE_PAY""GOOGLE_PAY""PAYPAL""TWINT""NONE""CHIP""MANUAL_ENTRY""CUSTOMER_ENTRY""MAGSTRIPE_FALLBACK""MAGSTRIPE""DIRECT_DEBIT""CONTACTLESS""MOTO""CONTACTLESS_MAGSTRIPE""N/A"How the payment details were captured, for example
CHIPorCONTACTLESSfor card-present payments andCUSTOMER_ENTRYfor card details entered by the payer. For wallet and alternative payment methods, this can identify the method, such asAPPLE_PAYorBLIK.Example:
"CUSTOMER_ENTRY" - auth_codestring
Authorization code for the transaction sent by the payment card issuer or bank. Applicable only to card payments.
Example:
"053201"
- transaction_codestring
Transaction code of the successful transaction with which the payment for the checkout is completed.
Example:
"TEENSK4W2K" - transaction_idstring
Unique identifier of the successful transaction that completed payment for the checkout.
Example:
"410fc44a-5956-44e1-b5cc-19c6f8d727a4" - merchant_namestring
Name of the merchant.
Example:
"Sample Merchant" - redirect_urlstring
URL where the payer is redirected after a redirect-based payment or SCA flow completes.
Example:
"https://mysite.com/completed_purchase" - payment_instrumentobject
Details of the saved payment instrument created or reused during checkout processing.
Show 1 property
- tokenstring
Unique token of the saved payment instrument.
Example:
"e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
202application/json
Returns the next required action for asynchronous checkout processing.
- next_stepobject
Instructions for the next action the payer or client must take.
Show 5 properties
- urlstring
URL to open or submit in order to continue processing.
Example:
"https://dummy-3ds-gateway.com/cap?RID=1233&VAA=A" - methodstring
HTTP method to use when following the next step.
Example:
"POST" - redirect_urlstring
Merchant URL where the payer returns after the external flow finishes.
Example:
"https://mysite.com/completed_purchase" - mechanismarray<string>Options:
"iframe""browser"Allowed presentation mechanisms for the next step.
iframemeans the flow can be embedded, whilebrowsermeans it can be completed through a full-page redirect.Example:
["iframe"] - payloadmap<string>
Parameters required to complete the next step. The exact keys depend on the payment provider and flow type.
Example:
{"PaReq":"eJxVUttu2zAM/RXDr4MjyY5dO6BVuE27FZuDZHGG9VGRmMSFb/Wljff1k9KkF0APPCR1eHQouD6WhfWCbZfXVWyzCbUtrGSt8mof25vs3gltq+tFpURRVxjbI3b2NYfs0CLO1yiHFjmk2HVij1auYrsRW1+F0U4qZxfKwJlur4QTYcQcJoIdc+XO2/poc1gmv/GZw3k216MnLpAL1JytPIiq5yDk883Dgk+DwPV9IGcIJbYPc84o1Ye6lHqu5wVA3tJQiRL5eiiHxlqKscSq76xfeZn3qICciiDroerbkYeuvnYBMLQFP/R9MyOkM9cnCoGYJJAPScvBRJ0mOeaKr/6l08XT6jXN7tx0vvHSbOMtsj1dzB9jIKYDlOiRu1omYyy0WDCj0YxFQE55EKWZzj2f6ee9xdCYEcmnwucEaN9bvaeRR1ehFn9BgMdGr0l3aCvfYyAfem9/GENlrz36ufpTBPTv07r8lm3qpPiOo1y/7u+SJImNzacmw5hrX1wt/kRpABBDQ84bJOf16+jLt/gPhUvGGw==","MD":"b1a536c0-29b9-11eb-adc1-0242ac120002","TermUrl":"https://api.sumup.com/v0.1/checkouts/e552de3b-1777-4c91-bdb8-756967678572/complete_payment"}
400application/json
The request body is invalid for processing the checkout.
Exactly one of the following variants.
ErrorExtended
- 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.namerefers to thenameparameter embedded in thecardobject.Example:
"card.name"
array<unknown>
401application/json
The request is not authorized.
- format:
uriA 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:
uriA URI reference that identifies the specific occurrence of the problem.
Example:
"https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"
404application/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"
409application/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"