SumUp
Docs
Dashboard
SumUpDeveloper
Dashboard

Checkout

View as MarkdownSet up AI assistant

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.

Fields

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

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

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

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

    • transaction_codestring

      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"

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

    • installments_countinteger
      minimum: 1

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

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

      Example: 6

    • tip_amountnumber
      format: float

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

      Example: 3

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

Type to search…