Create a card

Issuing

Cards

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.

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
The personalization design object belonging to this card.

pinobject
The desired PIN for this card.
- pin.encrypted_numberstring
  The card’s desired new PIN, encrypted under Stripe’s public key.

replacement_forstring
The card this is meant to be a replacement for (if any).

replacement_reasonenum

If replacement_for is specified, this should indicate why that card is being replaced.

Possible enum values

damaged

The physical card has been damaged and cannot be used at terminals. This reason is only valid for cards of type physical.

expired

The expiration date has passed or is imminent.

lost

The card was lost. This status is only valid if the card it replaces is marked as lost.

stolen

The card was stolen. This status is only valid if the card it replaces is marked as stolen.

second_linestring
The second line to print on the card. Max length: 24 characters.

shippingobject

The address where the card will be shipped.

shipping.addressobjectRequired
The address that the card is shipped to.
- shipping.address.citystringRequired
  City, district, suburb, town, or village.
- shipping.address.countrystringRequired
  Two-letter country code (ISO 3166-1 alpha-2).
- shipping.address.line1stringRequired
  Address line 1 (e.g., street, PO Box, or company name).
- shipping.address.postal_codestringRequired
  ZIP or postal code.
- shipping.address.line2string
  Address line 2 (e.g., apartment, suite, unit, or building).
- shipping.address.statestring
  State, county, province, or region.

shipping.namestringRequired
The name printed on the shipping label when shipping the card.

shipping.address_validationobject

Address validation settings.

shipping.address_validation.modeenumRequired

The address validation capabilities to use.

Possible enum values

disabled

The card will be shipped without validating or normalizing the shipping address.

normalization_only

The card will be shipped with the normalized address without validation. Undeliverable addresses won’t be blocked.

validation_and_normalization

The card will be shipped with the normalized, validated address. Undeliverable addresses will be blocked.

shipping.customsobject
Customs information for the shipment.
- shipping.customs.eori_numberstring
  The Economic Operators Registration and Identification (EORI) number to use for Customs. Required for bulk shipments to Europe.

shipping.phone_numberstring
Phone number of the recipient of the shipment.

shipping.require_signatureboolean
Whether a signature is required for card delivery.

shipping.serviceenum
Shipment service.
Possible enum values
express
Cards arrive in 4 business days.
priority
Cards arrive in 2-3 business days.
standard
Cards arrive in 5-8 business days.

shipping.typeenum
Packaging options.
Possible enum values
bulk
Cards are grouped and mailed together.
individual
Cards are sent individually in an envelope.

spending_controlsobject

Rules that control spending for this card. Refer to our documentation for more details.

spending_controls.allowed_categoriesarray of strings
Array of strings containing categories of authorizations to allow. All other categories will be blocked. Cannot be set with blocked_categories.

spending_controls.allowed_merchant_countriesarray of strings
Array of strings containing representing countries from which authorizations will be allowed. Authorizations from merchants in all other countries will be declined. Country codes should be ISO 3166 alpha-2 country codes (e.g. US). Cannot be set with blocked_merchant_countries. Provide an empty value to unset this control.

spending_controls.blocked_categoriesarray of strings
Array of strings containing categories of authorizations to decline. All other categories will be allowed. Cannot be set with allowed_categories.

spending_controls.blocked_merchant_countriesarray of strings
Array of strings containing representing countries from which authorizations will be declined. Country codes should be ISO 3166 alpha-2 country codes (e.g. US). Cannot be set with allowed_merchant_countries. Provide an empty value to unset this control.

spending_controls.spending_limitsarray of objects

Limit spending with amount-based rules that apply across any cards this card replaced (i.e., its replacement_for card and that card’s replacement_for card, up the chain).

spending_controls.spending_limits.amountintegerRequired
Maximum amount allowed to spend per interval.

spending_controls.spending_limits.intervalenumRequired

Interval (or event) to which the amount applies.

Possible enum values

all_time

Limit applies to all transactions.

daily

Limit applies to a day, starting at midnight UTC.

monthly

Limit applies to a month, starting on the 1st at midnight UTC.

per_authorization

Limit applies to each authorization.

weekly

Limit applies to a week, starting on Sunday at midnight UTC.

yearly

Limit applies to a year, starting on January 1st at midnight UTC.

spending_controls.spending_limits.categoriesarray of strings
Array of strings containing categories this limit applies to. Omitting this field will apply the limit to all categories.

Returns

Returns an Issuing Card object if creation succeeds.

POST /v1/issuing/cards

Server-side language

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

Create a card

Parameters

currencystringRequired

typeenumRequired

cardholderstringRequired

metadataobject

statusenum

More parametersCollapse all

personalization_designstring

pinobject

pin.encrypted_numberstring

replacement_forstring

replacement_reasonenum

second_linestring

shippingobject

shipping.addressobjectRequired

shipping.address.citystringRequired

shipping.address.countrystringRequired

shipping.address.line1stringRequired

shipping.address.postal_codestringRequired

shipping.address.line2string

shipping.address.statestring

shipping.namestringRequired

shipping.address_validationobject

shipping.address_validation.modeenumRequired

shipping.customsobject

shipping.customs.eori_numberstring

shipping.phone_numberstring

shipping.require_signatureboolean

shipping.serviceenum

shipping.typeenum

spending_controlsobject

spending_controls.allowed_categoriesarray of strings

spending_controls.allowed_merchant_countriesarray of strings

spending_controls.blocked_categoriesarray of strings

spending_controls.blocked_merchant_countriesarray of strings

spending_controls.spending_limitsarray of objects

spending_controls.spending_limits.amountintegerRequired

spending_controls.spending_limits.intervalenumRequired

spending_controls.spending_limits.categoriesarray of strings

Returns

More parameters