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. See Payment source attributes for a descriptive list of attributes and payment source types.

Sample payment source [ JSON ]

{ "id": "pm_3Nl8E2TQRL6rFd6", "object": "payment_source", "customer_id": "8avVGOkx8U1MX", "type": "card", "reference_id": "tok_3Nl8E2TQRL6rFI5", "status": "valid", "gateway": "chargebee", "gateway_account_id": "gw_3Nl8E2TQRL6pXo2", "card": { "iin": "411111", "last4": "1111", "funding_type": "credit", "expiry_month": 1, "expiry_year": 2022, "masked_number": "************1111", "object": "card", "brand": "visa" } }
id
Identifier of the payment source.
string, max chars=40
customer_id
Identifier of the customer with whom this payment source is associated.
string, max chars=50
type
Type of payment source.
enumerated string
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.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.
reference_id
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.
string, max chars=50
status
Current status of the payment source.
enumerated string, default=valid
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
Name of the gateway this payment source is stored with.
enumerated string
Possible values are
chargebeeChargebee test gateway.stripeStripe payment gateway.wepayWePay Gateway.braintreeBraintree payment gateway.
authorize_netAuthorize.net payment gateway.paypal_proPaypal Pro Account.pinPin payment gateway.ewayeWAY Account.eway_rapideWAY Rapid gateway.worldpayWorldPay payment gateway.balanced_paymentsBalanced payment gateway.beanstreamBeanstream Account.bluepayBluePay payment gateway.elavonElavon Virtual Merchant.first_data_globalFirst Data Global Gateway Virtual Terminal Account.hdfcHDFC Account.migsMasterCard Internet Gateway Service.nmiNMI gateway.ogoneOgone Account.paymillPAYMILL payment gateway.paypal_payflow_proPayPal Payflow Pro gateway.sage_paySage Pay gateway.tco2Checkout payment gateway.wirecardWireCard Account.gocardlessGoCardless.adyenAdyen.not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
gateway_account_id
The gateway account to which this payment source is stored with.
optional, string, max chars=50
ip_address
The IP address from where the payment source is created or updated. Used primarily for EU VAT validation.
optional, string, max chars=50
issuing_country
2-letter(alpha2) ISO country code.
optional, string, max chars=50
Card details associated with this payment source.
optional, card
Card attributes
first_name
Cardholder's first name.
optional, string, max chars=50
last_name
Cardholder's last name.
optional, string, max chars=50
iin
The Issuer Identification Number, i.e. the first six digits of the card number.
string, min chars=6, max chars=6
last4
Last four digits of the card number.
string, min chars=4, max chars=4
brand
Card brand.
enumerated string
Possible values are
visaA Visa card.mastercardA MasterCard.american_expressAn American Express card.discoverA Discover card.jcbA JCB card.diners_clubA Diner's Club card.otherCard belonging to types other than those listed above.
funding_type
Card Funding type.
enumerated string
Possible values are
creditA credit card.debitA debit card.prepaidA prepaid card.not_knownAn unknown card.not_applicableUsed for ACH. Not applicable for cards.
expiry_month
Card expiry month.
integer, min=1, max=12
expiry_year
Card expiry year.
integer
billing_addr1
Address line 1, as available in card billing address.
optional, string, max chars=150
billing_addr2
Address line 2, as available in card billing address.
optional, string, max chars=150
billing_city
City, as available in card billing address.
optional, string, max chars=50
billing_state_code
The ISO 3166-2 state/province code. Supported only for countries US,Canada and India.
optional, string, max chars=50
billing_state
The state/province name.
optional, string, max chars=50
billing_country
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
billing_zip
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
masked_number
Masked credit card number that is safe to show.
optional, string, max chars=19
bank_account
Show attributes[+]
Bank account details the direct debit or ACH agreement/mandate created with this payment source.
optional, bank_account
Bank account attributes
name_on_account
Name as in Bank Account.
optional, string, max chars=22
bank_name
Account holder's Bank name.
optional, string, max chars=100
mandate_id
Mandate Id. Applicable for GoCardless direct debit.
optional, string, min chars=5, max chars=17
account_type
Type of the account.
optional, enumerated string
Possible values are
checkingChecking Account.savingsSavings Account.
amazon_payment
Show attributes[+]
Amazon payments details associated with this payment source.
optional, amazon_payment
Amazon payment attributes
email
Email address associated with Amazon payment account.
optional, string, max chars=70
agreement_id
Billing agreement id.
optional, string, max chars=50
PayPal Express Checkout details associated with this payment source.
optional, paypal
Paypal attributes
email
Email address associated with PayPal Express Checkout.
optional, string, max chars=70
agreement_id
Billing agreement id.
optional, string, max chars=50

