Create a Checkout Session

​

Create a new checkout session for processing payments.

Headers
  • Idempotency-Key
    Type: string
    max length:  
    255     Pattern: ^[a-zA-Z0-9:_\-.]+$

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

Body·CheckoutSessionCreateRequest
required
application/json

Request parameters for creating a new checkout session.

  • Request parameters for creating a new checkout session.

    • currency
      Type: object · Currency
      required

      Three-letter ISO currency code

    • 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

        Coming soon. Not available yet.

    • after_completion
      Type: object · AfterCompletion

      After completion behavior for the Checkout Session.

    • amount
      Type: integer · amountWithCurrencyPrecisionFormat: int64

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

    • billing_address_collection
      Type: string · BillingAddressCollectionenum

      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.

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

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

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

    • customer
      Type: string | null
      max length:  
      100

      ID of an existing Customer, if one exists.

    • customer_creation
      Type: stringenum

      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.

      values
      • always
      • if_required
    • 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.

    • description
      Type: string

      A free-form reference to describe the checkout

    • 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: array object[] · LineItem[]

      Details about the products sold or services provided

    • 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
    • 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
        Type: string
    • payment_intent_data
      Type: object · PaymentIntentData nullable
    • payment_method_types
      Type: array string[]

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

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

    • saved_payment_method_options
      Type: object · SavedPaymentMethodOptions
    • 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
      • auto
      • book
      • donate
      • pay
      • subscribe
    • 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.

    • ui_mode
      Type: stringenum

      The UI mode of the Session. Defaults to hosted.

      values
      • custom
      • embedded
      • hosted
    • wallet_options
      Type: object · CheckoutSessionWalletOptions

      Wallet-specific configuration for this Checkout Session.

Responses
  • 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 '{
  "currency": "EUR",
  "description": "",
  "mode": "payment",
  "ui_mode": "hosted",
  "cancel_url": "",
  "success_url": "",
  "return_url": "",
  "payment_method_types": [
    ""
  ],
  "submit_type": "auto",
  "wallet_options": {
    "apple_pay": {
      "display": "auto"
    },
    "google_pay": {
      "display": "auto"
    }
  },
  "client_reference_id": "",
  "client_customer_id": "",
  "expires_at": null,
  "line_items": [
    {
      "quantity": 2,
      "price_data": {
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1,
        "currency": "",
        "livemode": true,
        "lookup_key": null,
        "product": "01K755J9SV2364REVHB915Z2FW",
        "product_data": {
          "active": true,
          "name": "",
          "description": "",
          "unit_label": "",
          "id": ""
        },
        "recurring": {
          "interval": "day",
          "interval_count": 1,
          "meter": null,
          "usage_type": "licensed"
        },
        "type": "one_time",
        "unit_amount": null,
        "unit_amount_decimal": null,
        "id": ""
      },
      "metadata": {
        "additionalProperty": ""
      }
    }
  ],
  "payment_intent_data": {
    "amount": 100,
    "capture_method": "automatic",
    "on_behalf_of": "",
    "statement_descriptor": null,
    "setup_future_usage": "off_session",
    "payment_method": "01K688H80Z3199KETHDJ4ZAFPS",
    "customer": {
      "email": null,
      "name": null,
      "phone": null,
      "preferred_locales": [
        ""
      ],
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "invoice_settings": {
        "default_payment_method": "01K688H80Z3199KETHDJ4ZAFPS"
      },
      "created": "",
      "livemode": true,
      "id": "",
      "payment_methods": [
        {
          "type": "card",
          "card": {
            "cardholder_name": "[Max Depth Exceeded]",
            "brand": "[Max Depth Exceeded]",
            "country": "[Max Depth Exceeded]",
            "issuer": "[Max Depth Exceeded]",
            "display_brand": "[Max Depth Exceeded]",
            "exp_month": "[Max Depth Exceeded]",
            "exp_year": "[Max Depth Exceeded]",
            "fingerprint": "[Max Depth Exceeded]",
            "funding": "[Max Depth Exceeded]",
            "segment": "[Max Depth Exceeded]",
            "iin": "[Max Depth Exceeded]",
            "last4": "[Max Depth Exceeded]",
            "wallet": "[Max Depth Exceeded]",
            "three_d_secure_usage": "[Max Depth Exceeded]"
          },
          "billing_details": {
            "email": "[Max Depth Exceeded]",
            "name": "[Max Depth Exceeded]",
            "phone": "[Max Depth Exceeded]",
            "address": "[Max Depth Exceeded]"
          },
          "metadata": "[Max Depth Exceeded]",
          "customer": "",
          "id": "",
          "livemode": true,
          "created": ""
        }
      ]
    }
  },
  "saved_payment_method_options": {
    "payment_method_save": "disabled"
  },
  "metadata": {
    "additionalProperty": ""
  },
  "after_completion": {
    "type": "redirect",
    "redirect": {
      "url": ""
    },
    "hosted": {
      "custom_message": ""
    }
  },
  "locale": "auto",
  "customer": null,
  "customer_email": null,
  "customer_creation": "always",
  "amount": 100,
  "billing_address_collection": "auto"
}'

