Settings
API Version
Product Catalog
Library

Cards

This resource helps you to retrieve, update, and delete card details for a customer.

Sample card [ JSON ]

{ "card_type": "american_express", "customer_id": "__test__XpbTXGTSRp3gtJDI", "expiry_month": 12, "expiry_year": 2022, "gateway": "chargebee", "iin": "378282", "last4": "0005", "masked_number": "***********0005", "object": "card", "reference_id": "tok___test__XpbTXGTSRp3gxDDL", "status": "valid" }

API Index URL

https://{site}.chargebee.com/api/v1/cards

Model Class

 

      Card attributes
      
 
status
 

      enumerated string
 
Current status of the card.
 
 
Possible values are
 
 
valid
A valid and active credit card
expiring
A card which is expiring in the current month.
expired
An expired card
 
 Show all values[+]
gateway
 

      enumerated string
 
Name of the gateway this payment source is stored with.
 
 
Possible values are
 
 
chargebee
Chargebee test gateway.
stripe
Stripe is a payment gateway.
braintree
Braintree is a payment gateway.
authorize_net
Authorize.net is a payment gateway
 
 Show all values[+]
reference_id
 

      optional, string, max chars=200
 
The identifier provided by the gateway/card vault for the specific payment method resource.
 
 
first_name
 

      optional, string, max chars=50
 
Cardholder's first name
 
 
last_name
 

      optional, string, max chars=50
 
Cardholder's last name
 
 
iin
 

      string, min chars=6, max chars=6
 
The Issuer Identification Number, i.e. the first six digits of the card number
 
 
last4
 

      string, min chars=4, max chars=4
 
Last four digits of the card number
 
 
card_type
 

      optional, enumerated string
 
Card type
 
 
Possible values are
 
 
visa
A Visa card.
mastercard
A MasterCard.
american_express
An American Express card.
discover
A Discover card.
 
 Show all values[+]
expiry_month
 

      integer, min=1, max=12
 
Card expiry month.
 
 
expiry_year
 

      integer
 
Card expiry year.
 
 
billing_addr1
 

      optional, string, max chars=150
 
Address line 1, as available in card billing address.
 
 
billing_addr2
 

      optional, string, max chars=150
 
Address line 2, as available in card billing address.
 
 
billing_city
 

      optional, string, max chars=50
 
City, as available in card billing address.
 
 
billing_state_code
 

      optional, string, max chars=50
 
The ISO 3166-2 state/province code
without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).
 
 
billing_state
 

      optional, string, max chars=50
 
The state/province name.
 
 
billing_country
 

      optional, string, max chars=50
 
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code
.


Note:
If you enter an invalid country code, the system will return an error.


Brexit
If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.
 
 
billing_zip
 

      optional, string, max chars=20
 
Postal or Zip code, as available in card billing address.
 
 
ip_address
 

      optional, string, max chars=50
 
The IP address of the customer. Used primarily for referral integration and EU VAT validation.
 
 
customer_id
 

      string, max chars=50
 
Identifier of the customer.
 
 
masked_number
 

      optional, string, max chars=19
 
Masked credit card number that is safe to show.
 
 
  
  
status status
 

          enumerated string
 
Current status of the card.
 
 
Possible values are
 
 
valid
A valid and active credit card
expiring
A card which is expiring in the current month.
expired
An expired card
 
 Show all values[+]
gateway gateway
 

          enumerated string
 
Name of the gateway this payment source is stored with.
 
 
Possible values are
 
 
chargebee
Chargebee test gateway.
stripe
Stripe is a payment gateway.
braintree
Braintree is a payment gateway.
authorize_net
Authorize.net is a payment gateway
 
 Show all values[+]
reference_id reference_id
 

          optional, string, max chars=200
 
The identifier provided by the gateway/card vault for the specific payment method resource.
 
 
first_name first_name
 

          optional, string, max chars=50
 
Cardholder's first name
 
 
last_name last_name
 

          optional, string, max chars=50
 
Cardholder's last name
 
 
iin iin
 

          string, min chars=6, max chars=6
 
