Cards

You can store multiple cards on a customer in order to charge the customer later. You can also store multiple debit cards on a recipient in order to transfer to those cards later.

Related guide: Card payments with Sources

Was this section helpful? Yes No

Create a card

POST / v1 / customers /:id / sources

Update a card

POST / v1 / customers /:id / sources /:id

Retrieve a card

GET / v1 / customers /:id / cards /:id

List all cards

GET / v1 / customers /:id / cards

Delete a card

DELETE / v1 / customers /:id / sources /:id

The Card object

Attributes

id string Unique identifier for the object.
address _ city nullable string the relevant part of the product
address _ country nullable string Billing address country, if provided when creating card.
address _ line1 nullable string Address line 1 (Street address/PO Box/Company name).
address _ line2 nullable string Address line 2 (the relevant part of the product).
address _ state nullable string the relevant part of the product
address _ zip nullable string ZIP or postal code.
address _ zip _ check nullable string If address_zip was provided, results of the check: pass, fail, unavailable, or unchecked.
brand string Card brand. Can be American Express, Cartes Bancaires, Diners Club, Discover, Eftpos Australia, Girocard, JCB, MasterCard, UnionPay, Visa, or Unknown.
country nullable string Two-letter ISO code representing the country of the card. You could use this attribute to get a sense of the international breakdown of cards you’ve collected.
customer nullable string Expandable The customer that this card belongs to. This attribute will not be in the card object if the card belongs to an account or recipient instead.
cvc _ check nullable string If a CVC was provided, results of the check: pass, fail, unavailable, or unchecked. A result of unchecked indicates that CVC was provided but hasn’t been checked yet. Checks are typically performed when attaching a card to a Customer object, or when creating a charge. For more details, see Check if a card is valid without a charge.
exp _ month integer Two-digit number representing the card’s expiration month.
exp _ year integer Four-digit number representing the card’s expiration year.
fingerprint nullable string Uniquely identifies this particular card number. You can use this attribute to check whether two customers who’ve signed up with you are using the same card number, for example. For payment methods that tokenize card information (Apple Pay, Google Pay), the tokenized number might be provided instead of the underlying card number. As of May 1, 2021, card fingerprint in India for Connect changed to allow two fingerprints for the same card—one for India and one for the rest of the world.
funding string Card funding type. Can be credit, debit, prepaid, or unknown.
last4 string The last four digits of the card.
metadata nullable map 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.
name nullable string Cardholder name.

More attributes

object string, value is "card"
account nullable string Expandable Available conditionally
address _ line1 _ check nullable string
allow _ redisplay nullable enum
available _ payout _ methods nullable array of enums
currency nullable enum Available conditionally
dynamic _ last4 nullable string
regulated _ status nullable enum
tokenization _ method nullable string
wallet nullable object Preview feature

The Card object

{ "id": "card_1MvoiELkdIwHu7ixOeFGbN9D", "object": "card", "address_city": null, "address_country": null, "address_line1": null, "address_line1_check": null, "address_line2": null, "address_state": null, "address_zip": null, "address_zip_check": null, "brand": "Visa", "country": "US", "customer": "cus_NhD8HD2bY8dP3V", "cvc_check": null, "dynamic_last4": null, "exp_month": 4, "exp_year": 2024, "fingerprint": "mToisGZ01V71BCos", "funding": "credit", "last4": "4242", "metadata": {}, "name": null, "tokenization_method": null, "wallet": null}

Create a card

POST / v1 / customers /:id / sources

When you create a new credit card, you must specify a customer or recipient on which to create it.

If the card’s owner has no default card, then the new card will become the default. However, if the owner already has a default, then it will not change. To change the default, you should update the customer to have a new default_source.

Parameters

source object | string Required A token, like the ones returned by Stripe.js or a dictionary containing a user’s card details (with the options shown below). Stripe will automatically validate the card.
metadata map 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.

Returns

Returns the Card object.

Response

{ "id": "card_1NGTaT2eZvKYlo2CZWSctn5n", "object": "card", "address_city": null, "address_country": null, "address_line1": null, "address_line1_check": null, "address_line2": null, "address_state": null, "address_zip": null, "address_zip_check": null, "brand": "Visa", "country": "US", "customer": "cus_9s6XGDTHzA66Po", "cvc_check": "pass", "dynamic_last4": null, "exp_month": 8, "exp_year": 2024, "fingerprint": "Xt5EWLLDS7FJjR1c", "funding": "credit", "last4": "4242", "metadata": {}, "name": null, "redaction": null, "tokenization_method": null, "wallet": null}