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.
openapi: 3.0.0
info:
title: Stripe Accounts Account Tokens API
description: This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current requirements or if the account is enabled to make live charges or receive payouts.
contact:
email: dev-platform@stripe.com
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
servers:
- url: https://api.stripe.com/
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Tokens
paths:
/v1/issuing/tokens:
get:
description: <p>Lists all Issuing <code>Token</code> objects for a given card.</p>
operationId: getIssuingTokens
parameters:
- description: The Issuing card identifier to list tokens for.
in: query
name: card
required: true
schema:
maxLength: 5000
type: string
style: form
- description: Select Issuing tokens that were created during the given date interval.
explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Select Issuing tokens with the given status.
in: query
name: status
required: false
schema:
enum:
- active
- deleted
- requested
- suspended
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetIssuingTokensRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/IssuingNetworkTokenList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Issuing Tokens
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Tokens
/v1/issuing/tokens/{token}:
get:
description: <p>Retrieves an Issuing <code>Token</code> object.</p>
operationId: getIssuingTokensToken
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: token
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetIssuingTokensTokenRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/issuing.token'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Issuing Tokens
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Tokens
post:
description: <p>Attempts to update the specified Issuing <code>Token</code> object to the status specified.</p>
operationId: postIssuingTokensToken
parameters:
- in: path
name: token
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostIssuingTokensTokenRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/issuing.token'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Issuing Tokens
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Tokens
/v1/tokens:
post:
summary: Stripe Create Token
description: <p>Creates a single-use token that represents a credit card's details. You can use this token in place of a credit card dictionary with any API method.</p>
operationId: PostTokens
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
card:
type: object
properties:
number:
type: string
exp_month:
type: string
exp_year:
type: string
cvc:
type: string
name:
type: string
address_line1:
type: string
address_line2:
type: string
address_city:
type: string
address_state:
type: string
address_zip:
type: string
address_country:
type: string
currency:
type: string
bank_account:
type: object
properties:
country:
type: string
currency:
type: string
account_holder_name:
type: string
account_holder_type:
type: string
enum:
- company
- individual
routing_number:
type: string
account_number:
type: string
pii:
type: object
properties:
id_number:
type: string
account:
type: object
properties:
business_type:
type: string
tos_shown_and_accepted:
type: boolean
individual:
type: object
company:
type: object
person:
type: object
properties:
first_name:
type: string
last_name:
type: string
dob:
type: object
address:
type: object
ssn_last_4:
type: string
customer:
type: string
maxLength: 5000
cvc_update:
type: object
properties:
cvc:
type: string
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/token'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tokens
/v1/tokens/{token}:
get:
summary: Stripe Retrieve Token
description: <p>Retrieves the token with the given ID.</p>
operationId: GetTokensToken
parameters:
- name: token
in: path
required: true
schema:
type: string
maxLength: 5000
- name: expand
in: query
required: false
explode: true
schema:
type: array
items:
type: string
maxLength: 5000
style: deepObject
responses:
'200':
description: Successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/token'
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/error_2'
tags:
- Tokens
components:
schemas:
PostIssuingTokensTokenRequest:
type: object
required:
- status
properties:
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
status:
description: Specifies which status the token should be updated to.
enum:
- active
- deleted
- suspended
type: string
issuing.cardholder:
description: 'An Issuing `Cardholder` object represents an individual or business entity who is [issued](https://stripe.com/docs/issuing) cards.
Related guide: [How to create a cardholder](https://stripe.com/docs/issuing/cards#create-cardholder)'
properties:
billing:
$ref: '#/components/schemas/issuing_cardholder_address'
company:
anyOf:
- $ref: '#/components/schemas/issuing_cardholder_company'
description: Additional information about a `company` cardholder.
nullable: true
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
email:
description: The cardholder's email address.
maxLength: 5000
nullable: true
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
individual:
anyOf:
- $ref: '#/components/schemas/issuing_cardholder_individual'
description: Additional information about an `individual` cardholder.
nullable: true
livemode:
description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
type: boolean
metadata:
additionalProperties:
maxLength: 500
type: string
description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
type: object
name:
description: The cardholder's name. This will be printed on cards issued to them.
maxLength: 5000
type: string
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- issuing.cardholder
type: string
phone_number:
description: The cardholder's phone number. This is required for all cardholders who will be creating EU cards. See the [3D Secure documentation](https://stripe.com/docs/issuing/3d-secure#when-is-3d-secure-applied) for more details.
maxLength: 5000
nullable: true
type: string
preferred_locales:
description: "The cardholder’s preferred locales (languages), ordered by preference. Locales can be `de`, `en`, `es`, `fr`, or `it`.\n This changes the language of the [3D Secure flow](https://stripe.com/docs/issuing/3d-secure) and one-time password messages sent to the cardholder."
items:
enum:
- de
- en
- es
- fr
- it
type: string
nullable: true
type: array
requirements:
$ref: '#/components/schemas/issuing_cardholder_requirements'
spending_controls:
anyOf:
- $ref: '#/components/schemas/issuing_cardholder_authorization_controls'
description: Rules that control spending across this cardholder's cards. Refer to our [documentation](https://stripe.com/docs/issuing/controls/spending-controls) for more details.
nullable: true
status:
description: Specifies whether to permit authorizations on this cardholder's cards.
enum:
- active
- blocked
- inactive
type: string
type:
description: One of `individual` or `company`. See [Choose a cardholder type](https://stripe.com/docs/issuing/other/choose-cardholder) for more details.
enum:
- company
- individual
type: string
x-stripeBypassValidation: true
required:
- billing
- created
- id
- livemode
- metadata
- name
- object
- requirements
- status
- type
title: IssuingCardholder
type: object
x-expandableFields:
- billing
- company
- individual
- requirements
- spending_controls
x-resourceId: issuing.cardholder
token:
type: object
properties:
id:
type: string
maxLength: 5000
object:
type: string
enum:
- token
bank_account:
type:
- object
- 'null'
card:
type:
- object
- 'null'
client_ip:
type:
- string
- 'null'
created:
type: integer
livemode:
type: boolean
type:
type: string
used:
type: boolean
required:
- id
- object
- created
- livemode
- type
- used
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
issuing.token:
description: An issuing token object is created when an issued card is added to a digital wallet. As a [card issuer](https://stripe.com/docs/issuing), you can [view and manage these tokens](https://stripe.com/docs/issuing/controls/token-management) through Stripe.
properties:
card:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/issuing.card'
description: Card associated with this token.
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/issuing.card'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
device_fingerprint:
description: The hashed ID derived from the device ID from the card network associated with the token
maxLength: 5000
nullable: true
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
last4:
description: The last four digits of the token.
maxLength: 5000
type: string
livemode:
description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
type: boolean
network:
description: The token service provider / card network associated with the token.
enum:
- mastercard
- visa
type: string
network_data:
$ref: '#/components/schemas/issuing_network_token_network_data'
network_updated_at:
description: Time at which the token was last updated by the card network. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- issuing.token
type: string
status:
description: The usage state of the token.
enum:
- active
- deleted
- requested
- suspended
type: string
wallet_provider:
description: The digital wallet for this token, if one was used.
enum:
- apple_pay
- google_pay
- samsung_pay
type: string
required:
- card
- created
- id
- livemode
- network
- network_updated_at
- object
- status
title: IssuingNetworkToken
type: object
x-expandableFields:
- card
- network_data
x-resourceId: issuing.token
GetIssuingTokensRequest:
type: object
properties: {}
GetIssuingTokensTokenRequest:
type: object
properties: {}
IssuingNetworkTokenList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/issuing.token'
type: array
has_more:
description: True if this list has another page of items after this one that can be fetched.
type: boolean
object:
description: String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
type: string
issuing.card:
description: You can [create physical or virtual cards](https://stripe.com/docs/issuing/cards) that are issued to cardholders.
properties:
brand:
description: The brand of the card.
maxLength: 5000
type: string
cancellation_reason:
description: The reason why the card was canceled.
enum:
- design_rejected
- lost
- stolen
nullable: true
type: string
x-stripeBypassValidation: true
cardholder:
$ref: '#/components/schemas/issuing.cardholder'
created:
description: Time at which the object was created. Measured in seconds since the Unix epoch.
format: unix-time
type: integer
currency:
description: Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Supported currencies are `usd` in the US, `eur` in the EU, and `gbp` in the UK.
type: string
cvc:
description: The card's CVC. For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with [the `expand` parameter](https://stripe.com/docs/api/expanding_objects). Additionally, it's only available via the ["Retrieve a card" endpoint](https://stripe.com/docs/api/issuing/cards/retrieve), not via "List all cards" or any other endpoint.
maxLength: 5000
type: string
exp_month:
description: The expiration month of the card.
type: integer
exp_year:
description: The expiration year of the card.
type: integer
financial_account:
description: The financial account this card is attached to.
maxLength: 5000
nullable: true
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
last4:
description: The last 4 digits of the card number.
maxLength: 5000
type: string
livemode:
description: Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.
type: boolean
metadata:
additionalProperties:
maxLength: 500
type: string
description: Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
type: object
number:
description: The full unredacted card number. For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with [the `expand` parameter](https://stripe.com/docs/api/expanding_objects). Additionally, it's only available via the ["Retrieve a card" endpoint](https://stripe.com/docs/api/issuing/cards/retrieve), not via "List all cards" or any other endpoint.
maxLength: 5000
type: string
object:
description: String representing the object's type. Objects of the same type share the same value.
enum:
- issuing.card
type: string
replaced_by:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/issuing.card'
description: The latest card that replaces this card, if any.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/issuing.card'
replacement_for:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/issuing.card'
description: The card this card replaces, if any.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/issuing.card'
replacement_reason:
description: The reason why the previous card needed to be replaced.
enum:
- damaged
- expired
- lost
- stolen
nullable: true
type: string
x-stripeBypassValidation: true
shipping:
anyOf:
- $ref: '#/components/schemas/issuing_card_shipping'
description: Where and how the card will be shipped.
nullable: true
spending_controls:
$ref: '#/components/schemas/issuing_card_authorization_controls'
status:
description: Whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to `inactive`.
enum:
- active
- canceled
- inactive
type: string
x-stripeBypassValidation: true
type:
description: The type of the card.
enum:
- physical
- virtual
type: string
wallets:
anyOf:
- $ref: '#/components/schemas/issuing_card_wallets'
description: Information relating to digital wallets (like Apple Pay and Google Pay).
nullable: true
required:
- brand
- cardholder
- created
- currency
- exp_month
- exp_year
- id
- last4
- livemode
- metadata
- object
- spending_controls
- status
- type
title: IssuingCard
type: object
x-expandableFields:
- cardholder
- replaced_by
- replacement_for
- shipping
- spending_controls
- wallets
x-resourceId: issuing.card
error_2:
type: object
properties:
error:
type: object
properties:
type:
type: string
message:
type: string
code:
type: string
param:
type: string