API Version
Product Catalog
Library
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 GET

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

Model Class

status
enumerated string
Current status of the card.
Possible values are
validA valid and active credit cardexpiringA card which is expiring in the current month.expiredAn expired card
Show all values[+]
gateway
enumerated string
Name of the gateway this payment source is stored with.
Possible values are
chargebeeChargebee test gateway.stripeStripe is a payment gateway.braintreeBraintree is a payment gateway.authorize_netAuthorize.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
visaA Visa card.mastercardA MasterCard.american_expressAn American Express card.discoverA 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.
gateway gateway
enumerated string
Name of the gateway this payment source is stored with.
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
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.
Retrieves the credit card for the customer ID.

Notes

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

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

card card
always returned
Resource object representing card

Sample admin console URL

https://{site}.chargebee.com/admin-console/cards/123x
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.

Notes

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

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

gateway[]
optional, enumerated string
Name of the gateway this card should be stored with.
Possible values are
chargebeeChargebee test gateway.stripeStripe is a payment gateway.braintreeBraintree is a payment gateway.authorize_netAuthorize.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.
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
Used to store the card to the customer after 3DS flow completion. Learn more on the 3DS integration guide via Chargebee APIs

Notes

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

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

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.
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

Switches the gateway in which customer’s card information is stored.

This is applicable only if the payment method is “card”.

Notes

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

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

gateway[]
required, enumerated string
Name of the gateway you want to switch to.
Possible values are
stripeStripe is a payment gateway.braintreeBraintree is a payment gateway.authorize_netAuthorize.net is a payment gatewaypaypal_proPayPal Pro Account is a payment gateway.
Show all values[+]
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

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.

Notes

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

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

customer customer
always returned
Resource object representing customer

Sample admin console URL

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