Product Catalog
    Library
You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

Cards

Deprecated

The Payment Sources API, with its additional options and improvements, obsoletes the Cards APIs. Learn more.

The following table lists the Payment Sources API operations alongside the equivalent Card API operations:

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

Sample card [ JSON ]

{ "card_type": "american_express", "created_at": 1517486946, "customer_id": "__test__XpbTXGTSRp3ELNCY", "expiry_month": 12, "expiry_year": 2022, "funding_type": "not_known", "gateway": "chargebee", "gateway_account_id": "gw___test__5SK2lMgOSRp3BOO1y", "iin": "378282", "last4": "0005", "masked_number": "***********0005", "object": "card", "payment_source_id": "pm___test__XpbTXGTSRp3ENNCc", "resource_version": 1517486946205, "status": "valid", "updated_at": 1517486946 }

Card attributes

payment_source_id
string, max chars=40
Identifier of the payment source
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.chargebee_paymentsChargebee Payments gateway.stripeStripe is a payment gateway.wepayWePay 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.amazon_paymentsAmazon Payments is a payment service provider.paypal_express_checkoutPayPal Express Checkout is a payment gateway.gocardlessGoCardless is a payment service provider.adyenAdyen is a payment gateway.orbitalChase Paymentech(Orbital) is a payment gateway.moneris_usMoneris USA is a payment gateway.monerisMoneris is a payment gateway.bluesnapBlueSnap is a payment gateway.cybersourceCyberSource is a payment gateway.vantivVantiv is a payment gateway.checkout_comCheckout.com is a payment gateway.paypalPayPal Commerce is a payment gateway.ingenico_directWorldline Online Payments is a payment gateway.exactExact Payments is a payment gateway.mollieMollie is a payment gateway.quickbooksIntuit QuickBooks Payments gateway.razorpayRazorpay is a fast growing payment service provider in India working with all leading banks and support for major local payment methods including Netbanking, UPI etc.global_paymentsGlobal Payments is a payment service provider.bank_of_americaBank of America Gateway.ecentricEcentric provides a seamless payment processing service in South Africa specializing on omnichannel capabilities.metrics_globalMetrics global is a leading payment service provider providing unified payment services in the US.windcaveWindcave provides an end to end payment processing solution in ANZ and other leading global markets.ebanxEBANX is a payment gateway, enabling businesses to accept diverse local payment methods from various countries for increased market reach and conversion..not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
gateway_account_id
optional, string, max chars=50
The gateway account to which this payment source is stored with.
ref_tx_id
optional, string, max chars=50
Reference transaction id which used for transactions
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[+]
funding_type
enumerated string
Card Funding type
Possible values are
creditA credit card.debitA debit card.prepaidA prepaid card.not_knownAn unknown card.not_applicableUsed for ACH. Not applicable for cards.
expiry_month
integer, min=1, max=12
Card expiry month.
expiry_year
integer
Card expiry year.
issuing_country
optional, string, max chars=50
two-letter(alpha2) ISO country code.
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.
created_at
timestamp(UTC) in seconds
Timestamp indicating when this card resource is created.
resource_version
optional, long
Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
updated_at
optional, timestamp(UTC) in seconds
Timestamp indicating when this credit card resource was last updated.
ip_address
optional, string, max chars=50
The IP address of the customer. Used primarily for referral integration and EU VAT validation.
powered_by
optional, enumerated string
Card powered by payment method.
Possible values are
idealideal.sofortsofort.bancontactbancontact.giropaygiropay.cardcard.latam_local_cardlatam_local_card.not_applicablenot_applicable.
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

Deprecated

This operation is obsoleted by the Retrieve a payment source API.

Retrieves the credit card for the customer id.

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

Sample Response [ JSON ]

Show more...
{"card": { "card_type": "american_express", "created_at": 1517486946, "customer_id": "__test__XpbTXGTSRp3ELNCY", "expiry_month": 12, "expiry_year": 2022, "funding_type": "not_known", "gateway": "chargebee", "gateway_account_id": "gw___test__5SK2lMgOSRp3BOO1y", "iin": "378282", "last4": "0005", "masked_number": "***********0005", "object": "card", "payment_source_id": "pm___test__XpbTXGTSRp3ENNCc", "resource_version": 1517486946205, "status": "valid", "updated_at": 1517486946 }}

URL Format GET

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

Returns

card
always returned
Resource object representing card

Update card for a customer

Idempotency Supported

Deprecated

The Payment Sources API, with its additional options and improvements, obsoletes the Cards APIs. This operation is obsoleted by the following:

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.

