Settings
API Version
Product Catalog
Library

Tokens

Tokenization hides sensitive payment information into a unique token for a secure transaction. The token does not expose any actual payment details.

Sample token [ JSON ]

API Index URL GET

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

Model Class

 

      Token attributes
      
 
id
 

      string, max chars=40
 Identifier of the Chargebee Token 
 
 
gateway
 

      enumerated string
 Name of the gateway this token is stored in. 
 
Possible values are
 
 
chargebeeChargebee test gateway.chargebee_paymentsChargebee Payments gatewayadyenAdyen is a payment gateway.stripeStripe is a payment gateway.
 
 Show all values[+]
 
gateway_account_id
 

      string, max chars=50
 The gateway account in which this token is stored. 
 
 
payment_method_type
 

      enumerated string
 Type of payment method of the token. 
 
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.
 
 Show all values[+]
 
status
 

      enumerated string, default=new
 Status of the token 
 
Possible values are
 
 
newnewexpiredexpiredconsumedThe token is already used
 
 Show all values[+]
 
id_at_vault
 

      string, max chars=65k
 The id with which this token is referred in gateway 
 
 
vault
 

      enumerated string
 Name of the gateway/vault provider where the payment method is tokenized 
 
Possible values are
 
 
spreedlyspreedlygatewaygateway
 
 Show all values[+]
 
ip_address
 

      optional, string, max chars=50
 The IP address from where the token is created. Used primarily for EU VAT validation. 
 
 
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 token resource was last updated. 
 
 
created_at
 

      timestamp(UTC) in seconds
 Timestamp indicating when this token resource is created. 
 
 
expired_at
 

      optional, timestamp(UTC) in seconds
 Timestamp indicating when this token is expired 
 
 
 
Event types
 

      This is a list of the event types we currently support. We will continue
      to add more events moving forward. All events follow a uniform pattern -
      <resource>_<event_name>. The resources that will be
      present in the event content are provided beneath each event type's
      description.
    
 
Note: If consolidated invoicing is enabled, the
      attributes invoice.subscription_id and
      credit_note.subscription_id should not be used
      (as it will not be present if the invoice / credit note has lines from
      multiple subscriptions). Instead to know the related subscriptions,
      their line_items' subscription_id attribute should be referred.
    
 
 
id id
 

          string, max chars=40
 Identifier of the Chargebee Token 
 
gateway gateway
 

          enumerated string
 Name of the gateway this token is stored in. 
 
Possible values are
 
 
chargebeeChargebee test gateway.chargebee_paymentsChargebee Payments gatewayadyenAdyen is a payment gateway.stripeStripe is a payment gateway.
 
 Show all values[+]
gateway_account_id gateway_account_id
 

          string, max chars=50
 The gateway account in which this token is stored. 
 
payment_method_type payment_method_type
 

          enumerated string
 Type of payment method of the token. 
 
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.
 
 Show all values[+]
status status
 

          enumerated string, default=new
 Status of the token 
 
Possible values are
 
 
newnewexpiredexpiredconsumedThe token is already used
 
 Show all values[+]
id_at_vault id_at_vault
 

          string, max chars=65k
 The id with which this token is referred in gateway 
 
vault vault
 

          enumerated string
 Name of the gateway/vault provider where the payment method is tokenized 
 
Possible values are
 
 
spreedlyspreedlygatewaygateway
 
 Show all values[+]
ip_address ip_address
 

          optional, string, max chars=50
 The IP address from where the token is created. Used primarily for EU VAT validation. 
 
resource_version 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 updated_at
 

          optional, timestamp(UTC) in seconds
 Timestamp indicating when this token resource was last updated. 
 
created_at created_at
 

          timestamp(UTC) in seconds
 Timestamp indicating when this token resource is created. 
 
expired_at expired_at
 

          optional, timestamp(UTC) in seconds
 Timestamp indicating when this token is expired 
 
 
 
