API Overview

• Adding new API resources.
• Adding new attributes to existing API responses.
• Changing the order of attributes in existing API responses.
• Adding new API methods for a resource.
• Adding new 'optional' input params to existing API methods.
• Adding new attributes to existing API responses.
• Making an input param 'required' in API methods (very rare).
• Adding new event types.

# creates a subscription with customer information and billing details.
curl  https://{site}.chargebee.com/api/v1/subscriptions \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[email]="john@user.com" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d customer[auto_collection]="off"

# creates a subscription with customer information and billing details.
curl  https://{site}.chargebee.com/api/v1/subscriptions \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[email]="john@user.com" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d customer[auto_collection]="off"

Sample Response [ JSON ]

Some of the resources have a corresponding details page in the Chargebee's admin console. In some cases you might want to construct the admin console url for easy access from your app (or from exported xls sheets). As the admin console urls are based on internal ids you need to construct the url in the below given format.

Here is an example of a constructed url for a subscription with id 123xyz

• Accessing the constructed url in a browser will redirect it to the details page.
• The login page will be shown if the user has not yet logged-in into Chargebee's admin console.
• Not all resources will have the corresponding details page. To know if it is supported, please look at the cURL documentation under the retrieve operation for that resource.
• Do not store the redirected internal id based url as it may change.

Chargebee supports billing in 100+ currencies.

Take a look at the list of supported currencies here.

Handling Currency Units

While specifying amount in any currency, you need to provide the amount in the smallest unit of that currency. For example, to specify an amount of $1.50, you would set amount=150 (i.e. 150 cents).

For zero decimal currencies (currencies that do not have decimal units), however, you need to provide the amount in the regular denomination. For example, to specify an amount of ¥15, you would set amount=15 (i.e. 15 yens).

Chargebee currently supports below zero-decimal currencies:

• KRW - South Korean Won
• JPY - Japanese Yen
• XAF - Central African CFA Franc
• XOF - West African CFA Franc

Multicurrency Support

With our Multicurrency support, you will be able to process transactions in additional currencies apart from your site's Base currency.

Once Multicurrency support is enabled, the API methods listed below will throw an error as currency_code is required for these methods to work and the same is not supported in the V1 version. So upgrade to our latest version (V2) to be able to pass currency_code input parameter to these methods in Multicurrency mode.

• Customer related methods
• Add account credits to a customer
• Deduct account credits from a customer
• Set account credits for a customer
• Invoice related methods
• Create an invoice
• Create invoice for charge
• Product Configuration related methods
• Create a plan
• Update a plan
• Create an addon
• Update an addon
• Create a coupon

Chargebee supports configuring multiple gateway accounts for a gateway type (eg: you can configure multiple Authorize.net accounts to process multiple currencies).

If you have multiple gateway accounts for a gateway type, the API methods listed below will throw an error as gateway_account_id is required for these methods to work and the same is not supported in the V1 version. So upgrade to our latest version (V2) to be able to pass gateway_account_id input parameter to these methods.

• Customer related methods
• Create a customer
• Update payment method for a customer
• Card related methods
• Update card for a customer
• Switch gateway
• Subscription related methods
• Create a subscription
• Update a subscription
• Hosted page related methods
• Checkout new subscription
• Checkout existing subscription
• Update payment method

Chargebee supports multiple payment methods/sources for a customer. So a customer can have a Card and a Paypal Account linked to them, or they can have multiple cards. Moreover, you can mark one of them as Primary and one as Backup payment source.

The purpose of a Backup payment source is that if a charge made via the Primary payment source fails, then the backup payment source will be automatically used for processing the transaction.

Updating a payment source:

1. To update the Primary payment source for a customer:
• Use any of the create payment source APIs with 'replace_primary_payment_source' set to 'true'. This will update the payment source and make it the Primary payment source for the customer.
2. To update alternate payment sources:
• Delete the payment source that you want to update
• Create a payment source for the customer using any of the create payment source APIs

An optional parameter, payment_source_id, is available in the following APIs:

• Subscription APIs

If you want to attach a particular payment source to a specific subscription, then pass the parameter in the following APIs:

