The Cardholder object 

Attributes

• idstring

  Unique identifier for the object.

• billingobject

  The cardholder’s billing information.

  Hide child attributes

  • billing.addressobject

    The cardholder’s billing address.

    Hide child attributes

    • billing.address.citynullable string

      City, district, suburb, town, or village.

    • billing.address.countrynullable string

      Two-letter country code (ISO 3166-1 alpha-2).

    • billing.address.line1nullable string

      Address line 1 (e.g., street, PO Box, or company name).

    • billing.address.line2nullable string

      Address line 2 (e.g., apartment, suite, unit, or building).

    • billing.address.postal_codenullable string

      ZIP or postal code.

    • billing.address.statenullable string

      State, county, province, or region.

• emailnullable string

  The cardholder’s email address.

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

• namestring

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

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

More attributes

Collapse all

• objectstring

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

• companynullable object

  Additional information about a company cardholder.

  Hide child attributes

  • company.tax_id_providedboolean

    Whether the company’s business ID number was provided.

• createdtimestamp

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

• individualnullable object

  Additional information about an individual cardholder.

  Hide child attributes

  • individual.card_issuingnullable object

    Information related to the card_issuing program for this cardholder.

    Hide child attributes

    • individual.card_issuing.user_terms_acceptancenullable object

      Information about cardholder acceptance of Celtic Authorized User Terms. Required for cards backed by a Celtic program.

      Hide child attributes

      • individual.card_issuing.user_terms_acceptance.datenullable timestamp

        The Unix timestamp marking when the cardholder accepted the Authorized User Terms.

      • individual.card_issuing.user_terms_acceptance.ipnullable string

        The IP address from which the cardholder accepted the Authorized User Terms.

      • individual.card_issuing.user_terms_acceptance.user_agentnullable string

        The user agent of the browser from which the cardholder accepted the Authorized User Terms.

  • individual.dobnullable object

    The date of birth of this cardholder.

    Hide child attributes

    • individual.dob.daynullable integer

      The day of birth, between 1 and 31.

    • individual.dob.monthnullable integer

      The month of birth, between 1 and 12.

    • individual.dob.yearnullable integer

      The four-digit year of birth.

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

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

  • individual.verificationnullable object

    Government-issued ID document for this cardholder.

    Hide child attributes

    • individual.verification.documentnullable object

      An identifying document, either a passport or local ID card.

      Hide child attributes

      • individual.verification.document.backnullable stringExpandable

        The back of a document returned by a file upload with a purpose value of identity_document.

      • individual.verification.document.frontnullable stringExpandable

        The front of a document returned by a file upload with a purpose value of identity_document.

• livemodeboolean

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

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

• requirementsobject

  Information about verification requirements for the cardholder.

  Hide child attributes

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

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

• spending_controlsnullable object

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

  Hide child attributes

  • 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 this cardholder’s cards.

    Hide child attributes

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

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

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