Sign in
Checkouts

Process a checkout

:::caution[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.

Follow this request with Retrieve a checkout to confirm its status.

put/v0.1/checkouts/{checkout_id}

Request body

payment_type'card' | 'boleto' | 'ideal' | 'blik' | 'bancontact' | 'google_pay' | 'apple_pay' required

Payment method used for this processing attempt. It determines which additional request fields are required.

installmentsinteger

Number of installments for deferred payments. Available only to merchant users in Brazil.

google_payobject

Raw PaymentData object received from Google Pay. Send the Google Pay response payload as-is.

apple_payobject

Raw payment token object received from Apple Pay. Send the Apple Pay response payload as-is.

tokenstring

Saved-card token to use instead of raw card details when processing with a previously stored payment instrument.

customer_idstring

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

Example request

{
  "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": {
    "name": "FIRSTNAME LASTNAME",
    "number": "1234567890123456",
    "expiry_year": "2030",
    "expiry_month": "12",
    "cvv": "123",
    "zip_code": "12345",
    "type": "VISA"
  },
  "google_pay": {
    "apiVersionMinor": 0,
    "apiVersion": 2,
    "paymentMethodData": {
      "description": "Visa •••• 1111",
      "tokenizationData": {
        "type": "PAYMENT_GATEWAY",
        "token": "token-data"
      },
      "type": "CARD",
      "info": {
        "cardNetwork": "VISA",
        "cardDetails": "1111"
      }
    }
  },
  "apple_pay": {
    "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"
    }
  },
  "token": "ba85dfee-c3cf-48a6-84f5-d7d761fbba50",
  "customer_id": "MEDKHDTI",
  "personal_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "phone": "+491635559723",
    "birth_date": "1993-12-31",
    "tax_id": "423.378.593-47",
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line_1": "Sample street",
      "line_2": "ap. 5",
      "postal_code": "10115",
      "state": "Berlin"
    }
  }
}

Response

Returns the checkout resource after a processing attempt.

checkout_referencestring

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.

amountnumber float

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

currency'BGN' | 'BRL' | 'CHF' | 'CLP' | 'COP' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HRK' | 'HUF' | 'NOK' | 'PLN' | 'RON' | 'SEK' | 'USD'

Three-letter ISO 4217 currency code of the amount.

merchant_codestring

Short unique identifier for the merchant that receives the payment.

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.

return_urlstring uri

Optional backend callback URL used by SumUp to notify your platform about processing updates for the checkout.

idstring

Unique SumUp identifier of the checkout resource.

status'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.

datestring date-time

The timestamp of when the checkout was created.

valid_untilstring date-time nullable

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.

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.

hosted_checkout_urlstring uri

URL of the SumUp-hosted payment page that handles the payment flow. Returned when Hosted Checkout is enabled for the checkout.

transaction_codestring

Transaction code of the successful transaction with which the payment for the checkout is completed.

transaction_idstring

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

merchant_namestring

Name of the merchant.

redirect_urlstring

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

Example response

{
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "amount": 10.1,
  "currency": "EUR",
  "merchant_code": "MH4H92C7",
  "description": "Purchase",
  "return_url": "http://example.com",
  "id": "4e425463-3e1b-431d-83fa-1e51c2925e99",
  "status": "PENDING",
  "date": "2020-02-29T10:56:56+00:00",
  "valid_until": "2020-02-29T10:56:56+00:00",
  "customer_id": "831ff8d4cd5958ab5670",
  "mandate": {
    "type": "recurrent",
    "status": "active",
    "merchant_code": "MH4H92C7"
  },
  "hosted_checkout_url": "https://checkout.sumup.com/pay/8f9316a3-cda9-42a9-9771-54d534315676",
  "transactions": [
    {
      "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"
    }
  ],
  "transaction_code": "TEENSK4W2K",
  "transaction_id": "410fc44a-5956-44e1-b5cc-19c6f8d727a4",
  "merchant_name": "Sample Merchant",
  "redirect_url": "https://mysite.com/completed_purchase",
  "payment_instrument": {
    "token": "e76d7e5c-9375-4fac-a7e7-b19dc5302fbc"
  }
}

Changes

Changed in 3 of the 56 revisions of this API.13