Cards

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

Endpoints

POST/v1/issuing/cards

POST/v1/issuing/cards/:id

GET/v1/issuing/cards/:id

GET/v1/issuing/cards

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

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

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

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

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

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

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

personalization_designstring

pinobject

replacement_forstring

replacement_reasonenum

second_linestring

shippingobject

spending_controlsobject

Returns

Returns an Issuing Card object if creation succeeds.

POST /v1/issuing/cards

curl https://api.stripe.com/v1/issuing/cards \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d cardholder=ich_1MsKAB2eZvKYlo2C3eZ2BdvK \
  -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
  }
}

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 is canceled.
Possible enum values
lost
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 as cancellation_reason.

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.

More parameters

pinobject

shippingobject

spending_controlsobject

Returns

Returns an updated Issuing Card object if a valid identifier was provided.

POST /v1/issuing/cards/:id

curl https://api.stripe.com/v1/issuing/cards/ic_1MvSieLkdIwHu7ixn6uuO0Xu \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "metadata[order_id]"=6735

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": {
    "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.

GET /v1/issuing/cards/:id

curl https://api.stripe.com/v1/issuing/cards/ic_1MvSieLkdIwHu7ixn6uuO0Xu \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

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

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

personalization_designstring

pinobject

replacement_forstring

replacement_reasonenum

second_linestring

shippingobject

spending_controlsobject

Returns

Update a card

Parameters

cancellation_reasonenum

metadataobject

statusenum

More parametersExpand all

pinobject

shippingobject

spending_controlsobject

Returns

Retrieve a card

Parameters

Returns

More attributes

More parameters

More parameters