The Card object

Issuing

Cards

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.

cardholder.idstring
Unique identifier for the object.

cardholder.objectstring
String representing the object’s type. Objects of the same type share the same value.

cardholder.billingobject
The cardholder’s billing information.
- cardholder.billing.addressobject
  The cardholder’s billing address.
  cardholder.billing.address.citynullable string
  City, district, suburb, town, or village.
  cardholder.billing.address.countrynullable string
  Two-letter country code (ISO 3166-1 alpha-2).
  cardholder.billing.address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
  cardholder.billing.address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
  cardholder.billing.address.postal_codenullable string
  ZIP or postal code.
  cardholder.billing.address.statenullable string
  State, county, province, or region.

cardholder.companynullable object
Additional information about a company cardholder.
- cardholder.company.tax_id_providedboolean
  Whether the company’s business ID number was provided.

cardholder.createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.

cardholder.emailnullable string
The cardholder’s email address.

cardholder.individualnullable object
Additional information about an individual cardholder.
- cardholder.individual.card_issuingnullable object
  Information related to the card_issuing program for this cardholder.
  cardholder.individual.card_issuing.user_terms_acceptancenullable object
  Information about cardholder acceptance of Celtic Authorized User Terms. Required for cards backed by a Celtic program.
  cardholder.individual.card_issuing.user_terms_acceptance.datenullable timestamp
  The Unix timestamp marking when the cardholder accepted the Authorized User Terms.
  cardholder.individual.card_issuing.user_terms_acceptance.ipnullable string
  The IP address from which the cardholder accepted the Authorized User Terms.
  cardholder.individual.card_issuing.user_terms_acceptance.user_agentnullable string
  The user agent of the browser from which the cardholder accepted the Authorized User Terms.
- cardholder.individual.dobnullable object
  The date of birth of this cardholder.
  cardholder.individual.dob.daynullable integer
  The day of birth, between 1 and 31.
  cardholder.individual.dob.monthnullable integer
  The month of birth, between 1 and 12.
  cardholder.individual.dob.yearnullable integer
  The four-digit year of birth.
- cardholder.individual.first_namenullable string
  The first name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters.
- cardholder.individual.last_namenullable string
  The last name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters.
- cardholder.individual.verificationnullable object
  Government-issued ID document for this cardholder.
  cardholder.individual.verification.documentnullable object
  An identifying document, either a passport or local ID card.
  cardholder.individual.verification.document.backnullable stringExpandable
  The back of a document returned by a file upload with a purpose value of identity_document.
  cardholder.individual.verification.document.frontnullable stringExpandable
  The front of a document returned by a file upload with a purpose value of identity_document.

cardholder.livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

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

cardholder.namestring
The cardholder’s name. This will be printed on cards issued to them.

cardholder.phone_numbernullable string
The cardholder’s phone number. This is required for all cardholders who will be creating EU cards. See the 3D Secure documentation for more details.

cardholder.preferred_localesnullable array of enums
The cardholder’s preferred locales (languages), ordered by preference. Locales can be de, en, es, fr, or it. This changes the language of the 3D Secure flow and one-time password messages sent to the cardholder.

cardholder.requirementsobject

Information about verification requirements for the cardholder.

cardholder.requirements.disabled_reasonnullable enum

If disabled_reason is present, all cards will decline authorizations with cardholder_verification_required reason.

Possible enum values

listed

Account might be on a prohibited persons or companies list. The past_due field contains information that you need to provide before the cardholder can approve authorizations.

rejected.listed

Cardholder is rejected because they are on a third-party prohibited persons or companies list (such as financial services provider or government). Their status will be blocked.

requirements.past_due

Cardholder has outstanding requirements. The past_due field contains information that you need to provide before the cardholder can activate cards.

under_review

This cardholder has raised additional review. Stripe will make a decision and update the disabled_reason field.

cardholder.requirements.past_duenullable array of enums

Array of fields that need to be collected in order to verify and re-enable the cardholder.

Possible enum values

company.tax_id

The cardholder’s business number (Tax ID).

individual.card_issuing.user_terms_acceptance.date

The Unix timestamp marking when the Cardholder accepted their Authorized User Terms. Required for Celtic Spend Card users.

