Update a card

Issuing

Cards

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
The desired new PIN for this card.
- pin.encrypted_numberstring
  The card’s desired new PIN, encrypted under Stripe’s public key.

shippingobject

Updated shipping information for the card.

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 updated Issuing Card object if a valid identifier was provided.

POST /v1/issuing/cards/:id

Server-side language

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

Update a card

Parameters

cancellation_reasonenum

metadataobject

statusenum

More parametersCollapse all

pinobject

pin.encrypted_numberstring

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