Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks
Sandboxes

Cardholders 

An Issuing Cardholder object represents an individual or business entity who is issued cards.

Related guide: How to create a cardholder

Endpoints

The Cardholder object 

Attributes

  • idstring

    Unique identifier for the object.

  • billingobject

    The cardholder’s billing information.

  • 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

  • objectstring

  • companynullable object

  • createdtimestamp

  • individualnullable object

  • livemodeboolean

  • preferred_localesnullable array of enums

  • requirementsobject

  • spending_controlsnullable object

  • statusenum

  • typeenum

The Cardholder object
{
  "id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
  "object": "issuing.cardholder",
  "billing": {
    "address": {
      "line1": "1234 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94111"
    }
  },
  "company": null,
  "created": 1680415995,
  "email": "jenny.rosen@example.com",
  "individual": null,
  "livemode": false,
  "metadata": {},
  "name": "Jenny Rosen",
  "phone_number": "+18888675309",
  "redaction": 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"
}

Create a cardholder 

Creates a new Issuing Cardholder object that can be issued cards.

Parameters

  • billingobjectRequired

    The cardholder’s billing address.

  • namestringRequired

    The cardholder’s name. This will be printed on cards issued to them. The maximum length of this field is 24 characters. This field cannot contain any special characters or numbers.

  • emailstring

    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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • phone_numberstring

    The cardholder’s phone number. This will be transformed to E.164 if it is not provided in that format already. This is required for all cardholders who will be creating EU cards. See the 3D Secure documentation for more details.

More parameters

  • companyobject

  • individualobject

  • preferred_localesarray of enums

  • spending_controlsobject

  • statusenum

  • typeenum

Returns

Returns an Issuing Cardholder object if creation succeeds.

POST /v1/issuing/cardholders
curl https://api.stripe.com/v1/issuing/cardholders \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d type=individual \
  -d name="Jenny Rosen" \
  --data-urlencode email="jenny.rosen@example.com" \
  --data-urlencode phone_number="+18888675309" \
  -d "billing[address][line1]"="1234 Main Street" \
  -d "billing[address][city]"="San Francisco" \
  -d "billing[address][state]"=CA \
  -d "billing[address][country]"=US \
  -d "billing[address][postal_code]"=94111
Response
{
  "id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
  "object": "issuing.cardholder",
  "billing": {
    "address": {
      "line1": "1234 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94111"
    }
  },
  "company": null,
  "created": 1680415995,
  "email": "jenny.rosen@example.com",
  "individual": null,
  "livemode": false,
  "metadata": {},
  "name": "Jenny Rosen",
  "phone_number": "+18888675309",
  "redaction": 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"
}

Update a cardholder 

Updates the specified Issuing Cardholder object by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Parameters

  • billingobject

    The cardholder’s billing address.

  • emailstring

    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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • phone_numberstring

    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 parameters

  • companyobject

  • individualobject

  • preferred_localesarray of enums

  • spending_controlsobject

  • statusenum

Returns

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

POST /v1/issuing/cardholders/:id
curl https://api.stripe.com/v1/issuing/cardholders/ich_1MsKAB2eZvKYlo2C3eZ2BdvK \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "metadata[order_id]"=6735
Response
{
  "id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
  "object": "issuing.cardholder",
  "billing": {
    "address": {
      "line1": "1234 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94111"
    }
  },
  "company": null,
  "created": 1680415995,
  "email": "jenny.rosen@example.com",
  "individual": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "name": "Jenny Rosen",
  "phone_number": "+18888675309",
  "redaction": 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"
}

Retrieve a cardholder 

Retrieves an Issuing Cardholder object.

Parameters

No parameters.

Returns

Returns an Issuing Cardholder object if a valid identifier was provided.

GET /v1/issuing/cardholders/:id
curl https://api.stripe.com/v1/issuing/cardholders/ich_1MsKAB2eZvKYlo2C3eZ2BdvK \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "ich_1MsKAB2eZvKYlo2C3eZ2BdvK",
  "object": "issuing.cardholder",
  "billing": {
    "address": {
      "line1": "1234 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94111"
    }
  },
  "company": null,
  "created": 1680415995,
  "email": "jenny.rosen@example.com",
  "individual": null,
  "livemode": false,
  "metadata": {},
  "name": "Jenny Rosen",
  "phone_number": "+18888675309",
  "redaction": 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"
}