individual.card_issuing.user_terms_acceptance.ip

The IP address from which the Cardholder accepted their Authorized User Terms. Required for Celtic Spend Card users.

individual.dob.day

The cardholder’s date of birth’s day.

individual.dob.month

The cardholder’s date of birth’s month.

individual.dob.year

The cardholder’s date of birth’s year.

individual.first_name

The cardholder’s legal first name.

individual.last_name

The cardholder’s legal last name.

individual.verification.document

The front and back of a government-issued form of identification.

cardholder.spending_controlsnullable object

Rules that control spending across this cardholder’s cards. Refer to our documentation for more details.

cardholder.spending_controls.allowed_categoriesnullable array of enums

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

Possible enum values

ac_refrigeration_repair

accounting_bookkeeping_services

advertising_services

agricultural_cooperative

airlines_air_carriers

airports_flying_fields

ambulance_services

amusement_parks_carnivals

antique_reproductions

antique_shops

Show 285 more

cardholder.spending_controls.allowed_merchant_countriesnullable array 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.

cardholder.spending_controls.blocked_categoriesnullable array of enums

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

Possible enum values

ac_refrigeration_repair

accounting_bookkeeping_services

advertising_services

agricultural_cooperative

airlines_air_carriers

airports_flying_fields

ambulance_services

amusement_parks_carnivals

antique_reproductions

antique_shops

Show 285 more

cardholder.spending_controls.blocked_merchant_countriesnullable array 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.

cardholder.spending_controls.spending_limitsnullable array of objects

Limit spending with amount-based rules that apply across this cardholder’s cards.

cardholder.spending_controls.spending_limits.amountinteger
Maximum amount allowed to spend per interval. This amount is in the card’s currency and in the smallest currency unit.

cardholder.spending_controls.spending_limits.categoriesnullable array of enums

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

Possible enum values

ac_refrigeration_repair

accounting_bookkeeping_services

advertising_services

agricultural_cooperative

airlines_air_carriers

airports_flying_fields

ambulance_services

amusement_parks_carnivals

antique_reproductions

antique_shops

Show 285 more

cardholder.spending_controls.spending_limits.intervalenum

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.

cardholder.spending_controls.spending_limits_currencynullable enum
Currency of the amounts within spending_limits.

cardholder.statusenum

Specifies whether to permit authorizations on this cardholder’s cards.

Possible enum values

active

Cards attached to this cardholder can approve authorizations.

blocked

Cards attached to this cardholder will decline all authorizations with the cardholder_blocked reason. This status is non-reversible.

inactive

Cards attached to this cardholder will decline all authorizations with the cardholder_inactive reason.

cardholder.typeenum

One of individual or company. See Choose a cardholder type for more details.

Possible enum values

company

The cardholder is a company or business entity, and additional information includes their tax ID. This option may not be available if your use case only supports individual cardholders.

individual

The cardholder is a person, and additional information includes first and last name, date of birth, etc. If you’re issuing Celtic Spend Cards, then Individual cardholders must accept Authorized User Terms prior to activating their card.

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
String representing the object’s type. Objects of the same type share the same value.

brandstring
The brand of the card.

createdtimestamp
Time at which the object was created. Measured in seconds since the Unix epoch.

cvcnullable stringExpandable
The card’s CVC. For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with the expand parameter. Additionally, it’s only available via the “Retrieve a card” endpoint, not via “List all cards” or any other endpoint.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

numbernullable stringExpandable
The full unredacted card number. For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with the expand parameter. Additionally, it’s only available via the “Retrieve a card” endpoint, not via “List all cards” or any other endpoint.

personalization_designnullable stringExpandable
The personalization design object belonging to this card.

replaced_bynullable stringExpandable
The latest card that replaces this card, if any.

replacement_fornullable stringExpandable
The card this card replaces, if any.

replacement_reasonnullable enum

The reason why the previous card needed to be 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.

shippingnullable object

Where and how the card will be shipped.

shipping.addressobject
Shipping address.
- shipping.address.citynullable string
  City, district, suburb, town, or village.
- shipping.address.countrynullable string
  Two-letter country code (ISO 3166-1 alpha-2).
- shipping.address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
- shipping.address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
- shipping.address.postal_codenullable string
  ZIP or postal code.
