Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Confirmation Token 

ConfirmationTokens help transport client side data collected by Stripe JS over to your server for confirming a PaymentIntent or SetupIntent. If the confirmation is successful, values present on the ConfirmationToken are written onto the Intent.

To learn more about how to use ConfirmationToken, visit the related guides:

Endpoints

The Confirmation Token object 

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • createdtimestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • expires_atnullable timestamp

    Time at which this ConfirmationToken expires and can no longer be used to confirm a PaymentIntent or SetupIntent.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • mandate_datanullable object

    Data used for generating a Mandate.

  • payment_intentnullable string

    ID of the PaymentIntent that this ConfirmationToken was used to confirm, or null if this ConfirmationToken has not yet been used.

  • payment_method_optionsnullable object

    Payment-method-specific configuration for this ConfirmationToken.

  • payment_method_previewnullable object

    Payment details collected by the Payment Element, used to create a PaymentMethod when a PaymentIntent or SetupIntent is confirmed with this ConfirmationToken.

  • return_urlnullable string

    Return URL used to confirm the Intent.

  • setup_future_usagenullable enum

    Indicates that you intend to make future payments with this ConfirmationToken’s payment method.

    The presence of this property will attach the payment method to the PaymentIntent’s Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete.

    Possible enum values
    off_session

    Use off_session if your customer may or may not be present in your checkout flow.

    on_session

    Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow.

  • setup_intentnullable string

    ID of the SetupIntent that this ConfirmationToken was used to confirm, or null if this ConfirmationToken has not yet been used.

  • shippingnullable object

    Shipping information collected on this ConfirmationToken.

  • use_stripe_sdkboolean

    Indicates whether the Stripe SDK is used to handle confirmation flow. Defaults to true on ConfirmationToken.

The Confirmation Token object
{
  "id": "ctoken_1NnQUf2eZvKYlo2CIObdtbnb",
  "object": "confirmation_token",
  "created": 1694025025,
  "expires_at": 1694068225,
  "livemode": true,
  "mandate_data": null,
  "payment_intent": null,
  "payment_method": null,
  "payment_method_preview": {
    "billing_details": {
      "address": {
        "city": "Hyde Park",
        "country": "US",
        "line1": "50 Sprague St",
        "line2": "",
        "postal_code": "02136",
        "state": "MA"
      },
      "email": "jennyrosen@stripe.com",
      "name": "Jenny Rosen",
      "phone": null
    },
    "card": {
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": null
      },
      "country": "US",
      "display_brand": "visa",
      "exp_month": 8,
      "exp_year": 2026,
      "funding": "credit",
      "generated_from": null,
      "last4": "4242",
      "networks": {
        "available": [
          "visa"
        ],
        "preferred": null
      },
      "three_d_secure_usage": {
        "supported": true
      },
      "wallet": null
    },
    "type": "card"
  },
  "return_url": "https://example.com/return",
  "setup_future_usage": "off_session",
  "setup_intent": null,
  "shipping": {
    "address": {
      "city": "Hyde Park",
      "country": "US",
      "line1": "50 Sprague St",
      "line2": "",
      "postal_code": "02136",
      "state": "MA"
    },
    "name": "Jenny Rosen",
    "phone": null
  }
}

Retrieve a ConfirmationToken 

Retrieves an existing ConfirmationToken object

Parameters

No parameters.

Returns

Returns the specified ConfirmationToken