• Create subscription for customer
• Import subscription for customer
• Override Billing Profile
• Invoice APIs

Pass this parameter in the following APIs to collect the payment using a specific payment source:

• Create an invoice
• Create invoice for charge
• Create invoice for addon
• Collect payment for an invoice

Chargebee supports 3DS payments to comply with Strong Customer Authentication (SCA) directed by the regulations of Revised Payment Service Directive (PSD2). Take a look at our guide on PSD2 and Strong Customer Authentication to understand more about the regulations and impacts.

To obey SCA, the 3DS flow must be implemented during payment actions, whenever the Issuing Bank wants authentication. The customer must compulsorily go through 3DS verification whenever a new card is added to the vault. Further, Merchant Initiated Transactions, which are done in the backend using stored cards are mostly exempted from the 3DS flow. 3DS can be implemented in the gateway's payment flow and the 3DS-verified token generated (reference for the 3DS payment) can be passed to Chargebee via API after the customer completes 3DS verification successfully.

3DS-SUPPORTED MODES OF API INTEGRATION IN CHARGEBEE

Chargebee supports two modes of API integration for handling 3DS transactions,

1. Using Chargebee.js to complete the 3DS flow

You can easily integrate Chargebee.js in your checkout using our JS implementation guide. After successful integration, Chargebee does most of the heavy-lifting involved in a 3DS transaction.

Adyen.js can be made 3DS viable using Chargebee.js' 3DS helper module.

For more information, take a look at our Chargebee.js documentation.

2. Using Gateway APIs directly to complete the 3DS flow

You can integrate gateway's JS in your checkout page to implement 3DS flow for transactions, by following the instructions provided by gateway. For new and stored cards, with the help of gateway's JS and its server APIs you can complete the 3DS flow.

If you have a gateway JS or direct API integration with Chargebee, continue reading to understand 3DS implementation for them.

Implementation Guide

Following steps explain the implementation instructions to complete the 3DS flow whenever a customer adds a card.

1. Integrate your payment pages and update payment method page with the gateways' supported 3DS flow. Please refer the gateways' implementation
2. You have to pass the authorization amount to the gateway's implementation. Use our Estimate APIs to estimate the payment amount for the transaction. The estimate can be generated for create subscription or update subscription operations. Please ensure to consider taxes, existing balances etc. while deriving the estimated amount.
3. 3DS flow for minimum chargeable amount can be created without generating an invoice for operations such as update the payment method, downgrade etc. Refer gateways' document to find the minimum chargeable amount for each currency.
4. Initialize the estimated amount in the gateway's JS before displaying the 3DS verification window.
5. Ensure the payment (if any) during 3DS verification flow is authorized without capturing. Chargebee will capture/release the authorized amount after storing the card. The authorized amount will be automatically released by the gateway if any error occurs while processing the card.
6. After the customer completes the 3DS verification successfully, the gateway JS will return an identifier for the payment and card for 3DS flow.
7. Pass the 3DS flow identifier to Chargebee using payment_intent[gateway_account_id] and payment_intent[gw_token]. Chargebee accepts these parameters via supported APIs where card details can be passed.
8. On completion, the card will be stored with the Chargebee customer object. The authorized amount will be captured if an invoice and payment is being created during the operation, otherwise an authorization transaction will be created and the authorized amount will be released to the card.

3DS authorization amount and Estimate APIs

The 3DS flow can be created for either an estimated invoice amount or can be initialized with minimum chargeable amount (say for 1$, or 0$ if the gateway allows) as verification. This ensures future merchant initiated payments can mostly be collected without requiring authentication.

To avoid the discrepancy in the authorization amount and original charge, use our Estimate APIs to estimate the payment amount for the operation. Please ensure considering taxes, existing balances etc. while deriving the estimated amount.

While storing the card after 3DS verification is complete, the invoice due amount will be captured, and if there is any remaining authorized amount, it will be released to the customer's payment method. If the 3DS authorization amount is lesser than the invoice's amount due, an error will be thrown.

A minimum chargeable amount can be verified to ensure the successful future MIT payments collection. e.g. An amount of $1 for USD authorization can be created for Stripe. Refer to gateway's doc for the minimum chargeable amount for the currency. This flow can be used in case of