- shipping.address.statenullable string
  State, county, province, or region.

shipping.address_validationnullable object

Address validation details for the shipment.

shipping.address_validation.modeenum

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.address_validation.normalized_addressnullable object
The normalized shipping address.
- shipping.address_validation.normalized_address.citynullable string
  City, district, suburb, town, or village.
- shipping.address_validation.normalized_address.countrynullable string
  Two-letter country code (ISO 3166-1 alpha-2).
- shipping.address_validation.normalized_address.line1nullable string
  Address line 1 (e.g., street, PO Box, or company name).
- shipping.address_validation.normalized_address.line2nullable string
  Address line 2 (e.g., apartment, suite, unit, or building).
- shipping.address_validation.normalized_address.postal_codenullable string
  ZIP or postal code.
- shipping.address_validation.normalized_address.statenullable string
  State, county, province, or region.

shipping.address_validation.resultnullable enum

The validation result for the shipping address.

Possible enum values

indeterminate

The deliverability of the card’s shipping address could not be determined.

likely_deliverable

The card’s shipping address is likely deliverable.

likely_undeliverable

The card’s shipping address is likely undeliverable as submitted.

shipping.carriernullable enum
The delivery company that shipped a card.
Possible enum values
dhl
DHL
fedex
FedEx
royal_mail
Royal Mail
usps
USPS

shipping.customsnullable object
Additional information that may be required for clearing customs.
- shipping.customs.eori_numbernullable string
  A registration number used for customs in Europe. See https://www.gov.uk/eori for the UK and https://ec.europa.eu/taxation_customs/business/customs-procedures-import-and-export/customs-procedures/economic-operators-registration-and-identification-number-eori_en for the EU.

shipping.etanullable timestamp
A unix timestamp representing a best estimate of when the card will be delivered.

shipping.namestring
Recipient name.

shipping.phone_numbernullable string
The phone number of the receiver of the shipment. Our courier partners will use this number to contact you in the event of card delivery issues. For individual shipments to the EU/UK, if this field is empty, we will provide them with the phone number provided when the cardholder was initially created.

shipping.require_signaturenullable boolean
Whether a signature is required for card delivery. This feature is only supported for US users. Standard shipping service does not support signature on delivery. The default value for standard shipping service is false and for express and priority services is true.

shipping.serviceenum
Shipment service, such as standard or express.
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.statusnullable enum

The delivery status of the card.

Possible enum values

canceled

The card was canceled before being shipped.

delivered

The card has been delivered to its destination.

failure

The card failed to be delivered but was not returned.

pending

The card is being prepared and has not yet shipped.

returned

The card failed to be delivered and was returned to the sender.

shipped

The card has been shipped. If the card’s shipping carrier does not support tracking, this will be the card’s final status.

submitted

The card has been submitted to the printer for shipment.

shipping.tracking_numbernullable string
A tracking number for a card shipment.

shipping.tracking_urlnullable string
A link to the shipping carrier’s site where you can view detailed information about a card shipment.

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_categoriesnullable array of enums

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

Possible enum values

ac_refrigeration_repair

accounting_bookkeeping_services

advertising_services

agricultural_cooperative

airlines_air_carriers

airports_flying_fields

ambulance_services

amusement_parks_carnivals

antique_reproductions

antique_shops

Show 285 more

spending_controls.allowed_merchant_countriesnullable array 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_categoriesnullable array of enums

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

Possible enum values

ac_refrigeration_repair

accounting_bookkeeping_services

advertising_services

agricultural_cooperative

airlines_air_carriers

airports_flying_fields

ambulance_services

amusement_parks_carnivals

antique_reproductions

antique_shops

Show 285 more

spending_controls.blocked_merchant_countriesnullable array 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_limitsnullable array 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.amountinteger
Maximum amount allowed to spend per interval. This amount is in the card’s currency and in the smallest currency unit.

spending_controls.spending_limits.categoriesnullable array of enums

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

Possible enum values

ac_refrigeration_repair

accounting_bookkeeping_services

advertising_services

agricultural_cooperative

airlines_air_carriers

airports_flying_fields

ambulance_services

amusement_parks_carnivals

antique_reproductions

antique_shops

Show 285 more

