Tokens

API Version

Product Catalog

Library

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 ]

{}

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

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

status

enumerated string, default=new

Status of the token

Possible values are

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

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

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

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

status

enumerated string, default=new

Status of the token

Possible values are

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

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

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

Try in API Explorer

Generate a token that holds card related information.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{}

URL Format POST

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

card

Parameters for card
pass parameters as card[<param name>]

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

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

token

always returned
Resource object representing token

Try in API Explorer

Generate a token using the one time token created by payment gateways for any specific payment method.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{}

URL Format POST

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

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

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.
  - 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 .

token_additional_detail

Parameters for token_additional_detail
pass parameters as token_additional_detail[<param name>]

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

Parameters for token_billing_address
pass parameters as token_billing_address[<param name>]

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

token

always returned
Resource object representing token

Try in API Explorer

Retrieve a token using token ID.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{}

URL Format GET

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

token

always returned
Resource object representing token

Sample token [ JSON ]

API Index URL

Model Class

Token attributes

Consent Fields for Token

Custom Fields for Token

Create a card payment method token ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Create using vault temp token ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a token ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL