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

GET/v1/confirmation_tokens/:id

POST/v1/test_helpers/confirmation_tokens

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

Server-side language

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

Server-side language

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

POST/v1/tokens

GET/v1/tokens/:id

Confirmation Token

The Confirmation Token object

Attributes

idstring

objectstring

createdtimestamp

expires_atnullable timestamp

livemodeboolean

mandate_datanullable object

payment_intentnullable string

payment_method_optionsnullable object

payment_method_previewnullable object

return_urlnullable string

setup_future_usagenullable enum

setup_intentnullable string

shippingnullable object

use_stripe_sdkboolean

Retrieve a ConfirmationToken

Parameters

Returns

Create a test Confirmation Token Test helper

Parameters

payment_methodstring

payment_method_dataobject

payment_method_optionsobject

return_urlstring

setup_future_usageenum

shippingobject

Returns

Tokens