• On-boarding a trial customer and no invoice amount is applicable for payment collection
• Adding new payment method for the customer
• Downgrading the subscription along with a new card details collection

List of 3DS supported APIs

The parameters payment_intent[gateway_account_id], payment_intent[gw_token] and payment_intent[gw_payment_method_id] can be passed in the following 3DS supported APIs:

• Create customer
• Create subscription
• Create subscription for customer
• Update a subscription
• Update card for customer using payment intent

Merchant Initiated transactions (MIT)

MITs are mostly exempted of 3DS flow according to SCA regulation. However, there is still a minor possibility that the Issuing Bank may demand a customer to authenticate in certain scenarios. The customer would not be present online to complete 3DS flow for MITs. You can configure dunning for 3DS in Chargebee, so that respective customers are notified via email to come online and complete the authentication. Learn more about 3DS workflows here

3DS for stored card

You can choose to perform 3DS verification flow using the stored card if the customer is available online. You can make use of this flow if the payment for the card is failing due to Issuing Bank mandating the 3DS verification for MITs. Follow the steps below to implement the 3DS for an existing customer in Chargebee.

1. Get the reference id for the customer and card profile at the gateway using reference_id attribute from the Card resource using Retrieve Card for a customer API.
2. Initialize the gateway 3DS flow implementation with the customer and card reference. More on 3DS implementation in Chargebee.
3. You will need to pass the authorization amount to the gateway's implementation. Use our Estimate API to estimate the payment amount for the operation. The estimate can be generated for create subscription or update subscription operations. Please ensure considering taxes, existing balances etc. while deriving the estimated amount.
4. Pass the 3DS flow identifier to Chargebee using payment_intent[gateway_account_id] and payment_intent[gw_token]. Chargebee accepts these parameters via supported APIs where card details can be passed.
5. Since the payment method was already stored with Chargebee, no new payment method would be created.
6. On completion, the authorized amount will be captured and a payment transaction will be created for the customer.

3DS IMPLEMENTATION IN CHARGEBEE

The implementation of 3DS flow differs for each gateway. Implementation for Chargebee supported gateways are given below.

Stripe

Stripe supports SCA ready 3DS flow in Checkout using Payment intent API. Integrate your payment pages using one of the methods. After completion of 3DS flow the payment intent ID can be passed as payment_intent[gw_token] in Chargebee API.

To perform 3DS for existing stored card, initialize the customer and card id retrieved from Chargebee API in the Stripe's payment intent API.

To know more about Stripe Elements' 3DS flow using Chargebee, take a look at our tutorial.

Braintree

Braintree supports SCA compliant 3DS flow using Braintree.js for new cards and the existing cards in vault.

After 3DS verification is performed for a new card, the 3DS-verified nonce generated can be passed to the payment_intent[gw_token] parameter in Chargebee APIs.

After 3DS verification is performed for a stored card, you need to generate a 3DS-verified nonce using Braintree permanent token and pass it to payment_intent[gw_token] parameter. Also, pass the Braintree permanent token to payment_intent[gw_payment_method_id].

To know more about Braintree's 3DS flow using Chargebee, take a look at our tutorial.

Note: We would be releasing API updates for Adyen in the coming weeks. Follow our Timeline to keep up with 3DS related happenings at Chargebee.

HTTP status code is used to indicate success or failure of an API call. The body of the response contains the details of the error in JSON format.

Sample error response:

Below is the sample error that is returned for 'create subscription' api call when the plan referred in the plan_id parameter is not present. The returned http status code will be 404.

Http Status Codes

The standard http status codes used are

• 2XX The response code in this range implies the API call has succeeded.
• 3XX This range is not used currently.
• 4XX response codes indicate failure due to wrong input (i.e, client) side. As the usable list of http codes in the 4xx range is limited we predominantly use the 400 ( BAD REQUEST ) error code for client side errors.
• 5XX response codes indicate API request was valid but failed due to bugs on the Chargebee server side.

Error Attributes

Note: There would be additional deprecated attributes (like error_code) which are present to support older versions of the libraries.

Error handling recommendations