Legacy behavior:
  • For sites created before March 1st, 2014: On making this request, the billing_address and vat_number of the customer are deleted and replaced by the values passed with this request. Ensure that you pass the billing address parameters and the vat_number parameters each time you make this request, to avoid losing the same information at the customer-level.
  • For sites created on or after March 1st, 2014: This request does not alter the billing_address and vat_number of the customer.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/customers/__test__XpbTXGTSRp3F3uCq/credit_card \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMgOSRp3BhV2u" \
     -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__XpbTXGTSRp3F3uCq/credit_card \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMgOSRp3BhV2u" \
     -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": 1517486950, "customer_id": "__test__XpbTXGTSRp3F3uCq", "expiry_month": 10, "expiry_year": 2022, "first_name": "Richard", "funding_type": "credit", "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMgOSRp3BhV2u", "iin": "401288", "issuing_country": "CA", "last4": "1881", "last_name": "Fox", "masked_number": "************1881", "object": "card", "payment_source_id": "pm___test__XpbTXGTSRp3FRuCt", "resource_version": 1517486950330, "status": "valid", "updated_at": 1517486950 }, "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517486948, "deleted": false, "excess_payments": 0, "first_name": "Richard", "id": "__test__XpbTXGTSRp3F3uCq", "last_name": "Fox", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMgOSRp3BhV2u", "object": "payment_method", "reference_id": "cus_J7rQYxGS0QeW4M/card_1IVbhxJv9j0DyntJN9j65gTP", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp3FRuCt", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517486950332, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517486950 } }

URL Format POST

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

Input Parameters

gateway_account_id
optional, string, max chars=50
The gateway account in which this payment source is stored.
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.

.

Returns

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

Switch gateway

Idempotency Supported

Deprecated

This request is obsoleted by the Switch gateway account API for Payment Sources.

Switches the gateway in which customer’s card information is stored. This is applicable only if the payment method is card.

Limitation
This request does not support switching between Braintree and Stripe payment gateways. Contact Chargebee Support to perform those actions.

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

Sample Response [ JSON ]

Show more...
{ "card": { "card_type": "visa", "created_at": 1517486948, "customer_id": "__test__XpbTXGTSRp3EldCh", "expiry_month": 12, "expiry_year": 2022, "funding_type": "not_known", "gateway": "pin", "gateway_account_id": "gw___test__5SK2lMgOSRp3EaR32", "iin": "411111", "last4": "1111", "masked_number": "************1111", "object": "card", "payment_source_id": "pm___test__XpbTXGTSRp3EwGCi", "resource_version": 1517486948483, "status": "valid", "updated_at": 1517486948 }, "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517486947, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp3EldCh", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "pin", "gateway_account_id": "gw___test__5SK2lMgOSRp3EaR32", "object": "payment_method", "reference_id": "EjZ45aBUKGOreGY1J5mObk2uJdp", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp3EwGCi", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517486948481, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517486948 } }

URL Format POST

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

Input Parameters

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

Returns

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

Copy card

Idempotency Supported

deprecated

The Payment Sources API, with its additional options and improvements, obsoletes the Cards APIs. This request is obsoleted by the Export payment source API.

Copies the customer’s card information to another payment gateway. This is useful if you want to port your customer’s card details to another gateway.

Limitation
This request does not support copying of cards between Braintree and Stripe payment gateways. Contact Chargebee Support to perform those actions.

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

Sample Response [ JSON ]

Show more...
{"third_party_payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMgOSRp3BhV2u", "object": "third_party_payment_method", "reference_id": "cus_J7rQxbSaNyG7Sd/card_1IVbhqJv9j0DyntJeFVNQdcz", "type": "card" }}

URL Format POST

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

Input Parameters

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

Returns

third_party_payment_method
always returned
Resource object representing third_party_payment_method

Delete card for a customer

Idempotency Supported

deprecated

The Payment Sources API, with its additional options and improvements, obsoletes the Cards APIs. This request is obsoleted by the Delete a payment source API.

Deletes the card for a customer. Upon successful deletion the auto_collection attribute for the customer is set to off and a card_deleted event is triggered. If there is no card found at the gateway for the customer, this API returns without errors.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/customers/__test__XpbTXGTSRp3DuPCO/delete_card \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/customers/__test__XpbTXGTSRp3DuPCO/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": 1517486944, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp3DuPCO", "last_name": "Henry", "net_term_days": 0, "object": "customer", "pii_cleared": "active", "preferred_currency_code": "USD", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517486945850, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517486945 }}

URL Format POST

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

Returns

customer
always returned
Resource object representing customer