spending_controls.spending_limits.intervalenum

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_currencynullable enum
Currency of the amounts within spending_limits. Always the same as the currency of the card.

walletsnullable object

Information relating to digital wallets (like Apple Pay and Google Pay).

wallets.apple_payobject

Apple Pay Details

wallets.apple_pay.eligibleboolean
Apple Pay Eligibility

wallets.apple_pay.ineligible_reasonnullable enum

Reason the card is ineligible for Apple Pay

Possible enum values

missing_agreement

Apple Pay is not enabled for your account.

missing_cardholder_contact

Cardholder phone number or email required.

unsupported_region

Apple Pay is not supported in the cardholder’s country.

wallets.google_payobject

Google Pay Details

wallets.google_pay.eligibleboolean
Google Pay Eligibility

wallets.google_pay.ineligible_reasonnullable enum

Reason the card is ineligible for Google Pay

Possible enum values

missing_agreement

Google Pay is not enabled for your account.

missing_cardholder_contact

Cardholder phone number or email required.

unsupported_region

Google Pay is not supported in the cardholder’s country.

wallets.primary_account_identifiernullable string
Unique identifier for a card used with digital wallets

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

The Card object

Attributes

idstring

cancellation_reasonnullable enum

cardholderobject

cardholder.idstring

cardholder.objectstring

cardholder.billingobject

cardholder.billing.addressobject

cardholder.billing.address.citynullable string

cardholder.billing.address.countrynullable string

cardholder.billing.address.line1nullable string

cardholder.billing.address.line2nullable string

cardholder.billing.address.postal_codenullable string

cardholder.billing.address.statenullable string

cardholder.companynullable object

cardholder.company.tax_id_providedboolean

cardholder.createdtimestamp

cardholder.emailnullable string

cardholder.individualnullable object

cardholder.individual.card_issuingnullable object

cardholder.individual.card_issuing.user_terms_acceptancenullable object

cardholder.individual.card_issuing.user_terms_acceptance.datenullable timestamp

cardholder.individual.card_issuing.user_terms_acceptance.ipnullable string

cardholder.individual.card_issuing.user_terms_acceptance.user_agentnullable string

cardholder.individual.dobnullable object

cardholder.individual.dob.daynullable integer

cardholder.individual.dob.monthnullable integer

cardholder.individual.dob.yearnullable integer

cardholder.individual.first_namenullable string

cardholder.individual.last_namenullable string

cardholder.individual.verificationnullable object

cardholder.individual.verification.documentnullable object

cardholder.individual.verification.document.backnullable stringExpandable

cardholder.individual.verification.document.frontnullable stringExpandable

cardholder.livemodeboolean

cardholder.metadataobject

cardholder.namestring

cardholder.phone_numbernullable string

cardholder.preferred_localesnullable array of enums

cardholder.requirementsobject

cardholder.requirements.disabled_reasonnullable enum

cardholder.requirements.past_duenullable array of enums

cardholder.spending_controlsnullable object

cardholder.spending_controls.allowed_categoriesnullable array of enums

cardholder.spending_controls.allowed_merchant_countriesnullable array of strings

cardholder.spending_controls.blocked_categoriesnullable array of enums

cardholder.spending_controls.blocked_merchant_countriesnullable array of strings

cardholder.spending_controls.spending_limitsnullable array of objects

cardholder.spending_controls.spending_limits.amountinteger

cardholder.spending_controls.spending_limits.categoriesnullable array of enums

cardholder.spending_controls.spending_limits.intervalenum

cardholder.spending_controls.spending_limits_currencynullable enum

cardholder.statusenum

cardholder.typeenum

currencyenum

exp_monthinteger

exp_yearinteger

last4string

metadataobject

statusenum

typeenum

More attributesCollapse all

objectstring

brandstring

createdtimestamp

cvcnullable stringExpandable

livemodeboolean

numbernullable stringExpandable

personalization_designnullable stringExpandable

replaced_bynullable stringExpandable

replacement_fornullable stringExpandable

replacement_reasonnullable enum

shippingnullable object

shipping.addressobject

shipping.address.citynullable string

shipping.address.countrynullable string

shipping.address.line1nullable string

shipping.address.line2nullable string

shipping.address.postal_codenullable string

More attributes