The Issuer Identification Number, i.e. the first six digits of the card number
 
 
last4 last4
 

          string, min chars=4, max chars=4
 
Last four digits of the card number
 
 
card_type card_type
 

          optional, enumerated string
 
Card type
 
 
Possible values are
 
 
visa
A Visa card.
mastercard
A MasterCard.
american_express
An American Express card.
discover
A Discover card.
 
 Show all values[+]
expiry_month expiry_month
 

          integer, min=1, max=12
 
Card expiry month.
 
 
expiry_year expiry_year
 

          integer
 
Card expiry year.
 
 
billing_addr1 billing_addr1
 

          optional, string, max chars=150
 
Address line 1, as available in card billing address.
 
 
billing_addr2 billing_addr2
 

          optional, string, max chars=150
 
Address line 2, as available in card billing address.
 
 
billing_city billing_city
 

          optional, string, max chars=50
 
City, as available in card billing address.
 
 
billing_state_code billing_state_code
 

          optional, string, max chars=50
 
The ISO 3166-2 state/province code
without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).
 
 
billing_state billing_state
 

          optional, string, max chars=50
 
The state/province name.
 
 
billing_country billing_country
 

          optional, string, max chars=50
 
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code
.


Note:
If you enter an invalid country code, the system will return an error.


Brexit
If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.
 
 
billing_zip billing_zip
 

          optional, string, max chars=20
 
Postal or Zip code, as available in card billing address.
 
 
ip_address ip_address
 

          optional, string, max chars=50
 
The IP address of the customer. Used primarily for referral integration and EU VAT validation.
 
 
customer_id customer_id
 

          string, max chars=50
 
Identifier of the customer.
 
 
masked_number masked_number
 

          optional, string, max chars=19
 
Masked credit card number that is safe to show.
 
 
 
 
Consent Fields for Card
 
 
Custom Fields for Card
 
 

      Retrieve card for a customer
      
  
  
Retrieves the credit card for the customer ID.
  

        Sample Request
      
 
 
 
curl  https://{site}.chargebee.com/api/v1/cards/__test__XpbTXGTSRp3gtJDI \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "card": {
        "card_type": "american_express",
        "customer_id": "__test__XpbTXGTSRp3gtJDI",
        "expiry_month": 12,
        "expiry_year": 2022,
        "gateway": "chargebee",
        "iin": "378282",
        "last4": "0005",
        "masked_number": "***********0005",
        "object": "card",
        "reference_id": "tok___test__XpbTXGTSRp3gxDDL",
        "status": "valid"
    }
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v1/cards/{customer-id}
    
 
Method
 
  
   
 
    
 
Returns
 
card  card
 

      always returned 
 Resource object representing card
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/cards/123x
    

      Update card for a customer
      
 
Idempotency Supported
 
  
Storing card after successful 3DS flow not supported in this API. Use create using Payment Intent API
under Payemnt source to store the card after successful 3DS flow completion.
Adds or replaces card details of a customer. Updating card details replaces the present payment method.
Passing credit card details to this API involves PCI liability at your end as sensitive card info passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable
    

  • If you are using Stripe gateway, you can use Stripe.js with your card update form.
    • 

  • If you are using Braintree gateway, you can use Braintree.js with your card update form.
    • 

  • You can also use our Hosted Pages based integration. Use our Hosted Page - Update Card API to generate a 'Update Card' Hosted Page link.
    • 

**Note:**For customers signed up before 1st March 2014, if the card's billing information is specified in the input, the customer's Billing Info (i.e Billing Address and vat_number) will also be replaced with the new values automatically.
  

        Sample Request
      
 
 
 
