POST /customers/{customer-id}/update_payment_method

Payment Sources comes with additional options and improvements to the Card APIs. For this operation, use the Create using temporary token API or Create using permanent token API under Payment Sources to update payment method for the customer.

Updates payment method details for a customer.

Note: If you wish to pass the card number, CVV, or the single-use card tokens provided by gateways like Stripe, then use the Update card for a customer API under Cards resource. 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 method using PayPal Express Checkout, you will be provided with the Billing Agreement ID by PayPal. You can update the payment method 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 method, you will be provided with the Billing Agreement ID by Amazon. You can update the payment method 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 update the reference id provided by them in Chargebee. To use this API, pass

type as card.
gateway with the gateway 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 combination of Stripe Customer ID and Stripe Card ID separated by 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 case of Braintree, the reference_id consists of combination of Braintree Customer ID and Braintree Payment Method Token separated by 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 update the reference id provided by them in Chargebee. To use this API, pass

type as direct_debit.
gateway with the gateway where the bank account details are stored (e.g. authorize_net). If the gateway 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.
tmp_token with the single use token provided by the gateway ( Should be passed only if reference_id is not passed ).

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

Stripe: In case of Stripe, the reference_id consists of combination of Stripe Customer ID and Stripe Bank Account ID separated by 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 combination of Authorize.Net's Customer Profile ID and Payment Profile ID separated by 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.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`customer-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`payment_method`	Object	No	Parameters for payment_method
`payment_method.gateway_account_id`	String	No	The gateway account in which this payment source is stored.
`payment_method.type`	String	Yes	The type of payment method. For more details refer Update payment method for a customer API under Customer resource. * card - Card based payment including credit cards and debit cards. Details about the card can be obtained from the card resource. * sepa_instant_transfer - Payments made via Sepa Instant Transfer * ideal - Payments made via iDEAL. * direct_debit - Represents bank account for which the direct debit or ACH agreement/mandate is created. * sofort - Payments made via Sofort. * alipay - Payments made via Alipay. This payment source is deprecated. * generic - Payments made via Generic Payment Method. * klarna_pay_now - Payments made via Klarna Pay Now * netbanking_emandates - Netbanking (eMandates) Payments. * apple_pay - Payments made via Apple Pay. * online_banking_poland - Payments made via Online Banking Poland * pay_to - Payments made via PayTo * unionpay - Payments made via UnionPay. * faster_payments - Payments made via Faster Payments * bancontact - Payments made via Bancontact Card. * dotpay - Payments made via Dotpay. * venmo - Payments made via Venmo * automated_bank_transfer - Represents virtual bank account using which the payment will be done. * giropay - Payments made via giropay. * upi - UPI Payments. * google_pay - Payments made via Google Pay. * wechat_pay - Payments made via WeChat Pay. This payment source is deprecated. * amazon_payments - Payments made via Amazon Payments. * payconiq_by_bancontact - Payments made via Payconiq by Bancontact * paypal_express_checkout - Payments made via PayPal Express Checkout. Valid values: `"bancontact"` `"amazon_payments"` `"upi"` `"online_banking_poland"` `"unionpay"` `"direct_debit"` `"sofort"` `"automated_bank_transfer"` `"netbanking_emandates"` `"giropay"` `"paypal_express_checkout"` `"pay_to"` `"venmo"` `"generic"` `"payconiq_by_bancontact"` `"card"` `"klarna_pay_now"` `"dotpay"` `"faster_payments"` `"sepa_instant_transfer"` `"google_pay"` `"alipay"` `"wechat_pay"` `"ideal"`
`payment_method.tmp_token`	String	No	Single-use toke created by payment gateways. In Stripe, a single-use token is created for direct debit. In Braintree, a nonce is created for PayPal.
`payment_method.issuing_country`	String	No	ISO 3166 alpha-2 country code. Note: If you enter an invalid country code, the system will return an error. If you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, then `XI` (the code for United Kingdom – Northern Ireland) is available as an option.
`payment_method.additional_information`	Object	No	`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. `fraud_session_id`: Your BlueSnap fraud session ID required to perform anti-fraud validation. `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. `bank_of_america`: While passing raw card details to Bank of America, your 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. `ecentric`: This parameter is used to verify and process payment method details in Ecentric. If the `merchant_id` parameter is included, Chargebee will vault it / perform a lookup and verification against this `merchant_id`, overriding the one configured in Chargebee. If tokens and processing occur in the same Merchant GUID, you can just skip this part. `merchant_id`: Merchant GUID where the card is vaulted or need to be vaulted. `ebanx`: While passing raw card details to EBANX, the user's `document` is required for some countries and `device_session_id` can be added to perform additional validation and avoid fraudulent transactions. `payer`: User related information. `document`: Document is the user's identification number based on their country. `fraud`: Fraud identification related information. `device_session_id`: Session ID associated with the user's device
`payment_method.reference_id`	String	No	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. For more details refer Update payment method for a customer API under Customer resource.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.