Getting Started

Building Blocks

Subscription Features



Billing Features


Payment Methods

Direct Debit Payments

Configuring Gateways

Fraud Management

Hosted Pages

Attach Additional Data


Open Source Resources

Other Features

API Integration

Third Party Integrations


Chargebee supports card payments and other payment methods such as PayPal Express Checkout and Amazon Payments. The first step to process card payments using Chargebee is to get a payment gateway and a merchant account ready. Chargebee is a subscription billing management service that eases the complexities involved in managing recurring payments.

What is a Payment Gateway? 

A payment gateway is a service that lets you process online card payments made by your customers. It is the online equivalent of a swipe machine which is present in a brick and mortar store. A payment gateway routes the details of a transaction to the merchant bank's processor which in turn is routed to the card processing network and finally to the card issuing bank. The results of the transaction are delivered back to the payment gateway which are then delivered to the merchant's website.

What is a Merchant Account? 

A merchant account is a type of a bank account that allows merchants to accept payments made by cards. When a payment is made, funds are transferred to the merchant account, before they are actually transferred to your business bank account. The bank which provides a merchant account is usually called an acquiring bank.

Merchant accounts, unlike the regular holding accounts (checking/saving) are a line of credit. After due risk assessment, acquiring banks extend this line of credit. Let us say the merchant becomes insolvent, in this scenario if a customer requests for a chargeback, the acquiring bank has to pay the customer. Due to this credit liability, merchant accounts are said to be a line of credit and hence a stringent process is followed in issuing a merchant account.

To get a merchant account, you will have to undergo an underwriting process which includes a credit check, supplying data related to your finances etc. Learn more about merchant accounts here 


Certain payment gateways like Stripe, Braintree, etc. also provide you with a bundled merchant account.

Chargebee's role in processing Card Payments 

Chargebee places itself between your website and the payment gateway you use. The process related to the payment flow works as follows:

  1. Customers subscribe for a service through your website by entering their card details in the payment page (The payment page can either be hosted at your website or at Chargebee).
  2. Chargebee forwards the card details to the payment gateway for processing.
  3. The gateway passes the secure information to the processor of the merchant bank which in turn passes it on to the credit card network (MasterCard, Visa, etc.).
  4. The credit card network then routes the transaction to the card issuing bank.
  5. The issuing bank authorizes the transaction based on certain factors like sufficient funds, expiry date of the card etc. and then conveys the result of the transaction to the card network which in turn relays the results to the merchant bank processor and finally to the gateway.
  6. The gateway then delivers these results to Chargebee. In case of a success, Chargebee displays a success message and records the transaction details. In case of a failure, Chargebee displays a corresponding error message.
  7. If the transaction is successful, the funds are settled to the merchant account and after a few days transferred to the business bank account of the merchant.

Chargebee stores your customers' card details in the payment gateway's card vault or in Spreedly's (Chargebee's gateway partner) card vault depending on your choice of payment gateway. When the card details are stored in a vault, a token corresponding to the card is generated. Chargebee makes use of those card tokens to charge customers for all future payments.


As a merchant, you will not have direct access to the complete card details of your customer, but you do have access to the last 4 digits of the card number along with the expiry dates and card type. This information will be helpful for you to handle customer support related to payments.

Configuring a card payment gateway 

Once you have a payment gateway and a merchant account in place, the next step would be configuring the payment gateway with Chargebee. Details about configuring a card payment gateway in Chargebee are discussed here.

Card Verification 

Card verification is the process of validating a card to ensure that the card number provided is tied to a valid bank account, can be charged, and can be vaulted.

For the gateways Stripe, Braintree, Pin Payments, and eWay Rapid, card verification has to be enabled at the respective gateway's end.

For Authorize.Net, WorldPay, PayPal Payments Pro & PayPal Payflow Pro, Chargebee provides the option of card verification.

Chargebee carries out card verification by performing a one unit charge (1 USD, 1 GBP, 1 AUD, 1 EUR, etc.) which is voided as soon as the authorization is complete.
If there is an immediate payment involved, Chargebee does not perform card verification.

To enable card verification for the above mentioned gateways, in the web interface, go to SettingsGateway Settings, select your gateway and enable the card verification option.


It is a good idea to indicate to customers signing up or updating their cards that there might be a "test authorization" charge on their cards. This helps avoid confusion and a support call to you when customers see these charges on their bank statements or when they get notified by their banks.

