Stripe Prerequisites & Configuration
Configure Stripe in Chargebee: prerequisites, connection steps, webhooks, card settings, and optional packs.
For an overview of supported methods and capabilities, see Stripe.
Prerequisites and limits
| Requirement | Detail |
|---|---|
| Stripe account | Test or live |
| Chargebee plan | All plans; Starter = one gateway per payment method |
| Currencies | 100+ common currencies; availability varies by Stripe account country and card network |
| Stripe API version |
|
| SCA / 3DS (EU) | |
| Auth and capture | One-time, API only, max 7 days |
| Stripe India | See Stripe India integration |
Gateway readiness and required settings
Review these settings when you configure Stripe:
- Activate your Stripe account for live charges before collecting live payments.
- Confirm each transactional currency is available for your Stripe account country and supported by Chargebee.
- For 3DS / SCA markets, enable 3D Secure in Chargebee. Stripe can request 3DS authentication through supported Payment Intent flows, but Chargebee must be configured to handle it.
- For India, 3DS is mandatory for INR payments. For non-INR payments, collect billing and card addresses for services, and billing, shipping, and card addresses for physical goods.
Region and currency notes
Chargebee and Stripe have 100+ common currencies. Availability varies by Stripe account country and card network, so confirm each transactional currency in both sources:
Connect Stripe to Chargebee
Note
We recommend configuring and validating the integration on your test site before repeating the setup on your live site.
Standard setup uses OAuth at Connect — you do not paste API keys manually.
- Click Settings > Configure Chargebee > Payment Gateways > Add payment gateway > Stripe. You can configure Stripe from your test or live site.
- Log in to an existing Stripe account or create a new one.
- The Configure Stripe page opens.
Note
For a seamless customer experience, disable Stripe's direct debit notifications and enable them in Chargebee if you prefer Chargebee to manage them. Enabling notifications in both systems sends duplicate emails to customers.
Due to recent world events, you may experience failures for payments originating from Russian financial institutions or instruments. Review guidelines issued by respective payment gateways for additional information.
Cards
Click Manage next to cards to configure them.
- Prepaid cards: Enable to allow customers to pay with prepaid cards.
- Always retain card information in Stripe: Controls where updated cards are vaulted for existing customers when you use multiple gateways. Enable to retain cards in Stripe even if smart routing moves to a new gateway. Disable to migrate customers gradually as they update cards. Learn more.
Configure webhooks
Webhooks notify Chargebee of changes to Stripe transactions so payment information stays up to date.
When you create the Stripe destination, under Versions select Stripe API version 2026-01-28.clover. Do not select a later webhook API version. If that version is not available, contact Chargebee Support.
- Log in to your Stripe account.
- On the Home page, click the Open Workbench icon.
- Click + Add destination under the Webhooks tab.
- In the Events form, select Your account, choose the necessary event types, and click Continue.
- Select Webhook endpoint under Destination type.
- Enter the Destination name, Endpoint URL (paste the Notification URL from Chargebee), and a description.
Get the Notification URL from Chargebee:
- Log in to your Chargebee account.
- Click Settings > Configure Chargebee > Payment Gateways > Stripe.
- Under Webhooks, copy the Notification URL and paste it as the Endpoint URL.
- Click Create destination.
Necessary event types for webhook configuration
| Webhook events |
|---|
| customer.card.updated |
| customer.source.updated |
| charge.succeeded |
| charge.failed |
| charge.expired |
| charge.refunded |
| charge.refund.updated |
| review.closed |
| source.transaction.created |
| payment_method.updated |
| charge.dispute.funds_withdrawn |
| charge.dispute.closed |
| payment_method.automatically_updated |
| payment_method.card_automatically_updated |
| source.chargeable |
| payment_intent.succeeded |
| payment_intent.payment_failed |
| mandate.updated |
| setup_intent.succeeded |
| setup_intent.setup_failed |
| customer_cash_balance_transaction.created |
Note
If you remove Stripe from Chargebee, this URL is no longer valid. Adding Stripe again generates a new URL that you must paste in Stripe.
See also
Configuring webhooks in Chargebee. Stripe events
Stripe India integration
Chargebee integrates with Stripe India for card payments. Stripe India categorizes accounts by currency (INR and non-INR).
If you sell to customers in INR, you must configure 3DS for multi-factor authentication compliance. Learn more.
Non-INR accounts in Stripe are classified as Goods or Services. Configure Chargebee as follows:
- Services: Make billing and card address mandatory during checkout. Configure Billing and Payment (Card) address fields in Checkout and Self-Serve Portal. Chargebee passes this information to Stripe when it is updated.
- Physical goods: Make billing, shipping, and card address mandatory during checkout. Configure Billing, Shipping, and Payment (Card) address fields in Checkout and Self-Serve Portal. Billing address is passed whenever it is updated; shipping address is sent for every transaction.
- Plan name is shared with Stripe for every transaction for auditing.
Enabling In checkout, prefill address information from in the Payment section under the fields tab on Checkout and Self-Serve Portal settings prefills address information from earlier sections so customers complete checkout faster.
Limitations (Goods account)
- Charges (one-time charges) against customers without subscriptions do not go through because they do not have a linked shipping address.
- Consolidated invoicing with different shipping addresses is not supported.
- Pay now with a different shipping address is not supported.
Test card numbers
Use these card numbers to test card transactions in Chargebee's test site with Stripe in test mode.
While testing, use any number for CVV and a valid future expiry date.
| Card number | Card type | Response description |
|---|---|---|
| 4242 4242 4242 4242 | Visa | Successful transaction. |
| 4000 0000 0000 0002 | Visa | Attempts to charge are declined with a Card Declined error. |
| 4000 0000 0000 0341 | Visa | Card can be added but attempts to charge fail. |
| 4000 0000 0000 0069 | Visa | Charge is declined with an Expired Card error. |
Auth and capture
Auth and capture authorizes and earmarks funds on a customer's card for up to 7 days. The merchant can claim the authorized amount within that period. This is useful when fulfillment is delayed.
Note
- Currently supported only for one-time charges.
- Auth and capture is available via API only.
Authorize — Chargebee checks the card for the authorized amount and places a hold for a set tenure.
- You can hold funds for a maximum of 7 days.
- Authorizations expire automatically after 7 days.
Capture — Collect the authorized funds within the tenure. If you miss the window, you cannot collect later; call a new auth and capture. Uncollected funds are released back to the card.
- You cannot capture more than the authorized amount.
- Partial and multiple captures are not supported.
Void — Void the authorization if you do not want to capture it.
See the Auth and Capture API.
Automated account updater
This integration supports automated account update for cards.
When a customer's card number, expiry, or CVV is updated, Chargebee receives the update in real time through card networks and Stripe. This reduces manual customer effort and payment failures from outdated card information.
Ensure the webhook events for automatic payment-method updates are enabled.
Other payment methods
Cards are configured above. For bank, wallet, and local methods, open the matching setup guide from the Stripe overview.
Top errors and fixes
| Error / symptom | Likely cause | Fix |
|---|---|---|
| Card declined / processor declined | Issuer decline or fraud rules | Try a different card or contact the issuing bank. See Card declined troubleshooting. |
| Expired Card | Card past expiry | Update the card in the portal; automated account updater may refresh it. |
This Connect account cannot currently make live charges | Stripe Connect account not fully activated | |
Customer does not have a linked card with ID card_… | Stale or missing payment method reference | Re-add the card. See Linked card ID error. |
As per Indian regulations, goods export transactions require a billing and shipping address | Missing address fields for Stripe India goods account | Make billing and shipping mandatory; see Stripe India and this KB. |
| Webhook delivery issues | Stale Notification URL after remove/re-add | Update the endpoint URL in Stripe after re-adding the gateway. See external Stripe webhook delivery issues. |
| SetupIntentAuthenticationFailure while updating PM | 3DS / SetupIntent failure on update |
See also Payment errors.
FAQ
How do I configure Chargebee's webhook in Stripe?
Copy the Notification URL from Chargebee Stripe settings and paste it as the endpoint in Stripe Workbench. See How do I configure Chargebee's webhook in Stripe?.
Should I configure on test first?
We recommend completing the end-to-end setup on your test site before repeating it on your live site.
Which test cards can I use?
4242 4242 4242 4242 for success; 4000 0000 0000 0002 for declined; 4000 0000 0000 0069 for expired. See Test card numbers.
What happens if I remove Stripe from Chargebee?
The Notification URL becomes invalid. After you re-add Stripe, paste the new URL in Stripe.
Is auth and capture supported?
Yes for one-time charges via API only, with a maximum hold of 7 days. See Auth and capture.
Is it mandatory to configure Chargebee webhook in Stripe?
See Is it mandatory to configure Chargebee webhook in Stripe?.
I'm moving to a new Stripe account in Chargebee. What steps should I follow?
See I'm moving to a new Stripe account in Chargebee and How to move to a new Stripe account.
Which API keys do I need for Stripe.js?
See Which API keys do I need to set up Stripe.js?.
Limitations and known constraints
- Auth and capture: one-time charges only; API only; max 7-day hold; no partial or multiple captures; not for renewals
- Stripe India Goods accounts: one-time charges without subscriptions, consolidated invoicing with different shipping addresses, and Pay now with a different shipping address are not supported
- Starter: one gateway per payment method
- Sending raw card details to Chargebee for 3DS is not recommended
Continue the journey
- Back: Stripe overview
- Next: Stripe 3DS Implementation
Was this article helpful?