Cards

We recommend that you use the Payment Source APIs which comes with additional options and improvements to the Cards APIs. Learn more.

The following table lists the Payment Source resource APIs that can be used instead of Card resource API:

API at Card resource Use instead
Retrieve card for a customer Retrieve a payment source
Update card for a customer
Switch gateway Switch gateway account
Copy card Export payment source
Delete card for a customer Delete a payment source

Represents the credit card associated with a customer.

Sample card [ JSON ]

{ "card_type": "american_express", "created_at": 1517505817, "customer_id": "__test__KyVnHhSBWlU2r2f9", "expiry_month": 12, "expiry_year": 2022, "funding_type": "not_known", "gateway": "chargebee", "gateway_account_id": "gw___test__KyVnGlSBWlRfY1sw", "iin": "378282", "last4": "0005", "masked_number": "***********0005", "object": "card", "payment_source_id": "pm___test__KyVnHhSBWlU3s2fC", "resource_version": 1517505817000, "status": "valid", "updated_at": 1517505817 }

Card attributes

payment_source_id
Identifier of the payment source.
string, max chars=40
status
Current status of the card.
enumerated string
Possible values are
validA valid and active credit card.expiringA card which is expiring in the current month.expiredAn expired card.
gateway
Name of the gateway this payment source is stored with.
enumerated string
Possible values are
chargebeeChargebee test gateway.stripeStripe payment gateway.wepayWePay Gateway.braintreeBraintree payment gateway.
authorize_netAuthorize.net payment gateway.paypal_proPaypal Pro Account.pinPin payment gateway.ewayeWAY Account.eway_rapideWAY Rapid gateway.worldpayWorldPay payment gateway.balanced_paymentsBalanced payment gateway.beanstreamBambora (formerly Beanstream).bluepayBluePay payment gateway.elavonElavon Virtual Merchant.first_data_globalFirst Data Global Gateway Virtual Terminal Account.hdfcHDFC Account.migsMasterCard Internet Gateway Service.nmiNMI gateway.ogoneIngenico ePayments (formerly Ogone).paymillPAYMILL payment gateway.paypal_payflow_proPayPal Payflow Pro gateway.sage_paySage Pay gateway.tco2Checkout payment gateway.wirecardWireCard Account.amazon_paymentsThe amazon payments.paypal_express_checkoutThe paypal gateway.gocardlessGoCardless.adyenAdyen.orbitalChase Paymentech(Orbital) Gateway.moneris_usMoneris USA Gateway.monerisMoneris Gateway.bluesnapBlueSnap gateway.cybersourceCyberSource gateway.vantivVantiv gateway.checkout_comCheckout.com Gateway.paypalPaypal Commerce.not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
gateway_account_id
The gateway account to which this payment source is stored with.
optional, string, max chars=50
ref_tx_id
Reference transaction id which used for transactions.
optional, string, max chars=50
first_name
Cardholder's first name.
optional, string, max chars=50
last_name
Cardholder's last name.
optional, string, max chars=50
iin
The Issuer Identification Number, i.e. the first six digits of the card number.
string, min chars=6, max chars=6
last4
Last four digits of the card number.
string, min chars=4, max chars=4
card_type
Card type.
optional, enumerated string
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.otherCard belonging to types other than those listed above.
funding_type
Card Funding type.
enumerated string
Possible values are
creditA credit card.debitA debit card.prepaidA prepaid card.not_knownAn unknown card.
expiry_month
Card expiry month.
integer, min=1, max=12
expiry_year
Card expiry year.
integer
issuing_country
2-letter(alpha2) ISO country code.
optional, string, max chars=50
billing_addr1
Address line 1, as available in card billing address.
optional, string, max chars=150
billing_addr2
Address line 2, as available in card billing address.
optional, string, max chars=150
billing_city
City, as available in card billing address.
optional, string, max chars=50
billing_state_code
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
billing_state
The state/province name.
optional, string, max chars=50
billing_country
2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50
billing_zip
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
created_at
Timestamp indicating when this card resource is created.
timestamp(UTC) in seconds
resource_version
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
updated_at
Timestamp indicating when this credit card resource was last updated.
optional, timestamp(UTC) in seconds
ip_address
The IP address from where the payment source is created or updated. Used primarily for EU VAT validation.
optional, string, max chars=50
powered_by

optional, enumerated string
Possible values are
idealideal.sofortsofort.bancontactbancontact.giropaygiropay.not_applicablenot_applicable.
customer_id
Identifier of the customer.
string, max chars=50
masked_number
Masked credit card number that is safe to show.
optional, string, max chars=19

Retrieve card for a customer

We recently released Payment Sources, which comes with additional options and improvements to the Card APIs. For this operation, use the Retrieve a payment source API under Payment Sources.

Retrieves the credit card for the customer id.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/cards/__test__KyVnHhSBWlU2r2f9 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/cards/__test__KyVnHhSBWlU2r2f9 \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"card": { "card_type": "american_express", "created_at": 1517505817, "customer_id": "__test__KyVnHhSBWlU2r2f9", "expiry_month": 12, "expiry_year": 2022, "funding_type": "not_known", "gateway": "chargebee", "gateway_account_id": "gw___test__KyVnGlSBWlRfY1sw", "iin": "378282", "last4": "0005", "masked_number": "***********0005", "object": "card", "payment_source_id": "pm___test__KyVnHhSBWlU3s2fC", "resource_version": 1517505817000, "status": "valid", "updated_at": 1517505817 }}

URL Format GET

https://{site}.chargebee.com/api/v2/cards/{customer_id}

Returns

card
Resource object representing card.
always returned

Update card for a customer

We recently released Payment Sources, which comes with additional options and improvements to the Card APIs. For this operation, use the Create using temporary token API or Create a card payment source API under Payment Sources to update card for the customer.

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.
  • If you are using Authorize.Net gateway, you use Accept.js with your card update form.
  • In case you are using the Adyen gateway, you will have to use the Adyen’s Client Side Encryption to encrypt sensitive cardholder data. Once the cardholder data is encrypted, pass the value in adyen.encrypted.data as temp token in this API.
  • 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/v2/customers/__test__KyVnHhSBWlUrE2fN/credit_card \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__KyVnGlSBWlRlI1tm" \
     -d first_name="Richard" \
     -d last_name="Fox" \
     -d number="4012888888881881" \
     -d expiry_month=10 \
     -d expiry_year=2022 \
     -d cvv="999"
copy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlUrE2fN/credit_card \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__KyVnGlSBWlRlI1tm" \
     -d first_name="Richard" \
     -d last_name="Fox" \
     -d number="4012888888881881" \
     -d expiry_month=10 \
     -d expiry_year=2022 \
     -d cvv="999"

Sample Response [ JSON ]

Show more...
{ "card": { "card_type": "visa", "created_at": 1517505821, "customer_id": "__test__KyVnHhSBWlUrE2fN", "expiry_month": 10, "expiry_year": 2022, "first_name": "Richard", "funding_type": "credit", "gateway": "stripe", "gateway_account_id": "gw___test__KyVnGlSBWlRlI1tm", "iin": "401288", "issuing_country": "CA", "last4": "1881", "last_name": "Fox", "masked_number": "************1881", "object": "card", "payment_source_id": "pm___test__KyVnHhSBWlV462fP", "resource_version": 1517505821000, "status": "valid", "updated_at": 1517505821 }, "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517505820, "deleted": false, "excess_payments": 0, "first_name": "Richard", "id": "__test__KyVnHhSBWlUrE2fN", "last_name": "Fox", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__KyVnGlSBWlRlI1tm", "object": "payment_method", "reference_id": "cus_I58Ra9m8POVbxn/card_1HUyASJv9j0DyntJS4Lu3OCT", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__KyVnHhSBWlV462fP", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517505821000, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517505821 } }

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/credit_card

Input Parameters

gateway_account_id
The gateway account in which this payment source is stored.
optional, string, max chars=50
tmp_token
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).
optional, string, max chars=300
first_name
Cardholder's first name.
optional, string, max chars=50
last_name
Cardholder's last name.
optional, string, max chars=50
number
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required, string, max chars=1500
expiry_month
Card expiry month.
required, integer, min=1, max=12
expiry_year
Card expiry year.
required, integer
cvv
The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520
billing_addr1
Address line 1, as available in card billing address.
optional, string, max chars=150
billing_addr2
Address line 2, as available in card billing address.
optional, string, max chars=150
billing_city
City, as available in card billing address.
optional, string, max chars=50
billing_state_code
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).
optional, string, max chars=50
billing_state
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50
billing_zip
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
billing_country
2-letter, ISO 3166 alpha-2 country code.
optional, string, max chars=50