Adds a payment source for the customer using the single-use payment source token returned by vaults like Stripe/Braintree, which act as a substitute for your payment source details. Before calling this API, you should have submitted payment source details to the gateway (Stripe/Braintree) and gotten this token in return. You can use one of the following integration methodologies to get the token:

  • If you are using Stripe gateway, you can use Stripe.js with your payment details form.
  • If you are using Braintree gateway, you can use Braintree.js with your payment details form.
  • In case you are replacing the primary source, you can also use our Hosted Pages based integration which will replace the primary payment source internally. Use our Hosted Page - Update Card API to generate a 'Update Card' Hosted Page link.

Using this API reduces the PCI liability at your end, which is required if sensitive card info passes through your servers.

Note: If the customer has already reached the payment source limit allowed for the site, pass 'replace_primary_payment_source' as 'true'. Or, delete one of the payment sources first and then add card payment source for the customer.

Note: For customers signed up before 1st March 2014, if this is primary/first payment source for the customer, and the payment source billing information is specified in the input while generating the single-use token, the customer's Billing Info (i.e Billing Address and vat_number) will also be replaced with the new values automatically.

Sample Request
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_temp_token \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d type="card" \
     -d tmp_token="66H51492YE2926"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_temp_token \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d type="card" \
     -d tmp_token="66H51492YE2926"

Sample Response [ JSON ]

