Create a Checkout Session

​

Creates a Checkout Session for a customer payment attempt or subscription signup. Create a new session each time a customer starts checkout, then redirect the customer to the returned checkout URL, render the session with the Paypercut checkout SDK, or confirm a custom Session with a Payment Method collected by Elements.

Use hosted or embedded Checkout when Paypercut should control the complete payment form. Use ui_mode=custom with Elements when your frontend owns the payment-page layout and your backend should create and confirm the Session after validating the final order. A custom Session response can include an opaque client_secret for a supported client SDK to continue customer authentication. In a JavaScript integration, pass it to paypercut.confirmPayment().

You can also create Checkout Sessions from the Merchant Dashboard when you want to test a Checkout flow without automating session creation.

Related guides: Checkout Experience, Build a custom checkout with Elements, and Checkout Sessions API

Headers

  • Idempotency-Key
    Type: string
    max length:  
    255

    Provide a unique, stable key per operation so retries don't create duplicates. Allowed: letters, digits, colon, dash, underscore, dot. Max 255 characters.

Body·

required
application/json

Request parameters for creating a new checkout session.

    • currency
      Type:
      required

      Three-letter ISO currency code

      Properties: 2
    • description
      Type: string

      A free-form reference to describe the checkout

    • mode
      Type: stringenum
      required

      The mode of the Checkout Session.

      values
      • payment

        Standard one-time payment.

      • setup

        Set up a payment method for future use.

      • subscription

        Create a subscription checkout that collects the first payment and stores a reusable payment method for renewal billing.

    • ui_mode
      Type: "custom" or "embedded" or "hosted"enum

      The UI mode of the Session. Defaults to hosted.

    • cancel_url
      Type: string

      If set, Checkout displays a back button and customers will be directed to this URL if they decide to cancel payment and return to your website.

    • success_url
      Type: string

      The URL to which Paypercut should send customers when payment or setup is complete. This parameter is not allowed if ui_mode is embedded or custom. If you'd like to use information from the successful Checkout Session on your page, read the guide on customizing your success page.

    • return_url
      Type: string

      The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site. This parameter is required if ui_mode is embedded or custom and redirect-based payment methods are enabled on the session.

    • payment_method_types
      Type: array of string
      max length:  
      100

      A list of the types of payment methods (e.g. card) this Checkout Session is allowed to accept.

    • submit_type
      Type: string | nullenum

      Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button. submit_type can only be specified on Checkout Sessions in payment mode. If blank or auto, pay is used.

      values
      autobookdonatepaysubscribe
    • wallet_options
      Type:

      Wallet-specific configuration for this Checkout Session.

      Properties: 2
    • client_reference_id
      Type: string

      A free-form reference from the merchant's system. Typically used to identify the checkout in the merchant's system. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.

    • client_customer_id
      Type: string

      An identifier of the customer in the merchant's system. Used to associate the Checkout and corresponding payments created from the Checkout. Required for SEPA payments - this will ensure that your customer is given a virtual iban that is unique to them and will enable Paypercut to reconcile the payment.

    • expires_at
      Type: string | nullFormat: date-time

      Expiry time for the checkout. After this time, the checkout will no longer be available for payment. Defaults to 24h after creation.

    • line_items
      Type:

      Details about the products sold or services provided. In subscription mode, use recurring Price-backed line items for subscription plans.

      Properties: 4
    • shipping_options
      Type: …5

      Shipping options offered for this Checkout Session. Provide one to five inline shipping_rate_data options when the customer should choose a shipping rate during checkout.

      Properties: 2
    • payment_intent_data
      Type: nullable

      Create-time PaymentIntent options accepted when creating a Checkout Session.

      Properties: 8
    • saved_payment_method_options
      Type:
      Properties: 3
    • payment_method_options
      Type:

      Payment-method-specific behavior for a Checkout Session.

      Properties: 1
    • metadata

      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

      Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

      • propertyName
        additionalPropertyType: string
    • after_completion
      Type:

      After completion behavior for the Checkout Session.

      Properties: 3
    • locale
      Type: stringenum

      The IETF language tag of the locale Checkout is displayed in. If blank or auto, the browser's locale is used.

      values
      • auto
      • bg
      • bg-BG
      • cs
      • cs-CZ
      • da
      • da-DK
      • de
    • customer
      Type: string | null
      max length:  
      100

      ID of an existing Customer, if one exists.

    • customer_email
      Type: string | null

      If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once a session is complete, use the customer field.

    • customer_creation
      Type: "always" or "if_required"enum

      Configure whether a Checkout Session creates a Customer during Session confirmation. When a Customer is not created, you can still retrieve email, address, and other customer data entered in Checkout with customer_details. Can only be set in payment mode.

    • amount
      Type: Format: int64

      Integer amount in minor units (e.g. cents) specific to the currency. Example: 100 for €1.00

    • billing_address_collection
      Type: enum

      Specify whether Checkout should collect the customer's billing address. Defaults to auto.

      values
      • auto

        Checkout will only collect the billing address when necessary.

      • required

        Checkout will always collect the customer's billing address.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/checkouts
