Confirm a Checkout Session

​

Confirms an open Checkout Session with a Payment Method collected by Paypercut Elements or another supported tokenization flow.

For a custom Elements integration, call this endpoint only from your backend after validating the final order and creating a Session with ui_mode=custom. Store the Checkout Session ID before confirmation and use a stable Idempotency-Key for the payment attempt.

The response can include client_secret for a custom Session. Return this opaque capability only to the untrusted client instance and customer that own the payment attempt, and pass it only to a supported Paypercut client SDK. In a JavaScript integration, use paypercut.confirmPayment().

If the confirmation response is lost or times out, retrieve the same Checkout Session before retrying. Do not create a replacement Session or repeat confirmation with a different Payment Method until the previous Session is known to be terminal.

Related guide: Build a custom checkout with Elements

Path Parameters
  • id
    Type: string
    max length:  
    200
    required

    Checkout Session ID.

Query Parameters
  • expand
    Type: array string[]

    Related resources to expand in the response, such as payment_intent.

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 confirming an open Checkout Session.

  • payment_method
    Type: string ·

    Opaque Payment Method ID to use for confirmation. In an Elements integration, pass the id returned by paypercut.createPaymentMethod({ elements }) or the Express Checkout Element's confirm event.

  • payment_method_data
    Type: object ·
  • payment_method_options
    Type: object ·

    Payment method-specific configuration for this PaymentIntent.

  • save_payment_method
    Type: boolean | null

    Set to true only after the customer agrees to save the Payment Method and the Checkout Session is configured for future usage.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/checkouts/{id}/confirm
curl 'https://api.paypercut.io/v1/checkouts/{id}/confirm' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "payment_method": "01KXXXXXXXXXXXXXXXXXXXXXXX"
}'

{
  "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 Session confirmation completed or entered its next processing state.