Settings
API Version
Product Catalog
Library

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 resourceUse instead
Retrieve card for a customerRetrieve a payment source
Update card for a customer
Switch gatewaySwitch gateway account
Copy cardExport payment source
Delete card for a customerDelete 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 }

API Index URL

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

Model Class

 

      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 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.chargebee_paymentsChargebee Payments gatewayadyenAdyen is a payment gateway.stripeStripe is a payment gateway.
 
 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.
 
 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.
 
 Show all values[+]
 
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 is powered by payment method. 
 
Possible values are
 
 
idealidealsofortsofortbancontactbancontactgiropaygiropay
 
 Show all values[+]
 
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. 
 
 
  
payment_source_id payment_source_id
 

          string, max chars=40
 Identifier of the payment source 
 
status 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 gateway
 

          enumerated string
 Name of the gateway this payment source is stored with. 
 
Possible values are
 
 
chargebeeChargebee test gateway.chargebee_paymentsChargebee Payments gatewayadyenAdyen is a payment gateway.stripeStripe is a payment gateway.
 
 Show all values[+]
gateway_account_id gateway_account_id
 

          optional, string, max chars=50
 The gateway account to which this payment source is stored with. 
 
ref_tx_id ref_tx_id
 

          optional, string, max chars=50
 Reference transaction id which used for transactions 
 
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
 
 
visaA Visa card.mastercardA MasterCard.american_expressAn American Express card.discoverA Discover card.
 
 Show all values[+]
funding_type funding_type
 

          enumerated string
 Card Funding type 
 
Possible values are
 
 
creditA credit card.debitA debit card.prepaidA prepaid card.not_knownAn unknown card.
 
 Show all values[+]
expiry_month expiry_month
 

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

          integer
 Card expiry year. 
 
issuing_country issuing_country
 

          optional, string, max chars=50
 two-letter(alpha2) ISO country code. 
 
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. 
 
created_at created_at
 

          timestamp(UTC) in seconds
 Timestamp indicating when this card resource is created. 
 
resource_version 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 updated_at
 

          optional, timestamp(UTC) in seconds
 Timestamp indicating when this credit card resource was last updated. 
 
ip_address ip_address
 

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

          optional, enumerated string
 Card is powered by payment method. 
 
Possible values are
 
 
idealidealsofortsofortbancontactbancontactgiropaygiropay
 
 Show all values[+]
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
      
  
 
  Try in API Explorer
   
Deprecated
This operation is obsoleted by the Retrieve a payment source API
.
Retrieves the credit card for the customer id.
  

        Sample Request
      
 

  Try in API Explorer

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

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    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}
    
 
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
 
 
  Try in API Explorer
   
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
      
 

  Try in API Explorer

 
 
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
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    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
    
 
Method
 
 
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. 
 
preferred_scheme[]
 

      optional, enumerated string 
 null 
Possible values are
 
 
cartes_bancairesmastercardvisa
 
 Show all values[+]
 
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  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
 
 
  Try in API Explorer
   
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
      
 

  Try in API Explorer

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

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    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
    
 
Method
 
 
Input Parameters
 
  
 
gateway_account_id[]
 

      required, string, max chars=50 
 The gateway account you want to switch to. 
 
 
    
 
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
    

      Copy card
      
 
Idempotency Supported
 
 
  Try in API Explorer
   
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
      
 

  Try in API Explorer

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

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    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
    
 
Method
 
 
Input Parameters
 
  
 
gateway_account_id[]
 

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

      always returned 
 Resource object representing third_party_payment_method
 
Sample admin console URL
 

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

      Delete card for a customer
      
 
Idempotency Supported
 
 
  Try in API Explorer
   
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
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/customers/__test__XpbTXGTSRp3DuPCO/delete_card \
     -X POST  \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    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
    
 
Method
 
  
   
 
    
 
Returns
 
customer  customer
 

      always returned 
 Resource object representing customer
 
Sample admin console URL
 

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