curl https://api.paypercut.io/v1/checkouts \
  --request POST \
  --header 'Idempotency-Key: order:12345:pi:create' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "mode": "payment",
  "ui_mode": "hosted",
  "currency": "EUR",
  "line_items": [
    {
      "price": "01HD7M6DRKZ4Q4QEVWJB0RC1S6",
      "quantity": 1
    }
  ],
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "payment_intent_data": {
    "metadata": {
      "order_id": "order_1042"
    }
  },
  "saved_payment_method_options": {
    "allow_redisplay_filters": [
      "always",
      "limited"
    ],
    "payment_method_remove": "enabled",
    "payment_method_save": "enabled"
  },
  "payment_method_options": {
    "card": {
      "request_three_d_secure": "any"
    }
  },
  "metadata": {
    "cart_id": "cart_987"
  }
}'

{
  "id": "21210021c2855007efa2d657018",
  "client_secret": null,
  "currency": {
    "iso": "usd",
    "scale": 2
  },
  "description": null,
  "mode": "payment",
  "ui_mode": "hosted",
  "amount_total": 100,
  "amount_subtotal": 100,
  "total_details": {
    "amount_discount": 100,
    "amount_shipping": 100,
    "amount_tax": 100
  },
  "shipping_options": [
    {
      "shipping_rate": {
        "id": "shr_standard",
        "display_name": "Standard shipping",
        "type": "fixed_amount",
        "fixed_amount": {
          "amount": 100,
          "currency": "EUR"
        },
        "delivery_estimate": {
          "minimum": {
            "unit": "business_day",
            "value": 3
          },
          "maximum": {
            "unit": "business_day",
            "value": 3
          }
        },
        "tax_behavior": "unspecified",
        "tax_code": null,
        "metadata": {
          "additionalProperty": "string"
        },
        "active": true
      }
    }
  ],
  "shipping_cost": {
    "shipping_rate": "shr_standard",
    "amount_subtotal": 100,
    "amount_tax": 100,
    "amount_total": 100,
    "currency": {
      "iso": "usd",
      "scale": 2
    }
  },
  "url": "https://www.example.com",
  "cancel_url": null,
  "success_url": null,
  "return_url": null,
  "payment_method_types": [
    "string"
  ],
  "submit_type": "auto",
  "wallet_options": {
    "apple_pay": {
      "display": "auto"
    },
    "google_pay": {
      "display": "auto"
    }
  },
  "client_reference_id": null,
  "client_customer_id": null,
  "expires_at": null,
  "line_items": [
    {
      "quantity": 2,
      "price": "01K755J9SV2364REVHB915Z2FW",
      "price_data": {
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1,
        "currency": "string",
        "livemode": true,
        "lookup_key": null,
        "product": "01K755J9SV2364REVHB915Z2FW",
        "product_data": {
          "active": true,
          "name": "string",
          "description": "string",
          "unit_label": "string",
          "id": "string"
        },
        "recurring": {
          "interval": "daily",
          "interval_count": 1,
          "meter": null,
          "usage_type": "licensed"
        },
        "type": "one_time",
        "unit_amount": null,
        "unit_amount_decimal": null,
        "id": "string"
      },
      "metadata": {
        "additionalProperty": "string"
      }
    }
  ],
  "saved_payment_method_options": {
    "allow_redisplay_filters": [
      "always"
    ],
    "payment_method_remove": "disabled",
    "payment_method_save": "disabled"
  },
  "payment_method_options": {
    "card": {
      "request_three_d_secure": "any"
    }
  },
  "metadata": {
    "additionalProperty": "string"
  },
  "after_completion": {
    "type": "redirect",
    "redirect": {
      "url": "https://example.com"
    },
    "hosted": {
      "custom_message": "string"
    }
  },
  "locale": null,
  "customer": "01K755J9SV2364REVHB915Z2FW",
  "customer_email": null,
  "customer_creation": "always",
  "payment_intent": "01K755J9SY55CS04SQ3JX1NX36",
  "setup_intent": "01K755J9SY55CS04SQ3JX1NX36",
  "subscription": "01HD7M6DRKZ4Q4QEVWJB0RC1S6",
  "payment_link": "01K755J9SV2364REVHB915Z2FW",
  "payment_status": "no_payment_required",
  "status": "complete",
  "next_action": {
    "redirect_to_url": {
      "return_url": null,
      "url": null
    },
    "type": "string",
    "three_d_secure": {
      "flow": "frictionless",
      "status_url": "https://api.yourco.com/v1/payment_intents/pi_123",
      "return_url": null,
      "message": {
        "allowed_origins": [
          "https://merchant.example.com"
        ]
      },
      "hint": {
        "scheme": "visa",
        "version": "2.2.0"
      },
      "idempotency_key": "string"
    }
  },
  "livemode": true,
  "billing_address_collection": "auto"
}

Checkout created successfully.