# Create a card

Adds a new card to an existing customer.

There are three ways to create a new card object: use a card token (for example obtained from Components), use a charge identifier (saves the card that was used to create a successful charge not assigned to any other customer, and assigns that charge to this customer), or specify all card details.

Endpoint: POST /customers/{customerId}/cards
Version: 1.0.0
Security: BasicAuth

## Path parameters:

  - `customerId` (string, required)
    Identifier of the customer the card should be added to.

## Request fields (application/x-www-form-urlencoded):

  - `id` (string, required)
    A card token (for example obtained from Components), or the identifier of a successful charge whose card should be saved to this customer.
    Example: tok_NGsyDoJQXop5Pqqi6HizbJTe

  - `number` (string, required)
    The card number.
    Example: 4242424242424242

  - `expMonth` (string, required)
    Two-digit expiration month.
    Example: 12

  - `expYear` (string, required)
    Four-digit expiration year.
    Example: 2030

  - `cvc` (string, required)
    Card verification code.
    Example: 123

  - `cardholderName` (string)
    Name of the cardholder.
    Example: John Doe

  - `addressLine1` (string)
    Example: 1234 Market St

  - `addressLine2` (string)
    Example: Suite 500

  - `addressCity` (string)
    Example: San Francisco

  - `addressState` (string)
    Example: CA

  - `addressZip` (string)
    Example: 94103

  - `addressCountry` (string)
    Country represented as a three-letter ISO country code.
    Example: USA

  - `fraudCheckData` (object)
    Additional data used for fraud protection.

  - `fraudCheckData.ipAddress` (string)
    IP address of the user.
    Example: 203.0.113.42

  - `fraudCheckData.ipCountry` (string)
    Country derived from the user's IP address (two-letter ISO country code).
    Example: US

  - `fraudCheckData.email` (string)
    E-mail address of the user.
    Example: john.doe@example.com

  - `fraudCheckData.phone` (string)
    Phone number of the user.
    Example: +14155550132

  - `fraudCheckData.userAgent` (string)
    Value of the "User-Agent" HTTP header sent by the user.
    Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36

  - `fraudCheckData.acceptLanguage` (string)
    Value of the "Accept-Language" HTTP header sent by the user.
    Example: en-US,en;q=0.9

  - `fraudCheckData.browserFingerprint` (string)
    Hashed device identifier, available if Shift4.js was used to create the token.
    Example: 35a05229011ab99930545a2e1b2edc4e

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier for the card
    Example: card_8P7OWXA5xiTS1ISnyZcum1KV

  - `created` (integer)
    Unix timestamp
    Example: 1711929600

  - `objectType` (string)
    Enum: "card"

  - `first6` (string)
    First six digits of the card number
    Example: 424242

  - `last4` (string)
    Last four digits of the card number
    Example: 4242

  - `fingerprint` (string)
    Unique fingerprint for this card number
    Example: e3d8suyIDgFg3pE7

  - `expMonth` (string)
    Two-digit expiration month
    Example: 12

  - `expYear` (string)
    Four-digit expiration year
    Example: 2027

  - `cardholderName` (string)
    Name of the cardholder
    Example: John Doe

  - `brand` (string)
    Card brand
    Enum: "Visa", "MasterCard", "American Express", "Discover", "JCB", "Diners Club", "Unknown"

  - `type` (string)
    Card type
    Enum: "Credit Card", "Debit Card", "Prepaid Card", "Unknown"

  - `country` (string)
    Two-letter ISO 3166-1 country code of the card's issuing country
    Example: US

  - `issuer` (string)
    Name of the bank that issued the card
    Example: Card Issuer Name

  - `customerId` (string)
    ID of the customer this card belongs to, if any
    Example: cust_AoR0wvgntQWRUYMdZNLYMz5R

  - `fraudCheckData` (object)
    Fraud-protection data captured when the card was created.

  - `fraudCheckData.ipAddress` (string)
    IP address of the user.
    Example: 203.0.113.42

  - `fraudCheckData.ipCountry` (string)
    Country derived from the user's IP address (two-letter ISO country code).
    Example: US

  - `fraudCheckData.email` (string)
    E-mail address of the user.
    Example: john.doe@example.com

  - `fraudCheckData.phone` (string)
    Phone number of the user.
    Example: +14155550132

  - `fraudCheckData.userAgent` (string)
    Value of the "User-Agent" HTTP header sent by the user.
    Example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36

  - `fraudCheckData.acceptLanguage` (string)
    Value of the "Accept-Language" HTTP header sent by the user.
    Example: en-US,en;q=0.9

  - `fraudCheckData.browserFingerprint` (string)
    Hashed device identifier, available if Shift4.js was used to create the token.
    Example: 35a05229011ab99930545a2e1b2edc4e

  - `merchantAccountId` (string)
    Identifier of the merchant account used to create this card.
    Example: ma_RHCN1yhubdBpSCgKcYAGb0xH

  - `addressLine1` (string)
    First line of the billing address associated with the card.
    Example: 1234 Market St

  - `addressLine2` (string)
    Second line of the billing address associated with the card.
    Example: Suite 500

  - `addressCity` (string)
    City of the billing address associated with the card.
    Example: San Francisco

  - `addressState` (string)
    State of the billing address associated with the card.
    Example: CA

  - `addressZip` (string)
    ZIP or postal code of the billing address associated with the card.
    Example: 94103

  - `addressCountry` (string)
    Country of the billing address associated with the card, represented as a three-letter ISO country code.
    Example: USA

  - `fastCredit` (object)
    Fast credit (fast payout) support status for this card.

  - `fastCredit.supported` (boolean)
    Indicates whether the card supports fast credit.
    Example: true

  - `fastCredit.updated` (integer)
    Unix timestamp of the last time the fast credit status was refreshed.
    Example: 1701432000

## Response 400 fields (application/json):

  - `error` (object)

  - `error.type` (string)
    Error type
    Enum: "invalid_request", "card_error", "gateway_error"

  - `error.code` (string)
    Machine-readable error code
    Example: invalid_number

  - `error.message` (string)
    Human-readable error message
    Example: Requested object does not exist

  - `error.chargeId` (string)
    ID of the charge associated with this error (if applicable)
    Example: char_ORVCrwOrTkGsDwM3H50OIW7Q

## Response 402 fields (application/json):

  - `error` (object)

  - `error.type` (string)
    Error type
    Enum: "invalid_request", "card_error", "gateway_error"

  - `error.code` (string)
    Machine-readable error code
    Example: invalid_number

  - `error.message` (string)
    Human-readable error message
    Example: Requested object does not exist

  - `error.chargeId` (string)
    ID of the charge associated with this error (if applicable)
    Example: char_ORVCrwOrTkGsDwM3H50OIW7Q