ChargebeeAPI

Create using permanent token

Idempotency Supported
Try in API Explorer

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

  • The permanent token must belong to a gateway account configured in Chargebee.
  • The token should be a permanent/vault token, not a single-use token.
  • When multiple gateway accounts are configured in Chargebee Billing, you must pass the gateway_account_id parameter if:
    • Smart Routing is not configured for the payment method.
    • Smart Routing is configured for the payment method, but the selected gateway account does not match the provided token.

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.

Sample Request

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 Enum Values
card

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

paypal_express_checkout

Payments made via PayPal Express Checkout.

amazon_payments

Payments made via Amazon Payments.

direct_debit

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

generic

Payments made via Generic Payment Method.

gateway_account_id
optional, string, max chars=50

The gateway account to which the payment source is associated.

reference_id
optional, 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 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.

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.

payment_method_token
optional, string, max chars=100

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
optional, string, max chars=100

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.

network_transaction_id
optional, string, max chars=100

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.

mandate_id
optional, string, max chars=100

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
optional, boolean, default=false

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.

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.

  • 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 .
card
optional, string

Parameters of tokenized card details

billing_address
optional, string

Parameters for billing_address

Returns

customerCustomer object

Resource object representing customer

payment_sourcePayment source object

Resource object representing payment_source