Cards

You can create physical or virtual cards that are issued to cardholders.

Was this section helpful? Yes No

Create a card

POST / v1 / issuing / cards

Update a card

POST / v1 / issuing / cards /:id

Retrieve a card

GET / v1 / issuing / cards /:id

List all cards

GET / v1 / issuing / cards

Deliver a testmode card

POST / v1 / test_helpers / issuing / cards /:id / shipping / deliver

Fail a testmode card

POST / v1 / test_helpers / issuing / cards /:id / shipping / fail

Return a testmode card

POST / v1 / test_helpers / issuing / cards /:id / shipping / return

Ship a testmode card

POST / v1 / test_helpers / issuing / cards /:id / shipping / ship

Submit a testmode card

POST / v1 / test_helpers / issuing / cards /:id / shipping / submit

The Card object

Attributes

id string Unique identifier for the object.
cancellation _ reason nullable enum The reason why the card was canceled. Possible enum values design_rejected The design of this card was rejected by Stripe for violating our partner guidelines. fulfillment_error There was an error in fulfilling the card. This reason is only valid for cards of type physical. lost The card was lost. stolen The card was stolen.
cardholder object The Cardholder object to which the card belongs.
currency enum Three-letter ISO currency code, in lowercase. Supported currencies are usd in the US, eur in the EU, and gbp in the UK.
exp _ month integer The expiration month of the card.
exp _ year integer The expiration year of the card.
last4 string The last 4 digits of the card number.
metadata map 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.
status enum 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 values active 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 with the card_canceled reason. This status is permanent. inactive The card will decline authorizations with the card_inactive reason.
type enum The type of the card. Possible enum values physical 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

object string, value is "issuing.card"
brand string
created timestamp
cvc nullable string Includable
latest _ fraud _ warning nullable object
lifecycle _ controls nullable object
livemode boolean
number nullable string Includable
personalization _ design nullable string Expandable
replaced _ by nullable string Expandable
replacement _ for nullable string Expandable
replacement _ reason nullable enum
second _ line nullable string
shipping nullable object
spending _ controls object
wallets nullable object

The Card 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

POST / v1 / issuing / cards

Creates an Issuing Card object.

Parameters

currency string Required The currency for the card.
type enum Required The type of card to issue. Possible values are physical or virtual. Possible enum values physical 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.
cardholder string Required The Cardholder object with which the card will be associated.
exp _ month integer The desired expiration month (1-12) for this card if specifying a custom expiration date.
exp _ year integer The desired 4-digit expiration year for this card if specifying a custom expiration date.
metadata map 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.
status enum 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 values active 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

lifecycle _ controls object
personalization _ design string
pin object
replacement _ for string
replacement _ reason enum
second _ line string
shipping object
spending _ controls object

Returns

Returns an Issuing Card object if creation succeeds.

Response

{ "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 }}