Chargebee will return the first encountered error when validating the API call. Hence we strongly recommend you to validate the user input on your side before calling Chargebee's API. Otherwise you will have to show the mistakes one at a time for the user to correct it before proceeding to the next.

There are cases where you have to depend on Chargebee's validation for handling errors like coupon code validation or VAT validations. In such cases check for the specific param and api_error_code combination to show proper error message to your users.

The following are the list of codes grouped based on type.

Note: 'New' codes might get added (though additions are very rare). If you are handling for specific codes also ensure that there is a default block for handling unknown(/new) error codes.

These errors may occur when trying to store the payment method details(such as card, paypal, ACH etc) or when trying to collect a payment. These errors should be handled and appropriate message should be shown to the user. The type attribute in the error response is sent as payment.

The following errors are caused due to invalid request. In most cases the errors should occur only during the development phase. The type attribute in the error response is sent as invalid_request.

These errors are returned when the request was valid but the requested operation could not be completed. These errors should occur very rarely. You generally need not handle them specifically other than showing a generic error message to your users. The type attribute in the error response is sent as operation_failed.

Most of these errors occur due to improper API environment setup in your server or changes to the site's configuration. The type attribute is not sent in the error response.

Sometimes you would want to disable emails or webhooks for the events that are generated for a particular api call. Typically you would need this when you are migrating customers from your system to Chargebee via api. One option would be to disable all the emails(/webhooks) for all events during the import process. But then you would still want to send emails for new customers who are signing up.
Chargebee supports custom http headers on each api request that allow you to control the actions that are triggered on the events generated by that particular api call.

• To skip all actions to be done on the events pass the header chargebee-event-actions with value all-disabled
• To skip only emails pass the header chargebee-event-email with value all-disabled
• Similarly to skip only webhooks pass chargebee-event-webhook with value all-disabled

        curl  https://mysite.chargebee.com/api/v1/customers \
     -H chargebee-event-actions:all-disabled \
     -u myapikey: \
     -d customer[email]="john@user.com" \
    

Passing user details like IP address, email address and Device information from your website to Chargebee is always useful. IP address information is routed to the payment gateway (where it will be validated against active fraud detection filters), used for EU tax validation, referral integration and event reports. Email addresses and Device information, even more ubiquitous, are used for identification. Chargebee supports http headers to send user details.

Use the following headers to send user details across:

• For the IP address of the customer where the request originated - chargebee-request-origin-ip; where an example is 192.168.1.2.
• For details of the customer - chargebee-request-origin-user; where an example is user@example.com.
• For the device from which the customer has made the request - chargebee-request-origin-device; where an example is Android.

 curl  https://mysite.chargebee.com/api/v1/customers \
     -H chargebee-request-origin-ip:192.168.1.2\
     -H chargebee-request-origin-user:user@example.com\
     -H chargebee-request-origin-device:Android\
     -u myapikey: \
     -d customer[email]="john@user.com" \

Chargebee gives you the option of creating custom fields to track additional information about Customers and their Subscriptions. You can create custom fields for customers, subscriptions, plans, and addons. Once the custom fields are created, they can be added to the hosted checkout pages and invoices. They can be accessed through the web interface, and via the API. More on Custom Fields here.

Sample Request

curl https://{site}.chargebee.com/api/v1/subscriptions \
-u {site_api_key}: \
-d plan_id="basic" \
-d "cf_notes"="sample" \
-d "customer[cf_gender]"="sample"

If you would want to store additional/custom data at a resource's level, you can make use of Meta Data.

For example, if you're a data service provider and would want to store certain features of a particular plan such as "Usage Limit", "Speed within limit", etc., you can have it stored in the Meta data of the Plan.

Meta Data can be passed during the Add/Update operations, for the following resources:

• Subscriptions
• Customers
• Plans
• Addons
• Coupons

Meta Data can only be stored in the JSON format. You can also use nested JSON objects.

Considering the same example as above, if you'd want to store the additional features of a particular data plan here's how the JSON would look:

• Tiered Pricing : If you're looking to set up a tiered pricing model using Chargebee, click here.
• Volume Pricing : If you're looking to set up a volume-based pricing model, click here.