Advanced features

The Chargebee API offers additional features such as custom HTTP request headers, custom fields, metadata. Moreover, the ability to set up multiple business entities, payment sources, and gateway accounts is also available. The sections below describe how to use these features.

If your site has multiple business entities, you can pass the chargebee-business-entity-id: <business-entity-id> custom HTTP header to specify the business entity for which Chargebee should perform the operation. Here <business-entity-id> is the unique identifier of a business entity.

The following sample shows how to create a customer within a business entity:

curl  https://{site}.chargebee.com/api/v2/customers \
    -H chargebee-business-entity-id:__dev__8at09TEfAyAk2\
    -u {api-key}: \
    -d customer[email]="sarah@acme.com"    

Alternative to passing the header

As an alternative to passing the request header, for some create operations, you can specify the business_entity_id using a query string parameter. See the create customer endpoint for example.

Providing user details

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 is validated against active fraud detection filters, and used for EU tax validation, referral integration, and event reports. Email addresses and device information, even more ubiquitous, are used for identification. Chargebee supports the following custom HTTP request headers for providing such user details:

• chargebee-request-origin-ip: Used to provide the IP address, of your customer/user, from where the request originated. For example, 202.170.207.70.
• chargebee-request-origin-user: Used to provide the email address of your customer/user. Use this when the email address has only ASCII characters. For example, amara@acme.com.
• chargebee-request-origin-user-encoded: Used to provide the Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters (such as user.квіточка@example.com). When this header is provided, the header chargebee-request-origin-user is ignored.
• chargebee-request-origin-device: Used to provide a string indicating the device from which the request was made. For example, Android, Ubuntu, or iOS.

Using Origin IP and Device Data with Chargebee APIs

When making API calls to Chargebee, including the chargebee-request-origin-ip and chargebee-request-origin-device details can provide valuable context about the user initiating the request. This information can enhance fraud detection and may be required by certain payment gateways. This document outlines the advantages of providing chargebee-request-origin-ip and chargebee-request-origin-device data and explains what happens if these details are omitted.

Information about Origin IP and Device Data
When you make a Chargebee API call, sending the chargebee-request-origin-ip and chargebee-request-origin-device details add more context about the user making the request. This additional information can be crucial for payment gateways to assess transaction legitimacy. However, if you're using Chargebee's frontend capabilities or hosted pages, this information is automatically managed, and you don't need to provide it separately.

Advantages of providing this information

• Compliance with gateway requirements: Some payment gateways require chargebee-request-origin-ip and chargebee-request-origin-device details to process transactions.
• Enhanced fraud detection: Certain gateways use this data to identify potential fraud based on their specific fraud detection rules.

What happens if these details are missing?

If you don't provide the chargebee-request-origin-ip and chargebee-request-origin-device details when making a Chargebee API call such as when using the create_subscription_for_items API, you can still proceed with the transaction. However, for API calls involving payments from end customers, it's recommended to include this information to:

• Improve fraud prevention: Enhances the chances of successful fraud detection by providing more context.
• Meet gateway requirements: Some gateways might have mandatory requirements for this data, and omitting it could lead to processing issues.
  Note: For Stripe, SEPA, iDEAL, ACH, and Bancontact,
  • chargebee-request-origin-ip and chargebee-request-origin-device are mandatory. Failing to provide these parameters will cause the flow to fail.
  • The bank owner's name and email are mandatory only if the payment method is stored for recurring payments. For one-time payments, the bank owner's name and email are optional.
  • Bank owner's name and email are mandatory for ACH if the payment method is stored for recurring or one-time payments.

Examples

Providing user details with the email address containing only ASCII characters:

curl  https://mysite.chargebee.com/api/v2/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" \

Providing user details with the email address containing UTF-8 characters (here user.квіточка@example.com):

Disabling webhooks and emails

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/v2/customers \
     -H chargebee-event-actions:all-disabled \
     -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, item families, and items. 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 API. More on Custom Fields here.

Sample Request

curl https://{site}.chargebee.com/api/v2/customers \
-u {site_api_key}: \
-d first_name="John" \
-d last_name="Doe" \
-d email="john@test.com" \
-d "cf_gender"="sample"

Some resources in Chargebee support an attribute called metadata or meta_data that can be used to store additional information for the resource. The data can be stored in JSON format. The following resources support this:

• Subscriptions
• Customers
• Items
• Item prices
• Coupons

Metadata can be passed in both the "create" as well as "update" operations against the resource.

Limitations of metadata

• Metadata has a character limit of 65,535.
• Metadata information is not surfaced on any customer-facing artifacts such as hosted pages or invoices.
• When using the "list" APIs, you cannot filter resources based on information stored within metadata.
• Metadata is not returned by the Export APIs.

Chargebee supports configuring multiple gateway accounts for a gateway type. For example, you can configure multiple Authorize.net accounts to process different currencies.

The default Gateway account to use for each currency can be configured using Smart Routing. However, you can override the selected gateway for each transaction in Chargebee. To do this pass the gateway_account_id parameter when calling the following APIs:

• Create a customer
• Update payment method for a customer

• Create a subscription
• Update a subscription
• Import a subscription

• Update card for a customer
• Switch gateway

• 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 items
• Import subscription for items
• 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

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.