Card Address Verification 

For processing card payments online, Address Verification System (AVS) is an important check that is done by the payment gateway. This service cross verifies the credit card's billing address entered by the customer with the address stored in the credit card company. It is a security check that helps in combating fraudulent transactions which, if unnoticed, could result in chargebacks.

If you have enabled AVS check at your gateway's end, ensure that the same fields are enabled in Chargebee under Card Address Verification.

Enabling the Card Address Verification fields (in Chargebee) is just an additional check which ensures that all the details required by your gateway's AVS settings are present.
Even if you have not enabled the required fields here, Chargebee still passes this information to the gateway.

In order to avoid validation errors returned by the gateway due to the absence of required data (such as AVS fields), it is recommended that you enable these settings.

If you use Chargebee's API or create subscriptions via the web interface, ensure that the required Card Address Verification fields are marked under Site SettingsSite Info under the Card Address Verification section.

If you use Chargebee's hosted pages, configure the required card fields in SettingsHosted Pages SettingsField Configurations.


Ensure that the address verification requirements you configure here match the AVS (address verification system) requirements that you have configured in your payment gateway.

Supported Card Types 

You can display the card types you will be supporting on the hosted pages.

You can configure this in your Gateway Settings.


Before you specify the card types, check with your payment gateway provider to ensure that they support and have enabled the required card types.

Adding/Updating Card Details 

Adding or updating card details of an existing customer can be done:

Via the Web Interface

i) Using the "Request Payment Method" option

Request Payment Method gives customers an option to update the details of an existing payment method and also switch between the various payment methods you offer.

In this method, an email containing a secure link is sent to your customers. When customers click on this link, they are redirected to a secure page where they can update their payment method details.

To request payment method details from your customers, open a subscription in the web interface, and click on the Request Payment Method option from the Actions panel.

Clicking on it will take you an email editor page with the URL in place, using which you can send out a mail to the customer.

ii) Through the "Payment Method Details" section

As a merchant if you have the card details of a customer, you can directly add them using the Add Card option available under the Payment Method Details section of a subscription/customer.

To update an existing card, use the Update option that can be found under the Payment Method Details section of a subscription.

2. Via the API

Refer to Scenario 1 & Scenario 2 for information.

3. Via the Customer Portal

Customers can update their card details by logging in to their customer portal. Customers can make use of this option only if you have enabled the customer portal for them.

Removing Card Details 

Whenever a subscription is canceled, some customers might request to have their card details removed. Removing the card details can be done through the web interface or using the Delete Card for a Customer API .

To remove card details, open the particular customer/subscription details page and use the Delete option under the Payment Method Details section.

When the card details are removed, Auto Collection will be automatically turned Off regardless of the status of the subscription. This makes the subscription an offline subscription. So, if a subscription is in Active state, and you remove the card details, the subscription will remain Active and renew according to the plan. Invoices will be generated and will be in Payment Due state. You will have to manually record the payments for the invoice.

Email Notifications 

Email notifications can be used to notify customers about payment related events such as card expiry, payment failure, etc.

For customers whose cards are about to expire or have already expired, you can configure Chargebee's email settings to send out reminders to those customers, letting them know about their card statuses. Learn more.

Test Credit Card Numbers 

The card numbers provided here can be used for testing payment transactions on Chargebee's test site. Use any 3 or 4 digit numbers for CVV and a valid date in the future for the expiry date.

A set of valid and invalid cards for the test gateways are given below.

1. Chargebee Test Payment Gateway

These card numbers can be used if you have Chargebee's test payment gateway configured.

Valid Cards:

Using the following cards will result in successful transactions.

Card Number

Card Type

Response Description

4111 1111 1111 1111


Successful Transaction

5555 5555 5555 4444


Successful Transaction

3782 822463 10005


Successful Transaction

6011 1111 1111 1117


Successful Transaction

3530 1113 3330 0000


Successful Transaction

3852 0000 0232 37


Successful Transaction

4119 8627 6033 8320


Card Storage will fail with a gateway verification failure

4005 5192 0000 0004


Charge attempts will fail with an "Insufficient funds" error.

2. Stripe Payment Gateway (Test Mode)

These card numbers can be used if you have a Stripe test account configured in Chargebee's test site.

3. Braintree Payment Gateway (Sandbox Mode)

These card numbers can be used if you have a Braintree sandbox account configured in Chargebee's test site.