Consent Fields for Token
 
 
Custom Fields for Token
 
  

      Create a card payment method token
      
 
Idempotency Supported
 
 
Generate a token that holds card related information.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
 

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/tokens/create_for_card
    
 
Method
 
 
Input Parameters
 
   
 
 
 
 
card[gateway_account_id]
 
optional, string, max chars=50 
  
card[first_name]
 
optional, string, max chars=50 
  
card[last_name]
 
optional, string, max chars=50 
  
card[number]
 
required, string, max chars=1500 
  
card[expiry_month]
 
required, integer, min=1, max=12 
  
card[expiry_year]
 
required, integer 
  
card[cvv]
 
optional, string, max chars=520 
  
card[preferred_scheme]
 
optional, enumerated string 
  
Possible values are
 
 
cartes_bancairesA Cartes Bancaires card scheme.mastercardA MasterCard scheme.visaA Visa card scheme.
 
 Show all values[+]
card[billing_addr1]
 
optional, string, max chars=150 
  
card[billing_addr2]
 
optional, string, max chars=150 
  
card[billing_city]
 
optional, string, max chars=50 
  
card[billing_state_code]
 
optional, string, max chars=50 
  
card[billing_state]
 
optional, string, max chars=50 
  
card[billing_zip]
 
optional, string, max chars=20 
  
card[billing_country]
 
optional, string, max chars=50 
  
card[additional_information]
 
optional, jsonobject 
  
card[card_type]
 
optional, enumerated string 
  
Possible values are
 
 
visaA Visa card.mastercardA MasterCard.american_expressAn American Express card.discoverA Discover card.
 
 Show all values[+]
   
 
Returns
 
token  token
 

      always returned 
 Resource object representing token
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/tokens/123x
    

      Create using vault temp token
      
 
Idempotency Supported
 
 
Generate a token using the one time token created by payment gateways for any specific payment method.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
 

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/tokens/create_using_temp_token
    
 
Method
 
 
Input Parameters
 
  
 
gateway_account_id[]
 

      optional, string, max chars=50 
 The gateway account to which the token is associated. 
 
payment_method_type[]
 

      required, enumerated string 
 Type of payment method of the token. 
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.
 
 Show all values[+]
 
id_at_vault[]
 

      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. 
 
gw_obj_type[]
 

      optional, string, max chars=255 
 Represents what type of object at gateway eg. "token" in case Stripe token and   "source" in case of Stripe Source. 
 
currency_code[]
 

      optional, string, max chars=3 
 Used to derieve Bank Account Scheme by default will take site default currency. 
 
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 
        •  
       
      •  
      
. 
 
 
 
 
 
token_additional_detail[first_name]
 
optional, string, max chars=50 
  
token_additional_detail[last_name]
 
optional, string, max chars=50 
  
token_additional_detail[expiry_month]
 
optional, integer, min=1, max=12 
  
token_additional_detail[expiry_year]
 
optional, integer 
  
 
 
token_billing_address[line1]
 
optional, string, max chars=150 
  
token_billing_address[line2]
 
optional, string, max chars=150 
  
token_billing_address[city]
 
optional, string, max chars=50 
  
token_billing_address[state]
 
optional, string, max chars=50 
  
token_billing_address[state_code]
 
optional, string, max chars=50 
  
token_billing_address[country_code]
 
optional, string, max chars=50 
  
token_billing_address[zip]
 
optional, string, max chars=20 
  
   
 
Returns
 
token  token
 

      always returned 
 Resource object representing token
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/tokens/123x
    

      Retrieve a token
      
  
 
Retrieve a token using token ID.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
 

      copy
      
Click to Copy
 
 

    Sample Response [ JSON ]
 
Show more...
 
{}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/tokens/{cb-token-id}
    
 
Method
 
  
   
 
    
 
Returns
 
token  token
 

      always returned 
 Resource object representing token
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/tokens/123x