Pricing Templates
Log in Sign up
Integrations / Chargebee Product / ...

POST /payment_sources/create_using_permanent_token

Creates a payment source for a customer using a permanent token obtained from the payment gateway.

Use this API to add a payment method that has already been vaulted in your gateway account. The permanent token enables Chargebee to securely link the payment method to the customer. This enables payment collection for future charges (both recurring and one-time) without requiring the customer to re-enter their payment details.

Prerequisites & Constraints

Impacts

Customer

Pass the replace_primary_payment_source parameter as true to update the customer's primary_payment_source_id. Otherwise, the existing primary payment source will remain unchanged.

Servers

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_token String No

An identifier provided by the gateway or card vault for the specific payment method resource.

Note: payment_method_token is an alternative for reference_id and cannot be used with reference_id.
customer_profile_token String No

A unique identifier associated with a customer`s profile within a payment gateway.

Note: customer_profile_token is an alternative for reference_id and cannot be used with reference_id.
card Object No

Parameters of tokenized card details
card.iin String No

The Issuer Identification Number, i.e. the first six digits of the card number
card.funding_type String No

Card Funding type * not_known -

An unknown card. * prepaid -

A prepaid card. * debit -

A debit card. * credit -

A credit card. * not_applicable -

Used for ACH. Not applicable for cards

Valid values:

  • "credit"
  • "not_known"
  • "prepaid"
  • "debit"
card.brand String No

Card brand * jcb -

A JCB card. * pay_by_bank -

Pay By Bank * cabal -

A Cabal card. * hipercard -

An Hipercard. * other -

Card belonging to types other than those listed above. * trustly -

Trustly * electronic_payment_standard -

Electronic Payment Standard * cartes_bancaires -

A Cartes Bancaires card. * american_express -

An American Express card. * visa -

A Visa card. * cencosud -

A Cencosud card. * bancontact -

A Bancontact card. * cmr_falabella -

A CMR Falabella card. * not_applicable -

Used for offline entries in transactions. Not applicable for cards * rupay -

A Rupay card. * maestro -

A Maestro card. * carnet -

A Carnet card. * nativa -

A Nativa card. * discover -

A Discover card. * argencard -

An Argencard. * dankort -

A Dankort card. * tarjeta_naranja -

A Tarjeta Naranja card. * kbc_payment_button -

KBC Payment Button * elo -

A Elo card. * diners_club -

A Diner's Club card. * mastercard -

A MasterCard.

Valid values:

  • "bancontact"
  • "nativa"
  • "maestro"
  • "tarjeta_naranja"
  • "argencard"
  • "other"
  • "carnet"
  • "cencosud"
  • "visa"
  • "jcb"
  • "cartes_bancaires"
  • "discover"
  • "diners_club"
  • "hipercard"
  • "elo"
  • "dankort"
  • "cmr_falabella"
  • "cabal"
  • "mastercard"
  • "rupay"
  • "american_express"
card.expiry_year Integer No

Card expiry year.
card.last4 String No

Last four digits of the card number
card.expiry_month Integer No

Card expiry month.
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 .
replace_primary_payment_source Boolean No

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.

Default value: false
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 a card, this will be the identifier provided by the gateway or card vault for the specific payment method resource.

Note:

  • This is not the one-time temporary token provided by gateways like Stripe.

  • reference_id is an alternative for payment_method_token, customer_profile_token, network_transaction_id, or mandate_id.

  • payment_method_token, customer_profile_token, network_transaction_id, or mandate_id cannot be used with reference_id.

  • reference_id is a combination of multiple tokens available at the gateway. Learn more about the combination of each gateway from this document.
customer_id String Yes

Identifier of the customer with whom this payment source is associated.
gateway_account_id String No

The gateway account to which the payment source is associated.
type String Yes

The type of payment method. For more details refer Update payment method for a customer API under Customer resource. * direct_debit -

Represents bank account for which the direct debit or ACH agreement/mandate is created. * unionpay -

Payments made via UnionPay. * faster_payments -

Payments made via Faster Payments * google_pay -

Payments made via Google Pay. * sepa_instant_transfer -

Payments made via Sepa Instant Transfer * dotpay -

Payments made via Dotpay. * pay_to -

Payments made via PayTo * generic -

Payments made via Generic Payment Method. * giropay -

Payments made via giropay. * klarna_pay_now -

Payments made via Klarna Pay Now * automated_bank_transfer -

Represents virtual bank account using which the payment will be done. * stablecoin -

Payments made via Stablecoin * paypal_express_checkout -

Payments made via PayPal Express Checkout. * alipay -

Payments made via Alipay.
This payment source is deprecated. * venmo -

Payments made via Venmo * sofort -

Payments made via Sofort. * pix -

Payments made via Pix * wechat_pay -

Payments made via WeChat Pay.
This payment source is deprecated. * ideal -

Payments made via iDEAL. * trustly -

Trustly * netbanking_emandates -

Netbanking (eMandates) Payments. * upi -

UPI Payments. * bancontact -

Payments made via Bancontact Card. * kbc_payment_button -

KBC Payment Button * card -

Card based payment including credit cards and debit cards. Details about the card can be obtained from the card resource. * payconiq_by_bancontact -

Payments made via Payconiq by Bancontact * amazon_payments -

Payments made via Amazon Payments. * pay_by_bank -

Pay By Bank * apple_pay -

Payments made via Apple Pay. * electronic_payment_standard -

Electronic Payment Standard

Valid values:

  • "pay_by_bank"
  • "upi"
  • "online_banking_poland"
  • "cash_app_pay"
  • "unionpay"
  • "direct_debit"
  • "netbanking_emandates"
  • "giropay"
  • "electronic_payment_standard"
  • "venmo"
  • "payconiq_by_bancontact"
  • "card"
  • "klarna_pay_now"
  • "pix"
  • "faster_payments"
  • "sepa_instant_transfer"
  • "alipay"
  • "naver_pay"
  • "revolut_pay"
  • "bancontact"
  • "amazon_payments"
  • "trustly"
  • "sofort"
  • "automated_bank_transfer"
  • "stablecoin"
  • "kakao_pay"
  • "paypal_express_checkout"
  • "apple_pay"
  • "pay_to"
  • "generic"
  • "kbc_payment_button"
  • "dotpay"
  • "google_pay"
  • "wechat_pay"
  • "ideal"
issuing_country String No

2-letter (alpha2) ISO country code. Indicates your customer's payment method country of issuance. Applicable for PayPal via Braintree.
mandate_id String No

An identifier of mandates which is an authorization given by the payer (usually a customer or account holder) to allow a third party such as a merchant or service provider to initiate payments from their account.

Note: mandate_id is an alternative for reference_id and cannot be used with reference_id.
skip_retrieval Boolean No

By default, the value is false and payment method details will be retrieved from the selected payment gateway using reference_id or payment_method_token / customer_profile_token / network_transaction_id / mandate_id. Learn more about the multiple token combinations of each gateway from this document. Enter the value as true for the payment gateways that do not allow to retrieve the payment method details. Once passed, it will create payment method at Chargebee with the provided attributes in payment_method_token, customer_profile_token, network_transaction_id, mandate_id, card, and billing_address.

Note: Currently, the skip_retrieval value as true is only supported for the Vantiv payment gateway.

Default value: false
network_transaction_id String No

An identifier of the payment or authorization transaction at the gateway initiated using this payment method.

Note: network_transaction_id is an alternative for reference_id and cannot be used with reference_id.
billing_address Object No

Parameters for billing_address
billing_address.line2 String No

Address line 2
billing_address.line1 String No

Address line 1
billing_address.email String No

The email address.
billing_address.last_name String No

The last name of the billing contact.
billing_address.line3 String No

Address line 3
billing_address.state_code String No

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_address.zip String No

Zip or postal code. The number of characters is validated according to the rules specified here .
billing_address.first_name String No

The first name of the billing contact.
billing_address.state String No

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
billing_address.country String No

The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code .

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_address.city String No

The name of the city.

How to start integrating

  1. Add HTTP Task to your workflow definition.
  2. 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.
  3. Click Test request to test run your request to the API and see the API's response.
All third party trademarks (including logos and icons) are the property of their respective owners, which do not sponsor, authorize, or endorse this website.
Pricing Templates Integrations Blog Contact Us Help
© 2026 SimWorkflow
Terms of Service Privacy Policy