Returns

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

Switch gateway

We recently released Payment Sources, which comes with additional options and improvements to the Card APIs. For this operation, use the Switch gateway account API under Payment Sources.

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

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

Notes

This operation does not support switching between Braintree and Stripe. If you need to use this API, please contact support.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlUUR2fG/switch_gateway \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__KyVnGlSBWlUNY1tu"
copy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlUUR2fG/switch_gateway \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__KyVnGlSBWlUNY1tu"

Sample Response [ JSON ]

Show more...
{ "card": { "card_type": "visa", "created_at": 1517505819, "customer_id": "__test__KyVnHhSBWlUUR2fG", "expiry_month": 12, "expiry_year": 2022, "funding_type": "not_known", "gateway": "pin", "gateway_account_id": "gw___test__KyVnGlSBWlUNY1tu", "iin": "411111", "last4": "1111", "masked_number": "************1111", "object": "card", "payment_source_id": "pm___test__KyVnHhSBWlUb22fH", "resource_version": 1517505819000, "status": "valid", "updated_at": 1517505819 }, "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517505818, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__KyVnHhSBWlUUR2fG", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "pin", "gateway_account_id": "gw___test__KyVnGlSBWlUNY1tu", "object": "payment_method", "reference_id": "3Malm9wxY1OyrwzHwTfDS87AiaU", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__KyVnHhSBWlUb22fH", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517505819000, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517505819 } }

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/switch_gateway

Input Parameters

gateway_account_id
The gateway account you want to switch to.
required, string, max chars=50

Returns

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

Copy card

We recently released Payment Sources, which comes with additional options and improvements to the Card APIs. For this operation, use the Export payment source API under Payment Sources.

Copies the customer’s card information to the gateway specified in the API.

This is useful if you want to port your customer’s card details into another gateway.

Notes

This operation does not support copying of cards from Stripe and Braintree gateways. If you need to use this API, please contact support.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlRmb2ev/copy_card \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__KyVnGlSBWlRlI1tm"
copy
curl  https://{site}.chargebee.com/api/v2/customers/__test__KyVnHhSBWlRmb2ev/copy_card \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__KyVnGlSBWlRlI1tm"

Sample Response [ JSON ]

Show more...
{"third_party_payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__KyVnGlSBWlRlI1tm", "object": "third_party_payment_method", "reference_id": "cus_I58Rw3ihuzi9yA/card_1HUyAKJv9j0DyntJVZHU2ZjC", "type": "card" }}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/copy_card

Input Parameters

gateway_account_id
The gateway account you want to copy the card.
required, string, max chars=50

Returns

third_party_payment_method
Resource object representing third_party_payment_method.
always returned

Delete card for a customer

We recently released Payment Sources, which comes with additional options and improvements to the Card APIs. For this operation, use the Delete a payment source API under Payment Sources.

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

Sample Response [ JSON ]

Show more...
{"customer": { "allow_direct_debit": false, "auto_collection": "off", "card_status": "no_card", "created_at": 1517505815, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__KyVnHhSBWlTZA2f1", "last_name": "Henry", "net_term_days": 0, "object": "customer", "pii_cleared": "active", "preferred_currency_code": "USD", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517505816000, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517505816 }}

URL Format POST

https://{site}.chargebee.com/api/v2/customers/{customer_id}/delete_card

Returns

customer
Resource object representing customer.
always returned