{
  "currency": {
    "iso": "usd",
    "scale": 2
  },
  "description": "string",
  "mode": "payment",
  "ui_mode": "hosted",
  "cancel_url": "string",
  "success_url": "string",
  "return_url": "string",
  "payment_method_types": [
    "string"
  ],
  "submit_type": "auto",
  "wallet_options": {
    "apple_pay": {
      "display": "auto"
    },
    "google_pay": {
      "display": "auto"
    }
  },
  "client_reference_id": "string",
  "client_customer_id": "string",
  "expires_at": null,
  "line_items": [
    {
      "quantity": 2,
      "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": "day",
          "interval_count": 1,
          "meter": null,
          "usage_type": "licensed"
        },
        "type": "one_time",
        "unit_amount": null,
        "unit_amount_decimal": null,
        "id": "string"
      },
      "metadata": {
        "additionalProperty": "string"
      }
    }
  ],
  "payment_intent_data": {
    "amount": 100,
    "capture_method": "automatic",
    "on_behalf_of": "string",
    "statement_descriptor": null,
    "setup_future_usage": "off_session",
    "payment_method": "01K688H80Z3199KETHDJ4ZAFPS",
    "customer": {
      "email": null,
      "name": null,
      "phone": null,
      "preferred_locales": [
        "string"
      ],
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "invoice_settings": {
        "default_payment_method": "01K688H80Z3199KETHDJ4ZAFPS"
      },
      "created": "2026-04-17T20:01:58.674Z",
      "livemode": true,
      "id": "string",
      "payment_methods": [
        {
          "type": "card",
          "card": {
            "cardholder_name": "[Max Depth Exceeded]",
            "brand": "[Max Depth Exceeded]",
            "country": "[Max Depth Exceeded]",
            "issuer": "[Max Depth Exceeded]",
            "display_brand": "[Max Depth Exceeded]",
            "exp_month": "[Max Depth Exceeded]",
            "exp_year": "[Max Depth Exceeded]",
            "fingerprint": "[Max Depth Exceeded]",
            "funding": "[Max Depth Exceeded]",
            "segment": "[Max Depth Exceeded]",
            "iin": "[Max Depth Exceeded]",
            "last4": "[Max Depth Exceeded]",
            "wallet": "[Max Depth Exceeded]",
            "three_d_secure_usage": "[Max Depth Exceeded]"
          },
          "billing_details": {
            "email": "[Max Depth Exceeded]",
            "name": "[Max Depth Exceeded]",
            "phone": "[Max Depth Exceeded]",
            "address": "[Max Depth Exceeded]"
          },
          "metadata": "[Max Depth Exceeded]",
          "customer": "string",
          "id": "string",
          "livemode": true,
          "created": "2026-04-17T20:01:58.674Z"
        }
      ]
    }
  },
  "saved_payment_method_options": {
    "payment_method_save": "disabled"
  },
  "metadata": {
    "additionalProperty": "string"
  },
  "after_completion": {
    "type": "redirect",
    "redirect": {
      "url": "https://example.com"
    },
    "hosted": {
      "custom_message": "string"
    }
  },
  "locale": "auto",
  "customer": null,
  "customer_email": null,
  "customer_creation": "always",
  "id": "21210021c2855007efa2d657018",
  "amount_total": 100,
  "url": "https://www.example.com",
  "payment_intent": "01K755J9SY55CS04SQ3JX1NX36",
  "setup_intent": "01K755J9SY55CS04SQ3JX1NX36",
  "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.