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

Payment sources

Updates
This API obsoletes the Cards API in Chargebee.

Represents the payment source for the customer. Specific types of payment source (Card, Direct Debit, Paypal Express Checkout, etc.) is defined as sub-resource in the response object. You can find the list of supported payment sources and the expected input parameters here. See Payment source attributes for a descriptive list of attributes and payment source types.

Sample payment source [ JSON ]

{ "card": { "brand": "visa", "expiry_month": 5, "expiry_year": 2022, "first_name": "MyCard", "funding_type": "credit", "iin": "******", "last4": "4242", "last_name": "testing", "masked_number": "************4242", "object": "card" }, "created_at": 1517487233, "customer_id": "__test__XpbTXGTSRp4QZ1EK", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "id": "pm___test__XpbTXGTSRp4R8ZEN", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVykqiooX1ng/card_1IVbmWJv9j0DyntJS7Bzo5q5", "resource_version": 1517487233588, "status": "valid", "type": "card", "updated_at": 1517487233 }

Payment source attributes

id
string, max chars=40
Identifier of the payment source
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 payment source resource was last updated.
created_at
timestamp(UTC) in seconds
Timestamp indicating when this payment source resource is created.
customer_id
string, max chars=50
Identifier of the customer with whom this payment source is associated.
type
enumerated string
Type of payment source
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.apple_payPayments made via Apple Pay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.
Show all values[+]
reference_id
string, max chars=200
The reference id. In the case of Amazon and PayPal this will be the 'billing agreement id'. For GoCardless direct debit this will be 'mandate id'. In the case of card payments this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one time temporary token provided by gateways like Stripe.
status
enumerated string, default=valid
Current status of the payment source.
Possible values are
validA payment source that is valid and active.expiringA payment source that is expiring (like card's status based on its expiry date).expiredA payment source that has expired.invalidThe billing agreement cannot be used. It might become valid again either automatically or due to customer action.pending_verificationThe payment source needs to be verified.
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.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.
ip_address
optional, string, max chars=50
The IP address of the customer. Used primarily for referral integration and EU VAT validation.
issuing_country
optional, string, max chars=50
two-letter(alpha2) ISO country code.
deleted
boolean
Indicates that this resource has been deleted.
business_entity_id
optional, string, max chars=50
The unique ID of the business entity of this payment_source. This is always the same as the business entity of the customer.

card
Show attributes[+]
optional, card
Card details associated with this payment source.
Card attributes
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
brand
enumerated string
Card brand
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.bancontactA Bancontact card.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.
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.
masked_number
optional, string, max chars=19
Masked credit card number that is safe to show.
bank_account
Show attributes[+]
optional, bank_account
Bank account details the direct debit or ACH or NetBanking agreement/mandate created with this payment source.
Bank account attributes
last4
string, min chars=4, max chars=4
Last four digits of the bank account number
name_on_account
optional, string, max chars=300
Account holder’s name as per bank account.
first_name
optional, string, max chars=150
Account holder’s first name as per bank account.
last_name
optional, string, max chars=150
Account holder’s last name as per bank account.
bank_name
optional, string, max chars=100
Name of account holder’s bank.
mandate_id
optional, string, min chars=1, max chars=50
Mandate Id. Applicable for SEPA, BACS, Autogiro, and BECS.
account_type
optional, enumerated string
Represents the account type used to create a payment source. Available for Authorize.net ACH and Razorpay NetBanking users only. If not passed, account type is taken as null.
Possible values are
checkingChecking AccountsavingsSavings Accountbusiness_checkingBusiness Checking AccountcurrentCurrent Account
echeck_type
optional, enumerated string
For Authorize.net ACH users only. Indicates the type of eCheck.
Possible values are
webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.
account_holder_type
optional, enumerated string
For Stripe ACH users only. Indicates the account holder type.
Possible values are
individualIndividual Account.companyCompany Account.
email
optional, string, max chars=70
Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
boleto
Show attributes[+]
optional, cust_voucher_source
Boleto payment source details of the customer
Boleto attributes
last4
string, min chars=4, max chars=4
Last four digits of unique id for voucher payment source ex: tax_id
first_name
optional, string, max chars=150
Customer first name as per voucher payment source.
last_name
optional, string, max chars=150
Customer last name as per voucher payment source.
email
optional, string, max chars=70
Email address associated Customer's voucher payment source.
billing_address
Show attributes[+]
optional, billing_address
Billing address for the payment source.
Billing address attributes
first_name
optional, string, max chars=150
The first name of the billing contact.
last_name
optional, string, max chars=150
The last name of the billing contact.
email
optional, string, max chars=70
The email address.
company
optional, string, max chars=250
The company name.
phone
optional, string, max chars=50
The phone number.
line1
optional, string, max chars=150
Address line 1
line2
optional, string, max chars=150
Address line 2
line3
optional, string, max chars=150
Address line 3
city
optional, string, max chars=50
The name of the city.
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).
state
optional, string, max chars=50
State or Province
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.


zip
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
validation_status
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
amazon_payment
Show attributes[+]
optional, amazon_payment
Amazon payments details associated with this payment source.
Amazon payment attributes
email
optional, string, max chars=70
Email address associated with Amazon payment account
agreement_id
optional, string, max chars=50
Billing agreement id
upi
Show attributes[+]
optional, upi
Represents the payment method that allows you to make payments directly using a bank account.
Upi attributes
vpa
optional, string, max chars=50
A unique identifier mapped with an individuals bank account to help UPI track the account.
paypal
Show attributes[+]
optional, paypal
PayPal Express Checkout details associated with this payment source.
Paypal attributes
email
optional, string, max chars=70
Email address associated with PayPal Express Checkout
agreement_id
optional, string, max chars=50
Billing agreement id
mandates
Show attributes[+]
optional, list of mandate
Mandate details associated with the payment source.
Mandate attributes
id
string, max chars=250
A unique mandate identifier used for recurring payments.
subscription_id
string, max chars=50
Chargebee’s subscription id used to find the mapping between the payment source and the Subscription.
created_at
timestamp(UTC) in seconds
Timestamp indicating when the mandate is created

Create using gateway temporary token

Idempotency Supported

This API offers an alternative way to create a payment source using a single-use gateway temporary token, which is generally provided by your payment gateway. In the case of Stripe, this temporary token is generated according to the instruction detailed in Stripe documentation.

Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_temp_token \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Mx02v" \
     -d customer_id="__test__XpbTXGTSRp4QZ1EK" \
     -d type="card" \
     -d tmp_token="tok_1IVbmWJv9j0DyntJuLTiAhzK"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_temp_token \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Mx02v" \
     -d customer_id="__test__XpbTXGTSRp4QZ1EK" \
     -d type="card" \
     -d tmp_token="tok_1IVbmWJv9j0DyntJuLTiAhzK"

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517487231, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4QZ1EK", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "object": "payment_method", "reference_id": "cus_J7rVykqiooX1ng/card_1IVbmWJv9j0DyntJS7Bzo5q5", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp4R8ZEN", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487233590, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487233 }, "payment_source": { "card": { "brand": "visa", "expiry_month": 5, "expiry_year": 2022, "first_name": "MyCard", "funding_type": "credit", "iin": "******", "last4": "4242", "last_name": "testing", "masked_number": "************4242", "object": "card" }, "created_at": 1517487233, "customer_id": "__test__XpbTXGTSRp4QZ1EK", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "id": "pm___test__XpbTXGTSRp4R8ZEN", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVykqiooX1ng/card_1IVbmWJv9j0DyntJS7Bzo5q5", "resource_version": 1517487233588, "status": "valid", "type": "card", "updated_at": 1517487233 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_temp_token

Input Parameters

customer_id
required, string, max chars=50
Identifier of the customer with whom this payment source is associated.
gateway_account_id
optional, string, max chars=50
The gateway account to which the payment source is associated.
type
required, enumerated string
Type of payment source.
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.apple_payPayments made via Apple Pay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.
Show all values[+]
tmp_token
required, string, max chars=65k
Single-use token created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
issuing_country
optional, string, max chars=50
2-letter (alpha2) ISO country code. Indicates your customer's payment method country of issuance. Applicable for PayPal via Braintree.
replace_primary_payment_source
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
additional_information
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
.

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source

Create using permanent token

Idempotency Supported

This API provides an alternative way to create a payment source using a permanent token, instead of having to add the full payment method details via API or the Chargebee UI. Permanent tokens are provided by payment gateways such as Stripe.

Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_permanent_token \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Q5TE9" \
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Mx02v" \
     -d reference_id="cus_J7rVCB7oVNyDJF" \
     -d type="card"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_permanent_token \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Q5TE9" \
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Mx02v" \
     -d reference_id="cus_J7rVCB7oVNyDJF" \
     -d type="card"

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517487229, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4Q5TE9", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "object": "payment_method", "reference_id": "cus_J7rVCB7oVNyDJF/card_1IVbmUJv9j0DyntJninpvymH", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp4QTuEF", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487231068, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487231 }, "payment_source": { "card": { "brand": "visa", "expiry_month": 12, "expiry_year": 2022, "funding_type": "credit", "iin": "******", "last4": "1111", "masked_number": "************1111", "object": "card" }, "created_at": 1517487231, "customer_id": "__test__XpbTXGTSRp4Q5TE9", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "id": "pm___test__XpbTXGTSRp4QTuEF", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVCB7oVNyDJF/card_1IVbmUJv9j0DyntJninpvymH", "resource_version": 1517487231066, "status": "valid", "type": "card", "updated_at": 1517487231 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_permanent_token

Input Parameters

customer_id
required, string, max chars=50
Identifier of the customer with whom this payment source is associated.
type
required, enumerated string
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.apple_payPayments made via Apple Pay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.
Show all values[+]
gateway_account_id
optional, string, max chars=50
The gateway account to which the payment source is associated.
reference_id
required, string, max chars=200
The reference id. In the case of Amazon and PayPal this will be the billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one-time temporary token provided by gateways like Stripe.
issuing_country
optional, string, max chars=50
2-letter (alpha2) ISO country code. Indicates your customer's payment method country of issuance. Applicable for PayPal via Braintree.
replace_primary_payment_source
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
additional_information
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
.

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source

Create using Chargebee token

Idempotency Supported
Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_token \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4REKES" \
     -d token_id="cb_tok___test__XpbTXGTSRp4RaBEV"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_token \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4REKES" \
     -d token_id="cb_tok___test__XpbTXGTSRp4RaBEV"

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517487233, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4REKES", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "object": "payment_method", "reference_id": "cus_J7rVlNvtSznu6p/card_1IVbmYJv9j0DyntJOIWtQCkk", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp4RqgEX", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487236333, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487236 }, "payment_source": { "card": { "brand": "visa", "expiry_month": 5, "expiry_year": 2022, "first_name": "MyCard", "funding_type": "credit", "iin": "******", "last4": "4242", "last_name": "testing", "masked_number": "************4242", "object": "card" }, "created_at": 1517487236, "customer_id": "__test__XpbTXGTSRp4REKES", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "id": "pm___test__XpbTXGTSRp4RqgEX", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVlNvtSznu6p/card_1IVbmYJv9j0DyntJOIWtQCkk", "resource_version": 1517487236331, "status": "valid", "type": "card", "updated_at": 1517487236 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_token

Input Parameters

customer_id
required, string, max chars=50
Identifier of the customer with whom this payment source is associated.
replace_primary_payment_source
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
token_id
required, string, max chars=40
Token generated by Chargebee JS representing payment method details.

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source

Create using payment intent

Idempotency Supported
Used to attach the card to the customer after 3DS completion. Learn more on the 3DS implementation via Chargebee APIs.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_payment_intent \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4MunE0" \
     -d payment_intent[gateway_account_id]="gw___test__5SK2lMpwSRp4Mx02v" \
     -d payment_intent[gw_token]="pi_1IVbmIJv9j0DyntJo1AUvK4o"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_payment_intent \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4MunE0" \
     -d payment_intent[gateway_account_id]="gw___test__5SK2lMpwSRp4Mx02v" \
     -d payment_intent[gw_token]="pi_1IVbmIJv9j0DyntJo1AUvK4o"

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517487217, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4MunE0", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "object": "payment_method", "reference_id": "cus_J7rVjoqwlD18Ei/pm_1IVbmIJv9j0DyntJCh6glSQB", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp4Q00E4", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487229215, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487229 }, "payment_source": { "card": { "brand": "visa", "expiry_month": 7, "expiry_year": 2050, "funding_type": "credit", "iin": "******", "last4": "3055", "masked_number": "************3055", "object": "card" }, "created_at": 1517487229, "customer_id": "__test__XpbTXGTSRp4MunE0", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "id": "pm___test__XpbTXGTSRp4Q00E4", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVjoqwlD18Ei/pm_1IVbmIJv9j0DyntJCh6glSQB", "resource_version": 1517487229213, "status": "valid", "type": "card", "updated_at": 1517487229 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_payment_intent

Input Parameters

customer_id
required, string, max chars=50
Identifier of the customer with whom this payment source is associated.
replace_primary_payment_source
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
+
payment_intent
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
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.
payment_intent[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.
payment_intent[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.
payment_intent[payment_method_type]
optional, enumerated string
The list of payment method types (For example, card, ideal, sofort, bancontact, etc.) this Payment Intent is allowed to use. If payment method type is empty, Card is taken as the default type for all gateways except Razorpay.
Possible values are
cardcardidealidealsofortsofortbancontactbancontact
google_paygoogle_paydotpaydotpaygiropaygiropayapple_payapple_payupiupinetbanking_emandatesnetbanking_emandatespaypal_express_checkoutpaypal_express_checkoutdirect_debitdirect_debitboletoboleto
Show all values[+]
payment_intent[reference_id]
optional, string, max chars=65k
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
payment_intent[additional_info]
optional, jsonobject
Applicable only for Braintree gateway. Can be used only for Braintree’s Premium Fraud Management Tools. Pass a stringified JSON containing the device_session_id and fraud_merchant_id as an input to fingerprint. Here’s a sample to it.
payment_intent[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source

Create a card payment source

Idempotency Supported
Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_card \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Mg0Dr" \
     -d card[number]="378282246310005" \
     -d card[cvv]="100" \
     -d card[expiry_year]=2022 \
     -d card[expiry_month]=12
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_card \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Mg0Dr" \
     -d card[number]="378282246310005" \
     -d card[cvv]="100" \
     -d card[expiry_year]=2022 \
     -d card[expiry_month]=12

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517487216, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4Mg0Dr", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "chargebee", "gateway_account_id": "gw___test__5SK2lMpwSRp4LJJ1y", "object": "payment_method", "reference_id": "tok___test__XpbTXGTSRp4MkpDu", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp4Ml3Dv", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487216760, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487216 }, "payment_source": { "card": { "brand": "american_express", "expiry_month": 12, "expiry_year": 2022, "funding_type": "not_known", "iin": "378282", "last4": "0005", "masked_number": "***********0005", "object": "card" }, "created_at": 1517487216, "customer_id": "__test__XpbTXGTSRp4Mg0Dr", "deleted": false, "gateway": "chargebee", "gateway_account_id": "gw___test__5SK2lMpwSRp4LJJ1y", "id": "pm___test__XpbTXGTSRp4Ml3Dv", "object": "payment_source", "reference_id": "tok___test__XpbTXGTSRp4MkpDu", "resource_version": 1517487216756, "status": "valid", "type": "card", "updated_at": 1517487216 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_card

Input Parameters

customer_id
required, string, max chars=50
Identifier of the customer with whom this payment source is associated.
replace_primary_payment_source
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
+
card
Parameters for card
pass parameters as card[<param name>]
card[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
card[first_name]
optional, string, max chars=50
Cardholder's first name
card[last_name]
optional, string, max chars=50
Cardholder's last name
card[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.
card[expiry_month]
required, integer, min=1, max=12
Card expiry month.
card[expiry_year]
required, integer
Card expiry year.
card[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.
card[billing_addr1]
optional, string, max chars=150
Address line 1, as available in card billing address.
card[billing_addr2]
optional, string, max chars=150
Address line 2, as available in card billing address.
card[billing_city]
optional, string, max chars=50
City, as available in card billing address.
card[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).
card[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.
card[billing_zip]
optional, string, max chars=20
Postal or Zip code, as available in card billing address.
card[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.

card[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source

Create a bank account payment source

Idempotency Supported

This API adds a Direct Debit payment source for a customer. The bank account details collected from your customer are passed as input to this API.

Automated Clearing House (ACH) Network

ACH is an electronic network for passing financial transactions in the US. Chargebee currently supports ACH via Stripe , Authorize.Net, and GoCardless.

Bank account verification

Once the bank account has been added, it needs to be verified.

Single Euro Payment Area (SEPA)

SEPA is an initiative that integrates bank transfer payments denominated in euro. It is supported via GoCardless, Stripe and Adyen.

Note:
  • For SEPA via Stripe, it is mandatory to pass user details such as IP address and device information.
  • For GoCardless, local bank details can be passed instead of IBAN.

Bacs Payment Schemes Limited (Bacs) and Bg Autogiro

Bacs is an organization that manages the Direct Debit and Direct Credit payment methods in the UK. Bg Autogiro is a Direct Debit scheme for krona denominated payments in Sweden. Both Bacs and Bg Autogiro are supported via GoCardless.

Bulk Electronic Clearing System (BECS) and Pre-Authorized Debit (PAD)

BECS is an automated payment method for Direct Debit in Australia and New Zealand while PAD does the same for Canada. GoCardless supports both.

For Direct Debit, the customer needs to accept a mandate that allows the merchant to debit their bank account. This agreement PDF can be obtained using the Retrieve direct debit agreement PDF API.

If the customer has already reached the payment source limit allowed for the site, pass replace_primary_payment_source as true. Alternatively, delete one of the payment sources first and then add the bank account payment source for the customer.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_bank_account \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Ly9Dj" \
     -d bank_account[gateway_account_id]="gw___test__5SK2lMpwSRp4Ljs2t" \
     -d bank_account[account_number]="000222222227" \
     -d bank_account[routing_number]="110000000" \
     -d bank_account[bank_name]="US Bank" \
     -d bank_account[account_holder_type]="individual" \
     -d bank_account[account_type]="savings" \
     -d bank_account[first_name]="Shay" \
     -d bank_account[last_name]="Liam"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_bank_account \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Ly9Dj" \
     -d bank_account[gateway_account_id]="gw___test__5SK2lMpwSRp4Ljs2t" \
     -d bank_account[account_number]="000222222227" \
     -d bank_account[routing_number]="110000000" \
     -d bank_account[bank_name]="US Bank" \
     -d bank_account[account_holder_type]="individual" \
     -d bank_account[account_type]="savings" \
     -d bank_account[first_name]="Shay" \
     -d bank_account[last_name]="Liam"

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": true, "auto_collection": "on", "created_at": 1517487213, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4Ly9Dj", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Ljs2t", "object": "payment_method", "reference_id": "cus_J7rVKldNI2hKt0/ba_1IVbmEJv9j0DyntJTe5oRPZE", "status": "pending_verification", "type": "direct_debit" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp4MS7Dm", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487215586, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487215 }, "payment_source": { "bank_account": { "account_holder_type": "individual", "account_type": "not_applicable", "bank_name": "US Bank", "last4": "2227", "name_on_account": "Shay Liam", "object": "bank_account" }, "created_at": 1517487215, "customer_id": "__test__XpbTXGTSRp4Ly9Dj", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Ljs2t", "id": "pm___test__XpbTXGTSRp4MS7Dm", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVKldNI2hKt0/ba_1IVbmEJv9j0DyntJTe5oRPZE", "resource_version": 1517487215582, "status": "pending_verification", "type": "direct_debit", "updated_at": 1517487215 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_bank_account

Input Parameters

customer_id
required, string, max chars=50
Identifier of the customer with whom this payment source is associated.
issuing_country
optional, string, max chars=50
2-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
replace_primary_payment_source
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
+
bank_account
Parameters for bank_account
pass parameters as bank_account[<param name>]
bank_account[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
bank_account[iban]
optional, string, min chars=10, max chars=50
Account holder’s International Bank Account Number. For the GoCardless platform, this can be the local bank details
bank_account[first_name]
optional, string, max chars=150
Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
bank_account[last_name]
optional, string, max chars=150
Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
bank_account[company]
optional, string, max chars=250
Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
bank_account[email]
optional, string, max chars=70
Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
bank_account[phone]
optional, string, max chars=50
Phone number of the account holder that is linked to the bank account.
bank_account[bank_name]
optional, string, max chars=100
Name of account holder’s bank.
bank_account[account_number]
optional, string, min chars=4, max chars=17
Account holder’s bank account number.
bank_account[routing_number]
optional, string, min chars=3, max chars=9
Bank account routing number.
bank_account[bank_code]
optional, string, max chars=20
Indicates the bank code.
bank_account[account_type]
optional, enumerated string
Represents the account type used to create a payment source. Available for Authorize.net ACH and Razorpay NetBanking users only. If not passed, account type is taken as null.
Possible values are
checkingChecking AccountsavingsSavings Accountbusiness_checkingBusiness Checking AccountcurrentCurrent Account
bank_account[account_holder_type]
optional, enumerated string
For Stripe ACH users only. Indicates the account holder type.
Possible values are
individualIndividual Account.companyCompany Account.
bank_account[echeck_type]
optional, enumerated string
For Authorize.net ACH users only. Indicates the type of eCheck.
Possible values are
webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.
bank_account[swedish_identity_number]
optional, string, min chars=10, max chars=12
For GoCardless Autogiro users only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
bank_account[billing_address]
optional, jsonobject
The billing address associated with the bank account. The value is a JSON object with the following keys and their values:
  • first_name:(string, max chars=150) The first name of the contact.
  • last_name:(string, max chars=150) The last name of the contact.
  • company_name:(string, max chars=250) The company name for the address.
  • line1:(string, max chars=180) The first line of the address.
  • line2:(string, max chars=180) The second line of the address.
  • country:(string) The name of the country for the address.
  • country_code:(string, max chars=50) The two-letter, ISO 3166 alpha-2 country code for the address.
  • state:(string, max chars=50) The name of the state or province for the address. When not provided, this is set automatically for US, Canada, and India.
  • state_code:(string, max chars=50) The ISO 3166-2 state/province code without the country prefix. This is 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).
  • city:(string, max chars=50) The city name for the address.
  • postal_code:(string, max chars=20) The postal or ZIP code for the address.
  • phone:(string, max chars=50) The contact phone number for the address.
  • email:(string, max chars=70) The contact email address for the address.

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source

Update a card payment source

Idempotency Supported
Merchants look to update card details when:
  • The billing address of a customer has changed. In such a case, modify the billing address in the Chargebee and the payment gateway.
  • The expiration date of the card has been extended by the bank. (This usually happens when the date of card expiry is in near future).

Multiple parameters such as address, expiry date, month, and so on, can be updated through this API.

Meta data can also be added additionally(supported in Stripe only). Metadata is a JSON object. It is used to store additional information about customers.

In Stripe and Braintree payment gateways, changes in card details are auto-updated. This feature can also be used for other payment gateways in which auto-update is not enabled or is not supported by Chargebee.

Note: This endpoint supports Chargebee Test Gateway, Stripe, Braintree, Authorize.net, Worldpay US eCom, and WorldPay Direct Integration. For all other gateways, your customers must re-enter the full card details to update existing card details. For example, consider a customer not using the gateways mentioned above and wants to update the card[billing_addr1] parameter. In such a case, the customer must re-enter the value of all the parameters present in the card object.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4Xy9FR/update_card \
     -u {site_api_key}:\
     -d card[first_name]="John" \
     -d card[last_name]="Doe" \
     -d card[expiry_month]=5 \
     -d card[expiry_year]=2022 \
     -d card[billing_addr1]="#678 Mission Street" \
     -d card[billing_city]="New York City" \
     -d card[billing_zip]="10002" \
     -d card[billing_state_code]="NY" \
     -d card[billing_country]="US"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4Xy9FR/update_card \
     -u {site_api_key}:\
     -d card[first_name]="John" \
     -d card[last_name]="Doe" \
     -d card[expiry_month]=5 \
     -d card[expiry_year]=2022 \
     -d card[billing_addr1]="#678 Mission Street" \
     -d card[billing_city]="New York City" \
     -d card[billing_zip]="10002" \
     -d card[billing_state_code]="NY" \
     -d card[billing_country]="US"

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517487258, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4Xi1FQ", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "object": "payment_method", "reference_id": "cus_J7rVemdQKHVECd/card_1IVbmxJv9j0DyntJlQ8osjf2", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp4Xy9FR", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487261178, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487261 }, "payment_source": { "card": { "billing_addr1": "#678 Mission Street", "billing_city": "New York City", "billing_country": "US", "billing_zip": "10002", "brand": "visa", "expiry_month": 5, "expiry_year": 2022, "first_name": "John", "funding_type": "credit", "iin": "******", "last4": "1111", "last_name": "Doe", "masked_number": "************1111", "object": "card" }, "created_at": 1517487259, "customer_id": "__test__XpbTXGTSRp4Xi1FQ", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "id": "pm___test__XpbTXGTSRp4Xy9FR", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVemdQKHVECd/card_1IVbmxJv9j0DyntJlQ8osjf2", "resource_version": 1517487261179, "status": "valid", "type": "card", "updated_at": 1517487261 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/update_card

Input Parameters

gateway_meta_data
optional, jsonobject
Additional data about this resource can be passed to Stripe gateway here in the JSON Format. This will be stored along with payment source at the gateway account.
reference_transaction
optional, string, max chars=50
Reference transaction is used for future purchases. This is only applicable for Vantiv.
+
card
Parameters for card
pass parameters as card[<param name>]
card[first_name]
optional, string, max chars=50
Cardholder's first name
card[last_name]
optional, string, max chars=50
Cardholder's last name
card[expiry_month]
optional, integer, min=1, max=12
Card expiry month.
card[expiry_year]
optional, integer
Card expiry year.
card[billing_addr1]
optional, string, max chars=150
Address line 1, as available in card billing address.
card[billing_addr2]
optional, string, max chars=150
Address line 2, as available in card billing address.
card[billing_city]
optional, string, max chars=50
City, as available in card billing address.
card[billing_zip]
optional, string, max chars=20
Postal or Zip code, as available in card billing address.
card[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).
card[billing_state]
optional, string, max chars=50
The state/province name.
card[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
payment_source
always returned
Resource object representing payment_source

Update a bank account payment source

Idempotency Supported
This API is used to update the payment source details of a customer. Information related to bank account payment source such as email, first name, and last name can be updated.

  • For GoCardless, Chargebee supports (ACH,BACS,SEPA,AUTOGIRO,BECS,BECS_NZ,PAD).
  • For Stripe, Chargebee only supports SEPA.

Notes

The API is only supported for the payment_method of type direct_debit.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__KyVnPbSerKGB5d/update_bank_account \
     -u {site_api_key}:\
     -d bank_account[email]="johndoe@example.com" \
     -d bank_account[first_name]="John" \
     -d bank_account[last_name]="Doe"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__KyVnPbSerKGB5d/update_bank_account \
     -u {site_api_key}:\
     -d bank_account[email]="johndoe@example.com" \
     -d bank_account[first_name]="John" \
     -d bank_account[last_name]="Doe"

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": true, "auto_collection": "on", "channel": "web", "created_at": 1517507082, "deleted": false, "email": "markhenry@example.com", "excess_payments": 0, "first_name": "Mark", "id": "__test__KyVnPbSerKFjFY", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__KyVnGoSerKFdA2t", "object": "payment_method", "reference_id": "cus_Jxe0kGs9uZuKX3/src_1JJiiNJv9j0DyntJXYkqBHE8", "status": "valid", "type": "direct_debit" }, "pii_cleared": "active", "preferred_currency_code": "EUR", "primary_payment_source_id": "pm___test__KyVnPbSerKGB5d", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517507084711, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517507084 }, "payment_source": { "bank_account": { "email": "johndoe@example.com", "last4": "3000", "mandate_id": "OI1M52OFAXGFQZRR", "name_on_account": "John Doe", "object": "bank_account" }, "created_at": 1517507084, "customer_id": "__test__KyVnPbSerKFjFY", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__KyVnGoSerKFdA2t", "id": "pm___test__KyVnPbSerKGB5d", "issuing_country": "DE", "object": "payment_source", "reference_id": "cus_Jxe0kGs9uZuKX3/src_1JJiiNJv9j0DyntJXYkqBHE8", "resource_version": 1517507084712, "status": "valid", "type": "direct_debit", "updated_at": 1517507084 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/update_bank_account

Input Parameters

+
bank_account
Parameters for bank_account
pass parameters as bank_account[<param name>]
bank_account[first_name]
optional, string, max chars=150
Account holder’s first name as per bank account.
bank_account[last_name]
optional, string, max chars=150
Account holder’s last name as per bank account.
bank_account[email]
optional, string, max chars=70
Account holder’s email address. All Direct Debit compliant emails will be sent to this email address.

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source

Verify bank account payment source

Idempotency Supported

This API can be used to verify bank accounts which have been added as payment source. This is applicable for Stripe ACH with micro-deposit mode bank accounts only. Stripe handles verification in two ways - via Plaid, and micro-deposit.

For verifying bank accounts via micro-deposit, Stripe deposits two small amounts to the bank account being added. These deposits will take 1-2 business days to appear on the customer’s bank statement. The bank statement description for the two micro-deposits contains the amount and the values deposited. Your customer will need to relay the value of the two deposits to you, after which you can verify the bank account. Once the bank account has been verified, the payment source will be marked as “Valid”.

Notes

A maximum of 10 failed verification attempts are allowed. Once this limit has been crossed, the bank account can no longer be verified, and will be marked as “Invalid” in Chargebee.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4YjRFc/verify_bank_account \
     -u {site_api_key}:\
     -d amount1=32 \
     -d amount2=45
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4YjRFc/verify_bank_account \
     -u {site_api_key}:\
     -d amount1=32 \
     -d amount2=45

Sample Response [ JSON ]

Show more...
{"payment_source": { "bank_account": { "account_holder_type": "individual", "account_type": "not_applicable", "bank_name": "US Bank", "last4": "2227", "name_on_account": "Shay Liam", "object": "bank_account" }, "created_at": 1517487262, "customer_id": "__test__XpbTXGTSRp4YNIFZ", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Ljs2t", "id": "pm___test__XpbTXGTSRp4YjRFc", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rW1Bl7xQoLOW/ba_1IVbmzJv9j0DyntJXpjNOH1r", "resource_version": 1517487263313, "status": "valid", "type": "direct_debit", "updated_at": 1517487263 }}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/verify_bank_account

Input Parameters

amount1
required, in cents, min=0
Value of the micro-deposits sent to the bank account.
amount2
required, in cents, min=0
Value of the micro-deposits sent to the bank account.

Returns

payment_source
always returned
Resource object representing payment_source

Retrieve a payment source

Retrieves the payment source identified by the unique identifier.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__KyVmmpTSneqVht \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__KyVmmpTSneqVht \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"payment_source": { "card": { "brand": "visa", "expiry_month": 12, "expiry_year": 2030, "funding_type": "credit", "iin": "411111", "last4": "1111", "masked_number": "************1111", "object": "card" }, "created_at": 1517467526, "customer_id": "__test__KyVmmpTSneqFXs", "deleted": false, "gateway": "stripe", "gateway_account_id": "gw___test__KyVmsTTSnefon30", "id": "pm___test__KyVmmpTSneqVht", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_NA13opXonQckcW/card_0MPh10J7ubj1SVcrJTe4m32g", "resource_version": 1517467526693, "status": "valid", "type": "card", "updated_at": 1517467526 }}

URL Format GET

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}

Returns

payment_source
always returned
Resource object representing payment_source

List payment sources

Lists all the payment sources
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode type[is]="card"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode type[is]="card"

Sample Response [ JSON ]

Show more...
{ "list": [ {"payment_source": { "card": { "brand": "visa", "expiry_month": 12, "expiry_year": 2022, "first_name": "Richard", "funding_type": "not_known", "iin": "411111", "last4": "1111", "last_name": "Fox", "masked_number": "************1111", "object": "card" }, "created_at": 1517487242, "customer_id": "__test__XpbTXGTSRp4SZ5En", "deleted": false, "gateway": "pin", "gateway_account_id": "gw___test__5SK2lMpwSRp4Sb831", "id": "pm___test__XpbTXGTSRp4TUQEq", "object": "payment_source", "reference_id": "LHqS22OIh4y61Af9CXHicQFCfuD", "resource_version": 1517487242630, "status": "valid", "type": "card", "updated_at": 1517487242 }}, {..} ], "next_offset": "[\"1517487233000\",\"209000000107\"]" }

URL Format GET

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

Input Parameters

limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
sort_by[<sort-order>]
optional, string filter
Sorts based on the specified attribute.
Supported attributes : created_at, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
Filter Params
For operator usages, see the Pagination and Filtering section.
subscription_id
optional, string, max chars=50
Unique subscription identifier that helps to retrieve the payment source of a subscription which has mandate associated to it.
customer_id[<operator>]
optional, string filter
To filter based on Customer Id.
Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is] = "3bdjnDnsdQn"
type[<operator>]
optional, enumerated string filter
Type of payment source. Possible values are : card, paypal_express_checkout, amazon_payments, direct_debit, generic, alipay, unionpay, apple_pay, wechat_pay, ideal, google_pay, sofort, bancontact, giropay, dotpay, upi, netbanking_emandates.
Supported operators : is, is_not, in, not_in

Example → type[is] = "card"
status[<operator>]
optional, enumerated string filter
Current status of the payment source. Possible values are : valid, expiring, expired, invalid, pending_verification.
Supported operators : is, is_not, in, not_in

Example → status[is_not] = "valid"
updated_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating when this payment source resource was last updated.
Supported operators : after, before, on, between

Example → updated_at[after] = "1435054328"
created_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating when this payment source resource is created.
Supported operators : after, before, on, between

Example → created_at[after] = "1435054328"

Returns

payment_source
always returned
Resource object representing payment_source
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.

Switch gateway account

Idempotency Supported

Switches the gateway in which this payment source information is stored.

This is applicable only if the payment source is present in Spreedly vault.

Notes

This operation does not support switching between Braintree and Stripe. If you need help using this API, contact support@chargebee.com.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4XbjFJ/switch_gateway_account \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Wrl37"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4XbjFJ/switch_gateway_account \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4Wrl37"

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1517487256, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4X57FI", "last_name": "Henry", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "pin", "gateway_account_id": "gw___test__5SK2lMpwSRp4Wrl37", "object": "payment_method", "reference_id": "UKZpy3LgND7f5jOIeAjwXbRsbEx", "status": "valid", "type": "card" }, "pii_cleared": "active", "preferred_currency_code": "USD", "primary_payment_source_id": "pm___test__XpbTXGTSRp4XbjFJ", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487258458, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487258 }, "payment_source": { "card": { "brand": "visa", "expiry_month": 12, "expiry_year": 2022, "funding_type": "not_known", "iin": "411111", "last4": "1111", "masked_number": "************1111", "object": "card" }, "created_at": 1517487258, "customer_id": "__test__XpbTXGTSRp4X57FI", "deleted": false, "gateway": "pin", "gateway_account_id": "gw___test__5SK2lMpwSRp4Wrl37", "id": "pm___test__XpbTXGTSRp4XbjFJ", "object": "payment_source", "reference_id": "UKZpy3LgND7f5jOIeAjwXbRsbEx", "resource_version": 1517487258565, "status": "valid", "type": "card", "updated_at": 1517487258 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/switch_gateway_account

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

Export payment source

Idempotency Supported

Copies this payment source 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 help using this API, contact support@chargebee.com.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4TUQEq/export_payment_source \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4SXM2z"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4TUQEq/export_payment_source \
     -u {site_api_key}:\
     -d gateway_account_id="gw___test__5SK2lMpwSRp4SXM2z"

Sample Response [ JSON ]

Show more...
{"third_party_payment_method": { "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4SXM2z", "object": "third_party_payment_method", "reference_id": "cus_J7rVdlHN2uZpSx/card_1IVbmjJv9j0DyntJPYARLiEw", "type": "card" }}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/export_payment_source

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 a payment source

Idempotency Supported

Deletes a payment source. Once the payment source is deleted, if

  • Deleted payment source is Primary, and Backup is available
    • The Backup payment source will become the Primary payment source.
  • Deleted payment source is Primary, and no Backup is available
    • The other payment source available, but not assigned to any subscription, will become the Primary payment source.

      Note: When multiple payment sources exist, the payment method added most recently will be considered.

    • If other payment sources available are assigned to subscriptions, the auto collection attribute for the customer will be set to Off, and the events card_deleted and payment_source_deleted will be triggered.
  • Deleted payment source is attached to subscriptions
    • Dunning will be initiated for subscriptions attached to this payment source if auto collection is set to On, and when no customer default is present.

If there is no such payment source present in the gateway for the customer, this API will return successfully without throwing any error.

Note:
If you delete the only available payment method of a customer in Chargebee, it also deletes the customer’s record at the gateway. To delete the payment method locally(delete only in Chargebee), use Local Delete a Payment Source API.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4SEvEe/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4SEvEe/delete \
     -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": 1517487236, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4Rx1Ed", "last_name": "Henry", "net_term_days": 0, "object": "customer", "pii_cleared": "active", "preferred_currency_code": "USD", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487238746, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487238 }, "payment_source": { "card": { "brand": "visa", "expiry_month": 12, "expiry_year": 2022, "funding_type": "credit", "iin": "411111", "last4": "1111", "masked_number": "************1111", "object": "card" }, "created_at": 1517487237, "customer_id": "__test__XpbTXGTSRp4Rx1Ed", "deleted": true, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "id": "pm___test__XpbTXGTSRp4SEvEe", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVgQok1LkbJ9/card_1IVbmbJv9j0DyntJhbTqsfn1", "resource_version": 1517487237828, "status": "valid", "type": "card", "updated_at": 1517487237 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/delete

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source

Local delete a payment source

Idempotency Supported

Deletes a payment method from Chargebee. Payment method in the payment gateway will not be affected.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4V0hEw/delete_local \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm___test__XpbTXGTSRp4V0hEw/delete_local \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "no_card", "created_at": 1517487247, "deleted": false, "excess_payments": 0, "first_name": "Mark", "id": "__test__XpbTXGTSRp4UhfEv", "last_name": "Henry", "net_term_days": 0, "object": "customer", "pii_cleared": "active", "preferred_currency_code": "USD", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1517487248592, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1517487248 }, "payment_source": { "card": { "brand": "visa", "expiry_month": 12, "expiry_year": 2022, "funding_type": "credit", "iin": "411111", "last4": "1111", "masked_number": "************1111", "object": "card" }, "created_at": 1517487248, "customer_id": "__test__XpbTXGTSRp4UhfEv", "deleted": true, "gateway": "stripe", "gateway_account_id": "gw___test__5SK2lMpwSRp4Mx02v", "id": "pm___test__XpbTXGTSRp4V0hEw", "issuing_country": "US", "object": "payment_source", "reference_id": "cus_J7rVsWKqWFpyBS/card_1IVbmmJv9j0DyntJVAKlFn5a", "resource_version": 1517487248475, "status": "valid", "type": "card", "updated_at": 1517487248 } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/delete_local

Returns

customer
always returned
Resource object representing customer
payment_source
always returned
Resource object representing payment_source