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

idstring
Unique identifier for the object.

cancellation_reasonnullable 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.

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, and gbp 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 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.

typeenum
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

objectstring

brandstring

createdtimestamp

cvcnullable stringExpandable

latest_fraud_warningnullable object

lifecycle_controlsnullable object

livemodeboolean

numbernullable stringExpandable

personalization_designnullable stringExpandable

replaced_bynullable stringExpandable

replacement_fornullable stringExpandable

replacement_reasonnullable enum

second_linenullable string

shippingnullable object

spending_controlsobject

walletsnullable 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

currencystringRequired
The currency for the card.

typeenumRequired
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.

cardholderstringRequired
The Cardholder object with which the card will be associated.

exp_monthinteger
The desired expiration month (1-12) for this card if specifying a custom expiration date.

exp_yearinteger
The desired 4-digit expiration year for this card if specifying a custom expiration date.

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 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_controlsobject

personalization_designstring

pinobject

replacement_forstring

replacement_reasonenum

second_linestring

shippingobject

spending_controlsobject

Returns

Returns an Issuing Card object if creation succeeds.

curl https://api.stripe.com/v1/issuing/cards \
  -u "sk_test_VePHdqK...NInc7u56JBrQsk_test_VePHdqKTYQjKNInc7u56JBrQ:" \
  -d cardholder={{CARDHOLDER_ID}} \
  -d currency=usd \
  -d type=virtual

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

Cards

The Card object

Attributes

idstring

cancellation_reasonnullable enum

cardholderobject

currencyenum

exp_monthinteger

exp_yearinteger

last4string

metadataobject

statusenum

typeenum

More attributesExpand all

objectstring

brandstring

createdtimestamp

cvcnullable stringExpandable

latest_fraud_warningnullable object

lifecycle_controlsnullable object

livemodeboolean

numbernullable stringExpandable

personalization_designnullable stringExpandable

replaced_bynullable stringExpandable

replacement_fornullable stringExpandable

replacement_reasonnullable enum

second_linenullable string

shippingnullable object

spending_controlsobject

walletsnullable object

Create a card

Parameters

currencystringRequired

typeenumRequired

cardholderstringRequired

exp_monthinteger

exp_yearinteger

metadataobject

statusenum

More parametersExpand all

lifecycle_controlsobject

personalization_designstring

pinobject

replacement_forstring

replacement_reasonenum

second_linestring

shippingobject

spending_controlsobject

Returns

More attributes

More parameters