curl  https://{site}.chargebee.com/api/v1/customers/__test__XpbTXGTSRp3hoMDa/credit_card \
     -u {site_api_key}:\
     -d first_name="Richard" \
     -d last_name="Fox" \
     -d number="4012888888881881" \
     -d expiry_month=10 \
     -d expiry_year=2022 \
     -d cvv="999" \
     -d gateway="CHARGEBEE"
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "card": {
        "card_type": "visa",
        "customer_id": "__test__XpbTXGTSRp3hoMDa",
        "expiry_month": 10,
        "expiry_year": 2022,
        "first_name": "Richard",
        "gateway": "chargebee",
        "iin": "401288",
        "last4": "1881",
        "last_name": "Fox",
        "masked_number": "************1881",
        "object": "card",
        "reference_id": "tok___test__XpbTXGTSRp3hsKDd",
        "status": "valid"
    },
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487059,
        "excess_payments": 0,
        "first_name": "Richard",
        "id": "__test__XpbTXGTSRp3hoMDa",
        "last_name": "Fox",
        "object": "customer",
        "payment_method": {
            "gateway": "chargebee",
            "object": "payment_method",
            "reference_id": "tok___test__XpbTXGTSRp3hsKDd",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v1/customers/{customer-id}/credit_card
    
 
Method
 
 
Input Parameters
 
  
 
gateway[]
 

      optional, enumerated string 
 
Name of the gateway this card should be stored with.
 
Possible values are
 
 
chargebee
Chargebee test gateway.
stripe
Stripe is a payment gateway.
braintree
Braintree is a payment gateway.
authorize_net
Authorize.net is a payment gateway
 
 Show all values[+]
 
tmp_token[]
 

      optional, string, max chars=300 
 
The single-use card token returned by vaults like Stripe/Braintree which act as a substitute for your card details. Before calling this API, you should have submitted your card details to the gateway and gotten this token in return.
Note:
Supported only for Stripe, Braintree and Authorize.Net. If this value is specified, there is no need to specify other card details (like number, cvv, etc).
 
 
first_name[]
 

      optional, string, max chars=50 
 
Cardholder's first name.
 
 
last_name[]
 

      optional, string, max chars=50 
 
Cardholder's last name.
 
 
number[]
 

      required, string, max chars=1500 
 
The credit card number without any format. If you are using Braintree.js
, you can specify the Braintree encrypted card number here.
 
 
expiry_month[]
 

      required, integer, min=1, max=12 
 
Card expiry month.
 
 
expiry_year[]
 

      required, integer 
 
Card expiry year.
 
 
cvv[]
 

      optional, string, max chars=520 
 
The card verification value (CVV). If you are using Braintree.js
, you can specify the Braintree encrypted CVV here.
 
 
billing_addr1[]
 

      optional, string, max chars=150 
 
Address line 1, as available in card billing address.
 
 
billing_addr2[]
 

      optional, string, max chars=150 
 
Address line 2, as available in card billing address.
 
 
billing_city[]
 

      optional, string, max chars=50 
 
City, as available in card billing address.
 
 
billing_state_code[]
 

      optional, string, max chars=50 
 
The ISO 3166-2 state/province code
without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code
as AZ
(not US-AZ
). For Tamil Nadu (India), set as TN
(not IN-TN
). For British Columbia (Canada), set as BC
(not CA-BC
).
 
 
billing_state[]
 

      optional, string, max chars=50 
 
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
 
 
billing_zip[]
 

      optional, string, max chars=20 
 
Postal or Zip code, as available in card billing address.
 
 
billing_country[]
 

      optional, string, max chars=50 
 
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code
.


Note:
If you enter an invalid country code, the system will return an error.


Brexit
If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.


.
 
 
ip_address[]
 

      optional, string, max chars=50 
 
The IP address of the customer. Used primarily for referral integration and EU VAT validation.
 
 
 
    
 
Returns
 
customer  customer
 

      always returned 
 Resource object representing customer
card  card
 

      always returned 
 Resource object representing card
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/cards/123x
    

      Update card for customer using payment intent
      
 
Idempotency Supported
 
  
Used to store the card to the customer after 3DS flow completion. Learn more
on the 3DS integration guide via Chargebee APIs
  

        Sample Request
      
 
 
 
curl  https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPq9H44f/credit_card_using_payment_intent \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__3Nl9RIYRcPq9HaW" \
     -d gw_token="pi_1FK04IJv9j0DyntJoJZUurla"
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "card": {
        "card_type": "visa",
        "customer_id": "__test__3Nl9RLTRcPq9H44f",
        "expiry_month": 7,
        "expiry_year": 2020,
        "gateway": "stripe",
        "iin": "******",
        "last4": "3055",
        "masked_number": "************3055",
        "object": "card",
        "reference_id": "cus_FpfPS8LZzDBZAY/pm_1FK04IJv9j0DyntJXIKiwNnl",
        "status": "valid"
    },
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517479645,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__3Nl9RLTRcPq9H44f",
        "last_name": "Henry",
        "object": "customer",
        "payment_method": {
            "gateway": "stripe",
            "object": "payment_method",
            "reference_id": "cus_FpfPS8LZzDBZAY/pm_1FK04IJv9j0DyntJXIKiwNnl",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v1/customers/{customer-id}/credit_card_using_payment_intent
    
 
Method
 
 
Input Parameters
 
  
 
payment_intent_id[]
 

      optional, string, max chars=150 
 
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow.  The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
 
 
gateway_account_id[]
 

      optional, string, max chars=50 
 
The gateway account used for performing the 3DS flow. Applicable when you are using gateway APIs directly for completing the 3DS flow.
 
 
gw_token[]
 

      optional, string, max chars=65k 
 
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee
to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
 
 
reference_id[]
 

      optional, string, max chars=65k 
 
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
 
 
 
    
 
Returns
 
customer  customer
 

      always returned 
 Resource object representing customer
card  card
 

      always returned 
 Resource object representing card
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/cards/123x
    

      Switch gateway
      
 
Idempotency Supported
 
  
Switches the gateway in which customer's card information is stored.
This is applicable only if the payment method is "card".
This operation is not supported if the current gateway is Braintree or Stripe.
  

        Sample Request
      
 
 
 
curl  https://{site}.chargebee.com/api/v1/customers/__test__XpbTXGTSRp3hJ7DR/switch_gateway \
     -u {site_api_key}:\
     -d gateway="PIN"
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "card": {
        "card_type": "visa",
        "customer_id": "__test__XpbTXGTSRp3hJ7DR",
        "expiry_month": 12,
        "expiry_year": 2022,
        "gateway": "pin",
        "iin": "411111",
        "last4": "1111",
        "masked_number": "************1111",
        "object": "card",
        "reference_id": "T4SMIM14m11ZHguFv1EJbBiWKUz",
        "status": "valid"
    },
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "valid",
        "created_at": 1517487057,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp3hJ7DR",
        "last_name": "Henry",
        "object": "customer",
        "payment_method": {
            "gateway": "pin",
            "object": "payment_method",
            "reference_id": "T4SMIM14m11ZHguFv1EJbBiWKUz",
            "status": "valid",
            "type": "card"
        },
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v1/customers/{customer-id}/switch_gateway
    
 
Method
 
 
Input Parameters
 
  
 
gateway[]
 

      required, enumerated string 
 
Name of the gateway you want to switch to.
 
Possible values are
 
 
stripe
Stripe is a payment gateway.
braintree
Braintree is a payment gateway.
authorize_net
Authorize.net is a payment gateway
paypal_pro
PayPal Pro Account is a payment gateway.
 
 Show all values[+]
 
 
    
 
Returns
 
customer  customer
 

      always returned 
 Resource object representing customer
card  card
 

      always returned 
 Resource object representing card
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/cards/123x
    

      Delete card for a customer
      
 
Idempotency Supported
 
  
Deletes the existing card for a customer. Upon successful deletion of card the auto_collection attribute for this customer will be set to off and card_deleted event will be triggered.
If there is no card present in the gateway for the customer, this API will return successfully without throwing any error.
  

        Sample Request
      
 
 
 
curl  https://{site}.chargebee.com/api/v1/customers/__test__XpbTXGTSRp3gEsD8/delete_card \
     -X POST  \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1517487053,
        "excess_payments": 0,
        "first_name": "Mark",
        "id": "__test__XpbTXGTSRp3gEsD8",
        "last_name": "Henry",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v1/customers/{customer-id}/delete_card
    
 
Method
 
  
   
 
    
 
Returns
 
customer  customer
 

      always returned 
 Resource object representing customer
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/cards/123x