The Card object
Attributes
- idstring
Unique identifier for the object.
- cancellation_
reasonnullable enum The reason why the card was canceled.
Possible enum valuesdesign_rejected
The design of this card was rejected by Stripe for violating our partner guidelines.
lost
The card was lost.
stolen
The card was stolen.
- cardholderobject
The Cardholder object to which the card belongs.
- currencyenum
Three-letter ISO currency code, in lowercase. Supported currencies are
usd
in the US,eur
in the EU, andgbp
in the UK. - exp_
monthinteger The expiration month of the card.
- exp_
yearinteger The expiration year of the card.
- last4string
The last 4 digits of the card number.
- metadataobject
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.
- statusenum
Whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to
inactive
.Possible enum valuesactive
The card can approve authorizations. If the card is linked to a cardholder with past-due requirements, you may be unable to change the card’s status to ‘active’.
canceled
The card will decline authorizations, and no authorization object will be recorded. This status is permanent.
inactive
The card will decline authorizations with the
card_inactive
reason. - typeenum
The type of the card.
Possible enum valuesphysical
A physical card will be printed and shipped. It can be used at physical terminals.
virtual
No physical card will be printed. The card can be used online and can be added to digital wallets.
More attributes
- objectstring
- brandstring
- createdtimestamp
- cvcnullable stringExpandable
- livemodeboolean
- numbernullable stringExpandable
- personalization_
designnullable stringPreview featureExpandable - replaced_
bynullable stringExpandable - replacement_
fornullable stringExpandable - replacement_
reasonnullable enum - shippingnullable object
- spending_
controlsobject - walletsnullable object
{
"id": "ic_1MvSieLkdIwHu7ixn6uuO0Xu",
"object": "issuing.card",
"brand": "Visa",
"cancellation_reason": null,
"cardholder": {
"id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
"object": "issuing.cardholder",
"billing": {
"address": {
"city": "Anytown",
"country": "US",
"line1": "123 Main Street",
"line2": null,
"postal_code": "12345",
"state": "CA"
}
},
"company": null,
"created": 1680415995,
"email": null,
"individual": null,
"livemode": false,
"metadata": {},
"name": "John Doe",
"phone_number": null,
"requirements": {
"disabled_reason": "requirements.past_due",
"past_due": [
"individual.card_issuing.user_terms_acceptance.ip",
"individual.card_issuing.user_terms_acceptance.date",
"individual.first_name",
"individual.last_name"
]
},
"spending_controls": {
"allowed_categories": [],
"blocked_categories": [],
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "individual"
},
"created": 1681163868,
"currency": "usd",
"exp_month": 8,
"exp_year": 2024,
"last4": "4242",
"livemode": false,
"metadata": {},
"replaced_by": null,
"replacement_for": null,
"replacement_reason": null,
"shipping": null,
"spending_controls": {
"allowed_categories": null,
"blocked_categories": null,
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "virtual",
"wallets": {
"apple_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"google_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"primary_account_identifier": null
}
}
Create a card
Creates an Issuing Card
object.
Parameters
- currencystringRequired
The currency for the card.
- typeenumRequired
The type of card to issue. Possible values are
physical
orvirtual
.Possible enum valuesphysical
A physical card will be printed and shipped. It can be used at physical terminals.
virtual
No physical card will be printed. The card can be used online and can be added to digital wallets.
- cardholderstringRequired
The Cardholder object with which the card will be associated.
- metadataobject
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
. - statusenum
Whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to
inactive
.Possible enum valuesactive
The card can approve authorizations. If the card is linked to a cardholder with past-due requirements, you may be unable to change the card’s status to ‘active’.
inactive
The card will decline authorizations with the
card_inactive
reason.
More parameters
- personalization_
designstringPreview feature - pinobject
- replacement_
forstring - replacement_
reasonenum - second_
linestring - shippingobject
- spending_
controlsobject
Returns
Returns an Issuing Card
object if creation succeeds.
{
"id": "ic_1MvSieLkdIwHu7ixn6uuO0Xu",
"object": "issuing.card",
"brand": "Visa",
"cancellation_reason": null,
"cardholder": {
"id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
"object": "issuing.cardholder",
"billing": {
"address": {
"city": "Anytown",
"country": "US",
"line1": "123 Main Street",
"line2": null,
"postal_code": "12345",
"state": "CA"
}
},
"company": null,
"created": 1680415995,
"email": null,
"individual": null,
"livemode": false,
"metadata": {},
"name": "John Doe",
"phone_number": null,
"requirements": {
"disabled_reason": "requirements.past_due",
"past_due": [
"individual.card_issuing.user_terms_acceptance.ip",
"individual.card_issuing.user_terms_acceptance.date",
"individual.first_name",
"individual.last_name"
]
},
"spending_controls": {
"allowed_categories": [],
"blocked_categories": [],
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "individual"
},
"created": 1681163868,
"currency": "usd",
"exp_month": 8,
"exp_year": 2024,
"last4": "4242",
"livemode": false,
"metadata": {},
"replaced_by": null,
"replacement_for": null,
"replacement_reason": null,
"shipping": null,
"spending_controls": {
"allowed_categories": null,
"blocked_categories": null,
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "virtual",
"wallets": {
"apple_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"google_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"primary_account_identifier": null
}
}
Update a card
Updates the specified Issuing Card
object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
Parameters
- cancellation_
reasonenum Reason why the
status
of this card iscanceled
.Possible enum valueslost
The card was lost.
stolen
The card was stolen.
- metadataobject
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
. - statusenum
Dictates whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to
inactive
. If this card is being canceled because it was lost or stolen, this information should be provided ascancellation_reason
.Possible enum valuesactive
The card can approve authorizations. If the card is linked to a cardholder with past-due requirements, you may be unable to change the card’s status to ‘active’.
canceled
The card will decline authorizations, and no authorization object will be recorded. This status is permanent.
inactive
The card will decline authorizations with the
card_inactive
reason.
More parameters
- pinobject
- spending_
controlsobject
Returns
Returns an updated Issuing Card
object if a valid identifier was provided.
{
"id": "ic_1MvSieLkdIwHu7ixn6uuO0Xu",
"object": "issuing.card",
"brand": "Visa",
"cancellation_reason": null,
"cardholder": {
"id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
"object": "issuing.cardholder",
"billing": {
"address": {
"city": "Anytown",
"country": "US",
"line1": "123 Main Street",
"line2": null,
"postal_code": "12345",
"state": "CA"
}
},
"company": null,
"created": 1680415995,
"email": null,
"individual": null,
"livemode": false,
"metadata": {},
"name": "John Doe",
"phone_number": null,
"requirements": {
"disabled_reason": "requirements.past_due",
"past_due": [
"individual.card_issuing.user_terms_acceptance.ip",
"individual.card_issuing.user_terms_acceptance.date",
"individual.first_name",
"individual.last_name"
]
},
"spending_controls": {
"allowed_categories": [],
"blocked_categories": [],
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "individual"
},
"created": 1681163868,
"currency": "usd",
"exp_month": 8,
"exp_year": 2024,
"last4": "4242",
"livemode": false,
"metadata": {
"order_id": "6735"
},
"replaced_by": null,
"replacement_for": null,
"replacement_reason": null,
"shipping": null,
"spending_controls": {
"allowed_categories": null,
"blocked_categories": null,
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "virtual",
"wallets": {
"apple_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"google_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"primary_account_identifier": null
}
}
Retrieve a card
Retrieves an Issuing Card
object.
Parameters
No parameters.
Returns
Returns an Issuing Card
object if a valid identifier was provided. When requesting the ID of a card that has been deleted, a subset of the card’s information will be returned, including a deleted
property, which will be true.
{
"id": "ic_1MvSieLkdIwHu7ixn6uuO0Xu",
"object": "issuing.card",
"brand": "Visa",
"cancellation_reason": null,
"cardholder": {
"id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
"object": "issuing.cardholder",
"billing": {
"address": {
"city": "Anytown",
"country": "US",
"line1": "123 Main Street",
"line2": null,
"postal_code": "12345",
"state": "CA"
}
},
"company": null,
"created": 1680415995,
"email": null,
"individual": null,
"livemode": false,
"metadata": {},
"name": "John Doe",
"phone_number": null,
"requirements": {
"disabled_reason": "requirements.past_due",
"past_due": [
"individual.card_issuing.user_terms_acceptance.ip",
"individual.card_issuing.user_terms_acceptance.date",
"individual.first_name",
"individual.last_name"
]
},
"spending_controls": {
"allowed_categories": [],
"blocked_categories": [],
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "individual"
},
"created": 1681163868,
"currency": "usd",
"exp_month": 8,
"exp_year": 2024,
"last4": "4242",
"livemode": false,
"metadata": {},
"replaced_by": null,
"replacement_for": null,
"replacement_reason": null,
"shipping": null,
"spending_controls": {
"allowed_categories": null,
"blocked_categories": null,
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "virtual",
"wallets": {
"apple_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"google_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"primary_account_identifier": null
}
}
List all cards
Returns a list of Issuing Card
objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first.
Parameters
- cardholderstring
Only return cards belonging to the Cardholder with the provided ID.
- typeenum
Only return cards that have the given type. One of
virtual
orphysical
.Possible enum valuesphysical
A physical card will be printed and shipped. It can be used at physical terminals.
virtual
No physical card will be printed. The card can be used online and can be added to digital wallets.
More parameters
- createdobject
- ending_
beforestring - exp_
monthinteger - exp_
yearinteger - last4string
- limitinteger
- starting_
afterstring - statusenum
Returns
A dictionary with a data
property that contains an array of up to limit
cards, starting after card starting_after
. Each entry in the array is a separate Issuing Card
object. If no more cards are available, the resulting array will be empty.
{
"object": "list",
"url": "/v1/issuing/cards",
"has_more": false,
"data": [
{
"id": "ic_1MvSieLkdIwHu7ixn6uuO0Xu",
"object": "issuing.card",
"brand": "Visa",
"cancellation_reason": null,
"cardholder": {
"id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
"object": "issuing.cardholder",
"billing": {
"address": {
"city": "Anytown",
"country": "US",
"line1": "123 Main Street",
"line2": null,
"postal_code": "12345",
"state": "CA"
}
},
"company": null,
"created": 1680415995,
"email": null,
"individual": null,
"livemode": false,
"metadata": {},
"name": "John Doe",
"phone_number": null,
"requirements": {
"disabled_reason": "requirements.past_due",
"past_due": [
"individual.card_issuing.user_terms_acceptance.ip",
"individual.card_issuing.user_terms_acceptance.date",
"individual.first_name",
"individual.last_name"
]
},
"spending_controls": {
"allowed_categories": [],
"blocked_categories": [],
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "individual"
},
"created": 1681163868,
"currency": "usd",
"exp_month": 8,
"exp_year": 2024,
"last4": "4242",
"livemode": false,
"metadata": {},
"replaced_by": null,
"replacement_for": null,
"replacement_reason": null,
"shipping": null,
"spending_controls": {
"allowed_categories": null,
"blocked_categories": null,
"spending_limits": [],
"spending_limits_currency": null
},
"status": "active",
"type": "virtual",
"wallets": {
"apple_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"google_pay": {
"eligible": false,
"ineligible_reason": "missing_cardholder_contact"
},
"primary_account_identifier": null
}
}
{...}
{...}
],
}