{ "payment_source": { "id": "pm_XpbKGJ9QRL7odzGd", "object": "payment_source", "customer_id": "8avVGOkx8U1MX", "type": "card", "reference_id": "cus_B9OnlNTIA8PZL8/card_oOzdjzlO1LxGEm", "status": "valid", "gateway": "stripe", "gateway_account_id": "gw_3Nl8E2TQRL73vX7A", "issuing_country": "US", "card": { "first_name": "MyCard", "last_name": "testing", "iin": "******", "last4": "4242", "funding_type": "credit", "expiry_month": 5, "expiry_year": 2022, "masked_number": "************4242", "object": "card", "brand": "visa" } }, "customer": { "id": "8avVGOkx8U1MX", "first_name": "Benjamin", "last_name": "Ross", "email": "Benjamin@test.com", "auto_collection": "on", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1412101809, "taxability": "taxable", "updated_at": 1501853877, "resource_version": 1501853877000, "deleted": false, "object": "customer", "card_status": "valid", "contacts": [ { "id": "d334f4g45", "first_name": "aasca", "last_name": "asas", "email": "sss@wss.asc", "label": "ascasc", "enabled": true, "send_account_email": true, "send_billing_email": false, "object": "contact" }, {..} ], "primary_payment_source_id": "pm_3Nl8E2TQRL6rFd6", "payment_method": { "object": "payment_method", "type": "card", "reference_id": "tok_3Nl8E2TQRL6rFI5", "gateway": "chargebee", "gateway_account_id": "gw_3Nl8E2TQRL6pXo2", "status": "valid" }, "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "unbilled_charges": 0, "preferred_currency_code": "USD" } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_temp_token
customer_id
Identifier of the customer with whom this payment source is associated.
required, string, max chars=50
gateway_account_id
The gateway account to which the payment source is associated.
optional, string, max chars=50
type
Type of payment source.
required, enumerated string
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.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.
tmp_token
The single-use card token returned by vaults like Stripe, which act as a substitute for your bank account details. Before calling this API, you should have submitted your bank account details to the gateway ( Stripe ) and gotten this token in return.
required, string, max chars=150
replace_primary_payment_source
Indicates whether the primary payment source should be replaced with this payment source.
optional, boolean, default=false
Resource object representing customer.
always returned
Resource object representing payment_source.
always returned

Creates payment source for a customer.

Note: This API is not supported for Chargebee Test Gateway, it is provided to help you understand the billing workflow in Chargebee.

PayPal Express Checkout
You can use this API if you are directly integrating PayPal Express Checkout in your website instead of using Chargebee's hosted pages. When your customer updates his payment source using PayPal Express Checkout, you will be provided with the Billing Agreement ID by PayPal. You can create the payment source for that customer in Chargebee by passing type as paypal_express_checkout and reference_id with the Billing Agreement ID.

Login and Pay with Amazon
You can use this API if you are directly integrating Login and Pay with Amazon in your website instead of using Chargebee's hosted pages. When your customer updates Amazon as a payment source, you will be provided with the Billing Agreement ID by Amazon. You can create the payment source for that customer in Chargebee by passing type as amazon_payments and reference_id with the Billing Agreement ID.

Card Payments
When the card details of your customer are stored in the vault of gateways such as Stripe or Braintree, you can use this API to create payment source in Chargebee for that customer using the reference id provided by them. To use this API, pass

  • type as card.
  • gateway_account_id with the gateway account associated with the card. If the gateway is not specified, the default gateway will be used.
  • reference_id with the identifier provided by the gateway/Spreedly to reference that specific card.

Reference id format for Card Payments
The format of reference_id will differ based on where the card is stored.

Stripe: In case of Stripe, the reference_id consists of a combination of Stripe Customer ID and Stripe Card ID separated by a forward slash (e.g. cus_63MnDn0t6kfDW7/card_6WjCF20vT9WN1G). If you are passing Stripe Customer ID alone, then Chargebee will store the card marked as active for that customer in Stripe.

Braintree: In the case of Braintree, the reference_id consists of a combination of Braintree Customer ID and Braintree Payment Method Token separated by a forward slash
(e.g. cus_63MnDn0t6kfDW7/card_6WjCF20vT9WN1G). If you are passing Braintree Customer ID alone, then Chargebee will store the card marked as default for that customer in Braintree.

Spreedly Card vault: If the card details are stored in Spreedly vault, then you need to provide the Spreedly token as reference_id.

Direct Debit Payments
When the bank account details of your customer are stored in the gateway vault, you can use this API to create the payment source with the reference id provided by them in Chargebee. To use this API, pass

  • type as direct_debit.
  • gateway_account_id with the gateway account where the bank account details are stored (e.g. authorize_net). If the gateway_account_id is not specified, the gateway supporting the direct debit will be used.
  • reference_id with the identifier provided by the gateway to reference the customer's bank account details.

Reference id format for Direct Debit Payments
The format of reference_id will differ based on where the bank account is stored.

Stripe: In the case of Stripe, the reference_id consists of a combination of Stripe Customer ID and Stripe Bank Account ID separated by a forward slash
(e.g. cus_8suoHaLQH4G5AW/ba_18b8z2KmcbENlhgU03RznRYW). If you are passing Stripe Customer ID alone, then Chargebee will store the first bank account details present in payment profile list of that customer in Stripe.

Authorize.Net: The reference_id consists of a combination of Authorize.Net's Customer Profile ID and Payment Profile ID separated by a forward slash (e.g. 2384383/34834382). If you are passing Authorize.Net's Customer Profile ID alone, then Chargebee will store the first bank account details present in payment profile list of that customer in Authorize.Net.

GoCardless: The reference_id is the GoCardless Customer Mandate ID (e.g. MD0077Z99TTQXK).

Note: While using this API to update payment method details, Card Verification will not happen even if it is enabled for that particular gateway.

Sample Request
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_permanent_token \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d type="paypal_express_checkout" \
     -d reference_id="B-66H51492YE2926358"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_using_permanent_token \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d type="paypal_express_checkout" \
     -d reference_id="B-66H51492YE2926358"

Sample Response [ JSON ]

{ "payment_source": { "id": "pm_XpbKGJ9QRL79k3Cu", "object": "payment_source", "customer_id": "3Nl8E2TQRL73sK70", "type": "card", "reference_id": "cus_B9Okq1soJ4clT3/card_HzmfQH7oCNEqfq", "status": "valid", "gateway": "stripe", "gateway_account_id": "gw_3Nl8E2TQRL73vX7A", "issuing_country": "US", "card": { "first_name": "Hello", "last_name": "World", "iin": "******", "last4": "4242", "funding_type": "credit", "expiry_month": 10, "expiry_year": 2020, "masked_number": "************4242", "object": "card", "brand": "visa" } }, "customer": { "id": "3Nl8E2TQRL73sK70", "first_name": "John", "last_name": "Doe", "email": "john@test.com", "auto_collection": "on", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1501853697, "taxability": "taxable", "updated_at": 1501853720, "resource_version": 1501853720000, "deleted": false, "object": "customer", "billing_address": { "first_name": "Hello", "last_name": "World", "phone": "122242222", "line1": "Wow", "line2": "Cool", "city": "Chennai", "state_code": "TN", "state": "Tamil Nadu", "country": "IN", "zip": "600041", "validation_status": "not_validated", "object": "billing_address" }, "card_status": "valid", "primary_payment_source_id": "pm_XpbKGJ9QRL79k3Cu", "payment_method": { "object": "payment_method", "type": "card", "reference_id": "cus_B9Okq1soJ4clT3/card_HzmfQH7oCNEqfq", "gateway": "stripe", "gateway_account_id": "gw_3Nl8E2TQRL73vX7A", "status": "valid" }, "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "unbilled_charges": 0, "preferred_currency_code": "USD" } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_using_permanent_token
customer_id
Identifier of the customer with whom this payment source is associated.
required, string, max chars=50
type
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
required, enumerated string
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.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.
gateway_account_id
The gateway account to which the payment source is associated.
optional, string, max chars=50
reference_id
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.
required, string, max chars=50
replace_primary_payment_source
Indicates whether the primary payment source should be replaced with this payment source.
optional, boolean, default=false
Resource object representing customer.
always returned
Resource object representing payment_source.
always returned

Adds card details to the customer. You can pass the credit card details collected from your customers to this API, to create the card payment source.

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 API's:

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

Sample Request
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_card \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d card[first_name]="Richard" \
     -d card[last_name]="Fox" \
     -d card[number]="4012888888881881" \
     -d card[expiry_month]="10" \
     -d card[expiry_year]="2022" \
     -d card[cvv]="999"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/create_card \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d card[first_name]="Richard" \
     -d card[last_name]="Fox" \
     -d card[number]="4012888888881881" \
     -d card[expiry_month]="10" \
     -d card[expiry_year]="2022" \
     -d card[cvv]="999"

Sample Response [ JSON ]

{ "payment_source": { "id": "pm_XpbKGJ9QRL7ouSGg", "object": "payment_source", "customer_id": "8avVGOkx8U1MX", "type": "card", "reference_id": "cus_B9OnlNTIA8PZL8/card_q2K6hBd89SjkMh", "status": "valid", "gateway": "stripe", "gateway_account_id": "gw_3Nl8E2TQRL73vX7A", "issuing_country": "CA", "card": { "first_name": "Richard", "last_name": "Fox", "iin": "401288", "last4": "1881", "funding_type": "credit", "expiry_month": 10, "expiry_year": 2022, "masked_number": "************1881", "object": "card", "brand": "visa" } }, "customer": { "id": "8avVGOkx8U1MX", "first_name": "Benjamin", "last_name": "Ross", "email": "Benjamin@test.com", "auto_collection": "on", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1412101809, "taxability": "taxable", "updated_at": 1501853878, "resource_version": 1501853878000, "deleted": false, "object": "customer", "card_status": "valid", "contacts": [ { "id": "d334f4g45", "first_name": "aasca", "last_name": "asas", "email": "sss@wss.asc", "label": "ascasc", "enabled": true, "send_account_email": true, "send_billing_email": false, "object": "contact" }, {..} ], "primary_payment_source_id": "pm_3Nl8E2TQRL6rFd6", "payment_method": { "object": "payment_method", "type": "card", "reference_id": "tok_3Nl8E2TQRL6rFI5", "gateway": "chargebee", "gateway_account_id": "gw_3Nl8E2TQRL6pXo2", "status": "valid" }, "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "unbilled_charges": 0, "preferred_currency_code": "USD" } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/create_card
customer_id
Identifier of the customer with whom this payment source is associated.
required, string, max chars=50
replace_primary_payment_source
Indicates whether the primary payment source should be replaced with this payment source.
optional, boolean, default=false
card
Parameters for card
pass parameters as card[<param name>]
card[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
card[first_name]
Cardholder's first name.
optional, string, max chars=50
card[last_name]
Cardholder's last name.
optional, string, max chars=50
card[number]
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required, string, max chars=1500
card[expiry_month]
Card expiry month.
required, integer, min=1, max=12
card[expiry_year]
Card expiry year.
required, integer
card[cvv]
The card verification value. If you are using Braintree.js, you can specify the Braintree encrypted cvv here.
optional, string, max chars=520
card[billing_addr1]
Address line 1, as available in card billing address.
optional, string, max chars=150
card[billing_addr2]
Address line 2, as available in card billing address.
optional, string, max chars=150
card[billing_city]
City, as available in card billing address.
optional, string, max chars=50
card[billing_state_code]
The ISO 3166-2 state/province code. The recommended way of passing the state/province information. Supported for US, Canada and India now. Further if this is specified, 'state' attribute should not be specified as it will be set automatically.
optional, string, max chars=50
card[billing_state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
card[billing_zip]
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
card[billing_country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
Resource object representing customer.
always returned
Resource object representing payment_source.
always returned

Merchants look to add/update card details when such details are not furnished or when they have to be updated. For example, when a change in billing address or the expiration date of a card has to be updated in the system, this API will help to modify the card details without having to re-enter other details. It helps the customer details in Chargebee to be in sync with the payment gateway. This way, the merchant does not have to enter the card details in the payment gateway. 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.

Sample Request
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm_3Nl8E2TQRL6rFd6/update_card \
     -u {site_api_key}: \
     -d card[first_name]="John" \
     -d card[last_name]="Doe" \
     -d card[expiry_month]="05" \
     -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_3Nl8E2TQRL6rFd6/update_card \
     -u {site_api_key}: \
     -d card[first_name]="John" \
     -d card[last_name]="Doe" \
     -d card[expiry_month]="05" \
     -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 ]

{ "payment_source": { "id": "pm_3Nl8E2TQRL6rFd6", "object": "payment_source", "customer_id": "8avVGOkx8U1MX", "type": "card", "reference_id": "tok_3Nl8E2TQRL6rFI5", "status": "valid", "gateway": "chargebee", "gateway_account_id": "gw_3Nl8E2TQRL6pXo2", "card": { "first_name": "John", "last_name": "Doe", "iin": "411111", "last4": "1111", "funding_type": "credit", "expiry_month": 5, "expiry_year": 2022, "billing_addr1": "#678 Mission Street", "billing_city": "New York City", "billing_state_code": "NY", "billing_state": "New York", "billing_country": "US", "billing_zip": "10002", "masked_number": "************1111", "object": "card", "brand": "visa" } }, "customer": { "id": "8avVGOkx8U1MX", "first_name": "Benjamin", "last_name": "Ross", "email": "Benjamin@test.com", "auto_collection": "on", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1412101809, "taxability": "taxable", "updated_at": 1501853878, "resource_version": 1501853878000, "deleted": false, "object": "customer", "card_status": "valid", "contacts": [ { "id": "d334f4g45", "first_name": "aasca", "last_name": "asas", "email": "sss@wss.asc", "label": "ascasc", "enabled": true, "send_account_email": true, "send_billing_email": false, "object": "contact" }, {..} ], "primary_payment_source_id": "pm_3Nl8E2TQRL6rFd6", "payment_method": { "object": "payment_method", "type": "card", "reference_id": "tok_3Nl8E2TQRL6rFI5", "gateway": "chargebee", "gateway_account_id": "gw_3Nl8E2TQRL6pXo2", "status": "valid" }, "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "unbilled_charges": 0, "preferred_currency_code": "USD" } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/update_card
gateway_meta_data
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.
optional, string, max chars=65k
card
Parameters for card
pass parameters as card[<param name>]
card[first_name]
Cardholder's first name.
optional, string, max chars=50
card[last_name]
Cardholder's last name.
optional, string, max chars=50
card[expiry_month]
Card expiry month.
optional, integer, min=1, max=12
card[expiry_year]
Card expiry year.
optional, integer
card[billing_addr1]
Address line 1, as available in card billing address.
optional, string, max chars=150
card[billing_addr2]
Address line 2, as available in card billing address.
optional, string, max chars=150
card[billing_city]
City, as available in card billing address.
optional, string, max chars=50
card[billing_zip]
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
card[billing_state_code]
The ISO 3166-2 state/province code. Supported only for countries US,Canada and India.
optional, string, max chars=50
card[billing_state]
The state/province name.
optional, string, max chars=50
card[billing_country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
Resource object representing customer.
always returned
Resource object representing payment_source.
always returned
Retrieves the payment source identified by the unique identifier.
Sample Request
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm_3Nl8E2TQRL6rFd6 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm_3Nl8E2TQRL6rFd6 \
     -u {site_api_key}:

Sample Response [ JSON ]

{"payment_source": { "id": "pm_3Nl8E2TQRL6rFd6", "object": "payment_source", "customer_id": "8avVGOkx8U1MX", "type": "card", "reference_id": "tok_3Nl8E2TQRL6rFI5", "status": "valid", "gateway": "chargebee", "gateway_account_id": "gw_3Nl8E2TQRL6pXo2", "card": { "first_name": "John", "last_name": "Doe", "iin": "411111", "last4": "1111", "funding_type": "credit", "expiry_month": 5, "expiry_year": 2022, "billing_addr1": "#678 Mission Street", "billing_city": "New York City", "billing_state_code": "NY", "billing_state": "New York", "billing_country": "US", "billing_zip": "10002", "masked_number": "************1111", "object": "card", "brand": "visa" } }}

URL Format GET

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}
Resource object representing payment_source.
always returned
Lists all the payment sources.
Sample Request
curl  https://{site}.chargebee.com/api/v2/payment_sources \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

Sample Response [ JSON ]

{ "list": [ {"payment_source": { "id": "pm_XpbKGJ9QRL7ouSGg", "object": "payment_source", "customer_id": "8avVGOkx8U1MX", "type": "card", "reference_id": "cus_B9OnlNTIA8PZL8/card_q2K6hBd89SjkMh", "status": "valid", "gateway": "stripe", "gateway_account_id": "gw_3Nl8E2TQRL73vX7A", "issuing_country": "CA", "card": { "first_name": "Richard", "last_name": "Fox", "iin": "401288", "last4": "1881", "funding_type": "credit", "expiry_month": 10, "expiry_year": 2022, "masked_number": "************1881", "object": "card", "brand": "visa" } }}, {..} ], "next_offset": "[\"1501853878000\",\"132000000173\"]" }

URL Format GET

https://{site}.chargebee.com/api/v2/payment_sources
limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
Filter Params
For operator usages, see the Pagination and Filtering section.
customer_id[<operator>]
To filter based on Customer Id.
Supported operators : is, is_not, starts_with, in, not_in

Example customer_id[is_not] = "3bdjnDnsdQn"
optional, string filter
type[<operator>]
To filter based on PaymentSource Type. Possible values are : card, paypal_express_checkout, amazon_payments, direct_debit, generic, alipay, unionpay.
Supported operators : is, is_not, in, not_in

Example type[is] = "card"
optional, enumerated string filter
status[<operator>]
To filter based on PaymentSource Status. Possible values are : valid, expiring, expired, invalid, pending_verification.
Supported operators : is, is_not, in, not_in

Example status[is_not] = "valid"
optional, enumerated string filter
Resource object representing payment_source.
always returned
next_offset
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”.
optional, string, max chars=1000

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_3Nl8E2TQRL6rFd6/switch_gateway_account \
     -u {site_api_key}: \
     -d gateway_account_id="gw_3Nl9BNeQ7438Ks1"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm_3Nl8E2TQRL6rFd6/switch_gateway_account \
     -u {site_api_key}: \
     -d gateway_account_id="gw_3Nl9BNeQ7438Ks1"

Sample Response [ JSON ]

{ "customer": { "allow_direct_debit": false, "auto_collection": "on", "card_status": "valid", "created_at": 1501853723, "deleted": false, "email": "johnwilliams@gmail.com", "excess_payments": 0, "first_name": "John", "id": "XpbKGJ9QRL7AZ5Cx", "last_name": "Williams", "net_term_days": 0, "object": "customer", "payment_method": { "gateway": "pin", "gateway_account_id": "gw_3Nl8E2TQRL7AN57E", "object": "payment_method", "reference_id": "NUmOf9g5aCrB8lh39vq8PwgpPBb", "status": "valid", "type": "card" }, "preferred_currency_code": "USD", "primary_payment_source_id": "pm_XpbKGJ9QRL7B6xCy", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1501853725000, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1501853725 }, "payment_source": { "card": { "brand": "visa", "expiry_month": 12, "expiry_year": 2018, "funding_type": "not_known", "iin": "411111", "last4": "1111", "masked_number": "************1111", "object": "card" }, "customer_id": "XpbKGJ9QRL7AZ5Cx", "gateway": "pin", "gateway_account_id": "gw_3Nl8E2TQRL7AN57E", "id": "pm_XpbKGJ9QRL7B6xCy", "object": "payment_source", "reference_id": "NUmOf9g5aCrB8lh39vq8PwgpPBb", "status": "valid", "type": "card" } }

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/switch_gateway_account
gateway_account_id
The gateway account you want to switch to.
required, string, max chars=50
Resource object representing customer.
always returned
Resource object representing payment_source.
always returned

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_3Nl8E2TQRL6rFd6/export_payment_source \
     -u {site_api_key}: \
     -d gateway_account_id="gw_3Nl9BNeQ7438Ks1"
copy
curl  https://{site}.chargebee.com/api/v2/payment_sources/pm_3Nl8E2TQRL6rFd6/export_payment_source \
     -u {site_api_key}: \
     -d gateway_account_id="gw_3Nl9BNeQ7438Ks1"

Sample Response [ JSON ]

{"third_party_payment_method": { "gateway": "stripe", "gateway_account_id": "gw_3Nl8E2TQRL73vX7A", "type": "card", "reference_id": "cus_B9OlI1FiXDBY3z/card_GrlrmSDNsJW5Up", "object": "third_party_payment_method" }}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/export_payment_source
gateway_account_id
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 payment source. Upon successful deletion of payment source,

  • If the payment source is Primary, then the Backup if present for the customer, will become Primary payment source.
  • If the payment source is Primary and Backup is not present, then auto collection attribute for the customer will be set to off and card_deleted and payment_source_deleted event will be triggered.
  • Dunning starts for subscriptions that are attached to this payment source if auto collection is set to ‘On’ and Customer default is not present.

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

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

Sample Response [ JSON ]

{"customer": { "id": "8avVGOkx8U1MX", "first_name": "Benjamin", "last_name": "Ross", "email": "Benjamin@test.com", "auto_collection": "on", "net_term_days": 0, "allow_direct_debit": false, "created_at": 1412101809, "taxability": "taxable", "updated_at": 1501853878, "resource_version": 1501853878000, "deleted": false, "object": "customer", "card_status": "valid", "contacts": [ { "id": "d334f4g45", "first_name": "aasca", "last_name": "asas", "email": "sss@wss.asc", "label": "ascasc", "enabled": true, "send_account_email": true, "send_billing_email": false, "object": "contact" }, {..} ], "primary_payment_source_id": "pm_3Nl8E2TQRL6rFd6", "payment_method": { "object": "payment_method", "type": "card", "reference_id": "tok_3Nl8E2TQRL6rFI5", "gateway": "chargebee", "gateway_account_id": "gw_3Nl8E2TQRL6pXo2", "status": "valid" }, "promotional_credits": 0, "refundable_credits": 0, "excess_payments": 0, "unbilled_charges": 0, "preferred_currency_code": "USD" }}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_sources/{cust_payment_source_id}/delete
Resource object representing customer.
always returned