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.
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.
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
Chargebee places itself between your website and the payment gateway you use. The process related to the payment flow works as follows:
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.
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 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 Settings > Configure Chargebee > Payment Gateways, 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.
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 in Settings > Configure Chargebee > Billing LogIQ under the Card Address Verification section.
If you use Chargebee's hosted pages, configure the required card fields in Settings > Configure Chargebee > Checkout & Portal > Fields > Payments.
Ensure that the address verification requirements you configure here match the AVS (address verification system) requirements that you have configured in your payment gateway.
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 or updating card details of an existing customer can be done:
Whenever card details are added/updated and the last recurring invoice for the customer is in payment due or not paid status, an attempt to collect it is made automatically. However, this does not happen if the associated subscription status is cancelled.
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 Chargebee user interface, and click Request Payment Method on the Action panel.
Clicking on it will take you an email editor window with the Update Payment Method button in place. You can now collect the payment method details by sending out this email to the customer.
As a merchant if you have the card details of a customer, you can directly add them using the Add Card/Add Payment Method option available under the Payment Method section of a subscription/customer.
To update an existing card, use the Edit option that can be found under the Payment Method section in the customer details page.
Refer to Scenario 1 & Scenario 2 for information.
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.
When specific information pertaining to the card, such as the customer's name, billing address and date of expiry has to be updated in the payment gateway, the Partial Card Update feature comes into place. Thus the customer details in Chargebee and the payment gateway stay in sync.
Via the API
Refer to the following API operation to partially update the card details.
Refer to the solution article to learn more about how to pass information to the relevant fields through the API for Stripe/Braintree payment gateways vs other payment gateways.
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's details page and use the Delete option under the Payment Method 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.
When you have multiple payment gateways configured in your site, you can choose to store the updated card details of an existing customer in the secondary payment gateway instead of the default payment gateway by enabling the Card storage option.
Say you have Stripe and Braintree payment gateways configured in your site, let Stripe be the primary gateway, all the transactions will be processed via Stripe by default. Let's say you choose Braintree to be your primary gateway instead. Now, when a customer whose card details are present in Stripe updates their payment method, it will naturally be stored in Braintree which is the default gateway, but you can choose to retain it in Stripe by enabling this option.
Navigate to Settings > Configure Chargebee > Payment Gateways, select the payment gateway you have configured, and enable the Card Storage option as shown below,
Chargebee accepts prepaid cards by default. If you would like to disallow prepaid cards, enable the Don't allow prepaid cards option in the Supported cards section of your gateway's configuration page.
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.
The prepaid card numbers provided here can be used for testing payment transactions on Stripe and Braintree. If the Don't allow prepaid cards option is enabled on your respective gateway configuration page, the following errors will be returned:
| Card Number |
Gateway |
Response Description |
| 5105105105105100 |
Stripe |
Error: Prepaid cards are not supported |
| 4500600000000061 |
Braintree |
Error: Prepaid cards are not supported |
| 5105105105105100 |
Chargebee's Test Payment Gateway |
Error: Prepaid cards are not supported |
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 Gateway
These card numbers can be used if you have Chargebee's test gateway configured.
Valid Cards:
Using the following cards will result in successful transactions.
| Card Number |
Card Type |
Response Description |
| 4111 1111 1111 1111 |
Visa |
Successful Transaction |
| 5555 5555 5555 4444 |
MasterCard |
Successful Transaction |
| 3782 822463 10005 |
AMEX |
Successful Transaction |
| 6011 1111 1111 1117 |
Discover |
Successful Transaction |
| 3530 1113 3330 0000 |
JCB |
Successful Transaction |
| 3852 0000 0232 37 |
Diners |
Successful Transaction |
| 4119 8627 6033 8320 |
Visa |
Card Storage will fail with a gateway verification failure |
| 4005 5192 0000 0004 |
Visa |
Charge attempts will fail with an "Insufficient funds" error. |
In case you're looking for 3DS test cards to be used in Chargebee Test Gateway, you can find them here.
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.
Here's how the Request Payment Method option is displayed in Classic UI:
Here's how the Add card option is displayed in Classic UI inside customer/subscription details page.
Here's how the Update and Delete options for payment method are displayed in the customer details page.
1. What is a card token?
Card token is the reference to a customer's card details, provided by the payment gateway after storing the cards in vault. These card tokens are used to charge customers for all future payments.
2. What is a Reference ID?
Reference ID is the same as a card token.