GET /v1/confirmation_tokens/:id
curl https://api.stripe.com/v1/confirmation_tokens/ctoken_1NnQUf2eZvKYlo2CIObdtbnb \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "ctoken_1NnQUf2eZvKYlo2CIObdtbnb",
  "object": "confirmation_token",
  "created": 1694025025,
  "expires_at": 1694068225,
  "livemode": true,
  "mandate_data": null,
  "payment_intent": null,
  "payment_method": null,
  "payment_method_preview": {
    "billing_details": {
      "address": {
        "city": "Hyde Park",
        "country": "US",
        "line1": "50 Sprague St",
        "line2": "",
        "postal_code": "02136",
        "state": "MA"
      },
      "email": "jennyrosen@stripe.com",
      "name": "Jenny Rosen",
      "phone": null
    },
    "card": {
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": null
      },
      "country": "US",
      "display_brand": "visa",
      "exp_month": 8,
      "exp_year": 2026,
      "funding": "credit",
      "generated_from": null,
      "last4": "4242",
      "networks": {
        "available": [
          "visa"
        ],
        "preferred": null
      },
      "three_d_secure_usage": {
        "supported": true
      },
      "wallet": null
    },
    "type": "card"
  },
  "return_url": "https://example.com/return",
  "setup_future_usage": "off_session",
  "setup_intent": null,
  "shipping": {
    "address": {
      "city": "Hyde Park",
      "country": "US",
      "line1": "50 Sprague St",
      "line2": "",
      "postal_code": "02136",
      "state": "MA"
    },
    "name": "Jenny Rosen",
    "phone": null
  }
}

Create a test Confirmation Token Test helper

Creates a test mode Confirmation Token server side for your integration tests.

Parameters

  • payment_methodstring

    ID of an existing PaymentMethod.

  • payment_method_dataobject

    If provided, this hash will be used to create a PaymentMethod.

  • payment_method_optionsobject

    Payment-method-specific configuration for this ConfirmationToken.

  • return_urlstring

    Return URL used to confirm the Intent.

  • setup_future_usageenum

    Indicates that you intend to make future payments with this ConfirmationToken’s payment method.

    The presence of this property will attach the payment method to the PaymentIntent’s Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete.

    Possible enum values
    off_session

    Use off_session if your customer may or may not be present in your checkout flow.

    on_session

    Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow.

  • shippingobject

    Shipping information for this ConfirmationToken.

Returns

Returns a testmode Confirmation Token

POST /v1/test_helpers/confirmation_tokens
curl https://api.stripe.com/v1/test_helpers/confirmation_tokens \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d payment_method=pm_card_visa
Response
{
  "id": "ctoken_1Ow71CL4FhS6zgoxWjxc7sfr",
  "object": "confirmation_token",
  "created": 1710871450,
  "expires_at": 1710914650,
  "livemode": false,
  "payment_intent": null,
  "payment_method_preview": {
    "billing_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "name": null,
      "phone": null
    },
    "card": {
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "unchecked"
      },
      "country": "US",
      "display_brand": "visa",
      "exp_month": 3,
      "exp_year": 2025,
      "fingerprint": "jbGyCKrSRsFpOBWP",
      "funding": "credit",
      "generated_from": null,
      "last4": "4242",
      "networks": {
        "available": [
          "visa"
        ],
        "preferred": null
      },
      "three_d_secure_usage": {
        "supported": true
      },
      "wallet": null
    },
    "type": "card"
  },
  "return_url": null,
  "setup_future_usage": null,
  "setup_intent": null,
  "shipping": null,
  "use_stripe_sdk": true
}

Tokens 

Tokenization is the process Stripe uses to collect sensitive card or bank account details, or personally identifiable information (PII), directly from your customers in a secure manner. A token representing this information is returned to your server to use. Use our recommended payments integrations to perform this process on the client-side. This guarantees that no sensitive card data touches your server, and allows your integration to operate in a PCI-compliant way.

If you can’t use client-side tokenization, you can also create tokens using the API with either your publishable or secret API key. If your integration uses this method, you’re responsible for any PCI compliance that it might require, and you must keep your secret API key safe. Unlike with client-side tokenization, your customer’s information isn’t sent directly to Stripe, so we can’t determine how it’s handled or stored.

You can’t store or use tokens more than once. To store card or bank account information for later use, create Customer objects or External accounts. Radar, our integrated solution for automatic fraud protection, performs best with integrations that use client-side tokenization.

Endpoints