Connected accounts, cardholders, and cards
Learn how to create and manage cardholders and cards with Stripe Connect.
Connected accounts represent business entities. Cardholders represent individuals associated with those business entities. One connected account can have multiple cardholders. For example, a connected account for a small business might have multiple cardholders for the owner and its employees. After you create a cardholder, you issue them a virtual or physical card.
Create cardholders
To create a Cardholder, use the Cardholders API and provide the required information. Using digital wallets requires a valid phone number and email address, but they’re optional for physical cards.
Note
As a Connect platform, you make API calls on behalf of your connected accounts by including a Stripe-Account header and the connected account’s account ID.
| Field | Parameter | Description |
|---|---|---|
| Billing information | billing | Cardholder’s billing address (typically the primary business address). You can’t use a Postal Office (P.O.) box, highway contract box, or private mailbox address, but you can use them as a card shipping address. |
| Type | type | Whether the cardholder is a company or individual. See Choose a cardholder type for guidance. |
| Phone number | phone_ | Required if using digital wallets |
email | Email address of the cardholder. Required if using digital wallets |
Stripe returns a Cardholder object that contains the information you provided and sends the issuing_ webhook event.
Stripe must screen cardholder identity information in accordance with legal and regulatory guidelines. This can block authorisations based on cardholder attributes. Learn more about watchlist reviews.
After you create a Cardholder, call the Cardholder update endpoint with the parameters that you need to change. A successful call returns an updated Cardholder object.
Cardholders have a default active status, which means that any cards attached to the cardholder can approve authorisations. You can change the status to inactive by updating the cardholder. An inactive status on a Cardholder means all authorisations will be declined for any attached cards with a reason of cardholder_.
Create cards
After you create a Cardholder, issue them a card with the Cards API.
A Card object represents a physical card or virtual card. Creating a physical card requires a shipping address, and you can provide additional arguments to specify shipment packaging and delivery service.
| Cardholder | cardholder | Cardholder’s ID |
|---|---|---|
| Currency | currency | Three-letter ISO currency code, in lowercase. Supported currencies are usd in the US, gbp in the UK, and eur in euro area counties. |
| Type | type | Can be physical or virtual |
The following call is an example of issuing a virtual card attached to the specified Cardholder:
Stripe returns a Card object upon creation and sends the issuing_ webhook event.
Activate cards
Cards must be activated before authorisations are approved.
If you don’t specify a status when you create the card, the card has the default status of inactive. A card remains inactive until the status is changed with the Card update endpoint.
To activate a card:
Deactivating cards
You can deactivate cards by setting the status to inactive with Card update endpoint. This means you can’t approve any new authorisations for the card. You can still approve authorisations that were opened on the card before the status was set to inactive. To approve any new authorisations, you need to change the status of the card to active.
Learn more about Managing authorisations.
Cancel cards
You can cancel a card by changing the status to canceled with the Card update endpoint. The cancelled status is terminal and you can’t revert it. You can’t approve new authorisations for a card with a canceled status. You can still approve authorisations that were opened on the card before the status was set to canceled.
Listing Cardholders
Find cardholders associated with a connected account by making a Cardholders API GET request and passing the specific Stripe-Account into the header.
If successful, the response contains a list of cardholders:
{ "object": "list", "data": [ { "id": "ich_1234a", "object": "issuing.cardholder", "billing": { "address": { "city": "San Francisco", "country": "US", "line1": "510 Townsend Street", "line2": null, "postal_code": "94111", "state": "CA" } }, "company": null, "created": 1657144326, "email": "jenny.rosen@example.com", "individual": null, "livemode": false, "metadata": {}, "name": "Jenny Rosen", "phone_number": "+18008675309", "requirements": { "disabled_reason": null, "past_due": [] }, "spending_controls": { "allowed_categories": [], "blocked_categories": [], "spending_limits": [], "spending_limits_currency": null }, "status": "active", "type": "individual" }, { "id": "ich_1234b", "object": "issuing.cardholder", "billing": { "address": { "city": "San Francisco", "country": "US", "line1": "510 Townsend Street", "line2": null, "postal_code": "94111", "state": "CA" } }, "company": null, "created": 1656537695, "email": "jenny.rosen@example.com", "individual": null, "livemode": false, "metadata": {}, "name": "Jenny Rosen", "phone_number": "+18008675309", "requirements": { "disabled_reason": null, "past_due": [] }, "spending_controls": { "allowed_categories": [], "blocked_categories": [], "spending_limits": [], "spending_limits_currency": null }, "status": "active", "type": "individual" } ], "has_more": false, "url": "/v1/issuing/cardholders" }
Listing cards
You can also see a list of cards created on a connected account by making a Cards API GET request and passing the specific Stripe-Account into the header.
If successful, you receive a list of cards:
{ "object": "list", "data": [ { "id": "ic_1234a", "object": "issuing.card", "brand": "Visa", "cancellation_reason": null, "cardholder": { "id": "ich_1234a", "object": "issuing.cardholder", "billing": { "address": { "city": "San Francisco", "country": "US", "line1": "510 Townsend Street", "line2": null, "postal_code": "94111", "state": "CA" } }, "company": null, "created": 1656537695, "email": "jenny.rosen@example.com", "individual": null, "livemode": false, "metadata": {}, "name": "Jenny Rosen", "phone_number": "+18008675309", "requirements": { "disabled_reason": null, "past_due": [] }, "spending_controls": { "allowed_categories": [], "blocked_categories": [], "spending_limits": [], "spending_limits_currency": null }, "status": "active", "type": "individual" }, "created": 1656537950, "currency": "usd", "exp_month": 5, "exp_year": 2025, "last4": "0021", "livemode": false, "metadata": {}, "pin": null, "replaced_by": null, "replacement_for": null, "replacement_reason": null, "shipping": null, "spending_controls": { "allowed_categories": [ "car_rental_agencies" ], "blocked_categories": null, "spending_limits": [ { "amount": 8000, "categories": [], "interval": "per_authorization" } ], "spending_limits_currency": "usd" }, "status": "active", "type": "virtual", "wallets": { "apple_pay": { "eligible": true, "ineligible_reason": null }, "google_pay": { "eligible": true, "ineligible_reason": null }, "primary_account_identifier": null } }, { "id": "ic_1234b", "object": "issuing.card", "brand": "Visa", "cancellation_reason": null, "cardholder": { "id": "ich_1234a", "object": "issuing.cardholder", "billing": { "address": { "city": "San Francisco", "country": "US", "line1": "510 Townsend Street", "line2": null, "postal_code": "94111", "state": "CA" } }, "company": null, "created": 1656537695, "email": "jenny.rosen@example.com", "individual": null, "livemode": false, "metadata": {}, "name": "Jenny Rosen", "phone_number": "+18008675309", "requirements": { "disabled_reason": null, "past_due": [] }, "spending_controls": { "allowed_categories": [], "blocked_categories": [], "spending_limits": [], "spending_limits_currency": null }, "status": "active", "type": "individual" }, "created": 1656537947, "currency": "usd", "exp_month": 5, "exp_year": 2025, "last4": "0013", "livemode": false, "metadata": {}, "pin": null, "replaced_by": null, "replacement_for": null, "replacement_reason": null, "shipping": null, "spending_controls": { "allowed_categories": null, "blocked_categories": null, "spending_limits": [ { "amount": 50000, "categories": [], "interval": "daily" } ], "spending_limits_currency": "usd" }, "status": "active", "type": "virtual", "wallets": { "apple_pay": { "eligible": true, "ineligible_reason": null }, "google_pay": { "eligible": true, "ineligible_reason": null }, "primary_account_identifier": null } } ], "has_more": false, "url": "/v1/issuing/cards" }
You can see a list of cards associated with a specific cardholder by including the cardholder parameter on your Cards API GET request. Pass the specific Stripe-Account into the header and the cardholder ID into the cardholder parameter.