Process a checkout

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

Authorization

Use one of the following alternatives:

  • apiKey
  • oauth2 with scopes paymentscheckouts.write
Authorization guide

Path parameters

  • checkout_idstringrequired

    SumUp-generated id returned when creating a checkout. Use this value to retrieve, update, process, or deactivate the checkout.

    Example: "4e425463-3e1b-431d-83fa-1e51c2925e99"

Body parameters

application/jsonrequired

Details of the payment instrument for processing the checkout.

  • payment_typestringrequired
    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"

  • minimum: 1maximum: 12

    Number 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
    • 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"

  • cardobject

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

    Show 7 properties
    • namestringrequired

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

      Example: "FIRSTNAME LASTNAME"

    • numberstringrequired

      Number of the payment card (without spaces).

      Example: "1234567890123456"

    • expiry_yearstringrequired
      pattern: ^[0-9]{2}([0-9]{2})?$

      Two- or four-digit expiration year in YY or YYYY format.

      Example: "2030"

    • expiry_monthstringrequired
      minLength: 2maxLength: 2pattern: ^(0[1-9]|1[0-2])$

      Two-digit expiration month, from 01 through 12.

      Example: "12"

    • cvvstringrequired
      minLength: 3maxLength: 4

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

      Example: "123"

    • typestringrequired
      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_codestring
      minLength: 5maxLength: 5

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

      Example: "12345"

  • 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

    Token of a saved payment instrument returned by checkout processing or the customer's payment-instruments endpoint. To charge a saved card, set payment_type to card and provide both this token and the associated customer_id instead of raw card details.

    Example: "ba85dfee-c3cf-48a6-84f5-d7d761fbba50"

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

    Example: "MEDKHDTI"

  • Personal details for the customer.

    Show 7 properties
    • 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"

    • format: date

      Date of birth of the customer in YYYY-MM-DD format, without a time or timezone.

      Example: "1993-12-31"

    • tax_idstring
      maxLength: 255

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

  • maxLength: 64

    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
    format: float

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

    Example: 10.1

  • currencystring
    Options:"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"

  • Short unique identifier for the merchant that receives the payment.

    Example: "MH4H92C7"

  • 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"

  • format: uri

    Optional backend callback URL for checkout status notifications. SumUp sends an HTTP POST with event_type and the checkout id. 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"

  • statusstring
    Options:"PENDING""FAILED""PAID""EXPIRED"

    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"

  • datestring
    format: date-time

    The timestamp of when the checkout was created.

    Example: "2020-02-29T10:56:56+00:00"

  • valid_untilstringnullable
    format: date-time

    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: "2030-12-31T23:59:59Z"

  • 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"

    • statusstring
      Options:"active""inactive"

      Current lifecycle status of the mandate.

      Example: "active"

    • Short unique identifier for the merchant for which the mandate is valid.

      Example: "MH4H92C7"

  • format: uri

    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"

  • 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"

    • SumUp transaction code, for example TEENSK4W2K. Use it to look up the transaction with the transaction_code query parameter. This is separate from the transaction's id and the card issuer's auth_code.

      Example: "TEENSK4W2K"

    • amountnumber
      format: float

      Total amount of the transaction in major units of currency, for example 10.1 for EUR 10.10.

      Example: 10.1

    • currencystring
      Options:"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"

    • timestampstring
      format: date-time

      The timestamp of when the transaction was created.

      Example: "2020-02-29T10:56:56.876Z"

    • statusstring
      Options:"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"

    • Options:"CASH""POS""ECOM""RECURRING""BITCOIN""BALANCE""MOTO""BOLETO""DIRECT_DEBIT""APM""UNKNOWN"

      Payment category recorded on a transaction, for example POS for a point-of-sale card payment, ECOM for an online card payment, or RECURRING for a recurring card payment. These reporting values are separate from the lowercase payment_type values used to process checkouts.

      Example: "ECOM"

    • minimum: 1

      Number of installments for a deferred payment.

      Example: 1

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

      Example: "MH4H92C7"

    • format: float

      VAT included in the total transaction amount, in major units of the transaction's currency.

      Example: 6

    • format: float

      Tip included in the total transaction amount, in major units of the transaction's currency.

      Example: 3

    • Options:"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 CHIP or CONTACTLESS for card-present payments and CUSTOMER_ENTRY for card details entered by the payer. For wallet and alternative payment methods, this can identify the method, such as APPLE_PAY or BLIK.

      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 code of the successful transaction with which the payment for the checkout is completed.

    Example: "TEENSK4W2K"

  • Unique identifier of the successful transaction that completed payment for the checkout.

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

  • Name of the merchant.

    Example: "Sample Merchant"

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

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

  • 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"

    • 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. iframe means the flow can be embedded, while browser means 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
View ErrorExtended schema
  • messagestring

    Short description of the error.

    Example: "Resource not found"

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

    Example: "card.name"

array<unknown>
401application/json

The request is not authorized.

  • typestringrequired
    format: 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."

  • instancestring
    format: uri

    A 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"

  • 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"

  • Platform code for the error.

    Example: "NOT_FOUND"

Type to search…