The following table lists the Payment Sources API operations alongside the equivalent Card API operations:
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
}
Identifier of the payment source.
string, max chars=40
Current status of the card.
enumerated stringPossible values are
validA valid and active credit card.expiringA card which is expiring in the current month.expiredAn expired card.
Name of the gateway this payment source is stored with.
enumerated stringPossible 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.ingenico_directIngenico ePayments.exactExact Payments gateway.not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
The gateway account to which this payment source is stored with.
optional, string, max chars=50
Reference transaction id which used for transactions.
optional, string, max chars=50
Cardholder's first name.
optional, string, max chars=50
Cardholder's last name.
optional, string, max chars=50
The Issuer Identification Number, i.e. the first six digits of the card number.
string, min chars=6, max chars=6
Last four digits of the card number.
string, min chars=4, max chars=4
Card type.
optional, enumerated stringPossible 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.
Card Funding type.
enumerated stringPossible values are
creditA credit card.debitA debit card.prepaidA prepaid card.not_knownAn unknown card.
Card expiry month.
integer, min=1, max=12
2-letter(alpha2) ISO country code.
optional, string, max chars=50
Address line 1, as available in card billing address.
optional, string, max chars=150
Address line 2, as available in card billing address.
optional, string, max chars=150
City, as available in card billing address.
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
).
optional, string, max chars=50
The state/province name.
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
Timestamp indicating when this card resource is created.
timestamp(UTC) in seconds
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
Timestamp indicating when this credit card resource was last updated.
optional, timestamp(UTC) in seconds
The IP address of the customer. Used primarily for referral integration and EU VAT validation.
optional, string, max chars=50
optional, enumerated stringPossible values are
idealideal.sofortsofort.bancontactbancontact.giropaygiropay.not_applicablenot_applicable.
Identifier of the customer.
string, max chars=50
Masked credit card number that is safe to show.
optional, string, max chars=19
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}
Resource object representing card.
always returned
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
parameter (now deprecated), 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__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
The gateway account in which this payment source is stored.
optional, string, max chars=50
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
Cardholder's first name.
optional, string, max chars=50
Cardholder's last name.
optional, string, max chars=50
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
Card expiry month.
required, integer, min=1, max=12
Card expiry year.
required, integer
The card verification value (CVV). If you are using
Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520
Address line 1, as available in card billing address.
optional, string, max chars=150
Address line 2, as available in card billing address.
optional, string, max chars=150
City, as available in card billing address.
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
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
Resource object representing customer.
always returned
Resource object representing card.
always returned
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__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
The gateway account you want to switch to.
required, string, max chars=50
Resource object representing customer.
always returned
Resource object representing card.
always returned
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__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
The gateway account you want to copy the card.
required, string, max chars=50
Resource object representing third_party_payment_method.
always returned
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__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
Resource object representing customer.
always returned