SUsumup
Checkouts

Update a checkout

Changed on

Updates the amount, currency, description, reference, expiration, or customer associated with an existing checkout. Only the supplied fields are updated.

This request changes the checkout details; it does not charge a payment instrument. Process the checkout separately to attempt a payment.

patch/v0.1/checkouts/{checkout_id}

Request

  • Base URL
    https://api.sumup.com
  • URL
    https://api.sumup.com/v0.1/checkouts/{checkout_id}
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: https://api.sumup.com/authorize
      Token URL: https://api.sumup.com/token scopes: payments, checkouts.write

Request body

amountnumber float

Updated amount to be charged to the payer, expressed in major units.

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

Three-letter ISO 4217 currency code of the amount.

descriptionstring

Updated short merchant-defined description shown in SumUp tools and reporting.

checkout_referencestring

Updated merchant-defined reference for the checkout.

valid_untilstring date-time nullable

Updated expiration timestamp. The checkout must be processed before this moment, otherwise it becomes unusable.

customer_idstring

Updated merchant-scoped customer identifier associated with the checkout.

Example request

{
  "amount": 12.5,
  "currency": "EUR",
  "description": "Updated purchase",
  "checkout_reference": "f00a8f74-b05d-4605-bd73-2a901bae5802",
  "valid_until": "2030-12-31T23:59:59Z",
  "customer_id": "831ff8d4cd5958ab5670"
}

Response

Returns the updated checkout resource.

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

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.

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

Changes

  • 0f66b0a52002Revision changes
    • breaking

      removed the enum value BGN of the request property

    • breaking

      the request property's maxLength was decreased to 64

    • info

      removed the BGN enum value from the response property for the response status

    • info

      removed the BGN enum value from the /// response property for the response status

  • c75ca16e1e44Revision changes
    • info

      endpoint added