You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
    Library
You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

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" }

Card attributes

status
enumerated string
Current status of the card.
Possible values are
validA valid and active credit card.expiringA card which is expiring in the current month.expiredAn expired card.
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.paypal_proPayPal Pro Account is a payment gateway.pinPin is a payment gateway.ewayeWAY Account is a payment gateway.eway_rapideWAY Rapid is a payment gateway.worldpayWorldPay is a payment gateway.balanced_paymentsBalanced is a payment gateway.beanstreamBambora(formerly known as Beanstream) is a payment gateway.bluepayBluePay is a payment gateway.elavonElavon Virtual Merchant is a payment solution.first_data_globalFirst Data Global Gateway Virtual Terminal Account.hdfcHDFC Account is a payment gateway.migsMasterCard Internet Gateway Service payment gateway.nmiNMI is a payment gateway.ogoneIngenico ePayments (formerly known as Ogone) is a payment gateway.paymillPAYMILL is a payment gateway.paypal_payflow_proPayPal Payflow Pro is a payment gateway.sage_paySage Pay is a payment gateway.tco2Checkout is a payment gateway.wirecardWireCard Account is a payment service provider.not_applicableIndicates that payment gateway is not applicable for this resource.
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.
jcbA JCB card.diners_clubA Diner's Club card.bancontactA Bancontact card.otherCard belonging to types other than those listed above.not_applicableUsed for offline entries in transactions. Not applicable for cards.
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.

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
curl  https://{site}.chargebee.com/api/v1/cards/__test__XpbTXGTSRp3gtJDI \
     -u {site_api_key}:

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}

Returns

card
always returned
Resource object representing card

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

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

Input Parameters

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 gatewaypaypal_proPayPal Pro Account is a payment gateway.pinPin is a payment gatewayewayeWAY Account is a payment gateway.eway_rapideWAY Rapid is a payment gateway.worldpayWorldPay is a payment gatewaybalanced_paymentsBalanced is a payment gatewaybeanstreamBambora(formerly known as Beanstream) is a payment gateway.bluepayBluePay is a payment gateway.elavonElavon Virtual Merchant is a payment solution.first_data_globalFirst Data Global Gateway Virtual Terminal AccounthdfcHDFC Account is a payment gateway.migsMasterCard Internet Gateway Service payment gateway.nmiNMI is a payment gateway.ogoneIngenico ePayments (formerly known as Ogone) is a payment gateway.paymillPAYMILL is a payment gateway.paypal_payflow_proPayPal Payflow Pro is a payment gateway.sage_paySage Pay is a payment gateway.tco2Checkout is a payment gateway.wirecardWireCard Account is a payment service provider.
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
always returned
Resource object representing customer
card
always returned
Resource object representing card

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 \
     -X POST  \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__3Nl9RIYRcPq9HaW" \
     -d gw_token="pi_1FK04IJv9j0DyntJoJZUurla"
copy
curl  https://{site}.chargebee.com/api/v1/customers/__test__3Nl9RLTRcPq9H44f/credit_card_using_payment_intent \
     -X POST  \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__3Nl9RIYRcPq9HaW" \
     -d gw_token="pi_1FK04IJv9j0DyntJoJZUurla"

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

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
always returned
Resource object representing customer
card
always returned
Resource object representing card

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

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
curl  https://{site}.chargebee.com/api/v1/customers/__test__XpbTXGTSRp3hJ7DR/switch_gateway \
     -u {site_api_key}:\
     -d gateway="pin"

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

Input Parameters

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.pinPin is a payment gatewayewayeWAY Account is a payment gateway.eway_rapideWAY Rapid is a payment gateway.worldpayWorldPay is a payment gatewaybalanced_paymentsBalanced is a payment gatewaybeanstreamBambora(formerly known as Beanstream) is a payment gateway.bluepayBluePay is a payment gateway.elavonElavon Virtual Merchant is a payment solution.first_data_globalFirst Data Global Gateway Virtual Terminal AccounthdfcHDFC Account is a payment gateway.migsMasterCard Internet Gateway Service payment gateway.nmiNMI is a payment gateway.ogoneIngenico ePayments (formerly known as Ogone) is a payment gateway.paymillPAYMILL is a payment gateway.paypal_payflow_proPayPal Payflow Pro is a payment gateway.sage_paySage Pay is a payment gateway.wirecardWireCard Account is a payment service provider.
Show all values[+]

Returns

customer
always returned
Resource object representing customer
card
always returned
Resource object representing card

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
curl  https://{site}.chargebee.com/api/v1/customers/__test__XpbTXGTSRp3gEsD8/delete_card \
     -X POST  \
     -u {site_api_key}:

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

Returns

customer
always returned
Resource object representing customer