PayPal Commerce
PayPal Commerce lets you accept card, Venmo, and PayPal Wallet payments through one gateway connection in Chargebee, with card payments in up to 25 currencies. Use this guide to configure the gateway, import tokens, and transition a custom checkout from PayPal Express Checkout.
- PayPal Commerce supports Cards (Advanced Credit and Debit Card payments - ACDC), Venmo, and PayPal Wallet on the same gateway connection. Cards and Venmo use PayPal's Vault ID token format. Vault ID is PayPal's current token format; the legacy Billing Agreement ID (BAID) is deprecated by PayPal. When migrating Card or Venmo payment methods to Chargebee, pass the Vault ID as the reference ID. See the payment parameters API docs for details.
- Chargebee supports other PayPal payment services as well.
- If multicurrency is enabled, ensure that the currencies configured in your Chargebee site are also configured in your PayPal merchant account. Chargebee will mark the invoice as void if the customer makes a payment using a currency that is not configured in your Chargebee site.
Prerequisites for PayPal Commerce
Complete the following requirements before you accept payments via PayPal Commerce with Chargebee.
- PayPal Business Account: Use a PayPal Business Account. A Personal Account cannot be used. Find more on the types of PayPal accounts here.
- Reference Transactions: Enable reference transactions on your PayPal Business Account. This is required for Chargebee live sites. Contact PayPal Customer Support to enable it. Reference Transactions are not supported in PayPal sandbox accounts.
- Advanced Card Processing: Enable Advanced Card Processing in PayPal. After it is enabled, you can connect your PayPal account to Chargebee and use Advanced Cards.
- Supported currencies: Configure the same list of currencies in both your PayPal Business Account and your Chargebee live site.
Supported payment methods for PayPal Commerce
This integration supports the following payment methods:
- Cards (Advanced Credit and Debit Card payments - ACDC)
- Venmo via PayPal
- PayPal wallet
Integration options for PayPal Commerce
Chargebee offers the following options to integrate with PayPal:
- Chargebee hosted pages
- Chargebee.js
- Gateway JS
| Integration Method | Description | Payment Card Industry (PCI) compliance requirements |
|---|---|---|
In this method, customers' card information is collected by Chargebee's checkout and directly passed on to PayPal. | Low (Your PCI compliance requirements are greatly reduced due to the usage of Chargebee's checkout) | |
| Chargebee.js | You will collect raw card details via your custom checkout and pass them to Chargebee.js 3DS Helper to conduct the 3D Secure (3DS) flow. However, this will need you to ensure PCI compliance. | High (Card information will be collected by you directly; you will have to take care of PCI Compliance requirements) |
| Chargebee.js (Chargebee Components and Fields) | In this method, Chargebee's components and fields collect customers' card information and tokenize it with PayPal. | Low (Your PCI compliance requirements are greatly reduced due to the usage of Chargebee's components and fields) |
| Gateway JS + Chargebee API | The payment method is collected in the Gateway’s JS and converted into a permanent token. This permanent token will be used to process payments associated with the respective customer. | Low |
Configuring PayPal Commerce
To configure PayPal Commerce, follow the steps below:
- Log in to your Chargebee Billing site.
- Go to Settings > Configure Chargebee > Payment Gateways.
- Click +Add Gateway.
- Select PayPal.
- Connect to an existing account or create a new one.
- Connect to your PayPal account using your username and password.
- Click Go back to Test Store.
- The configuration page appears as shown below. Click Add to add a Business description. The description you add here is displayed in the Checkout screen.
All transactions made via the Chargebee test site will be available in your PayPal sandbox environment.
Enable Cards and Venmo for PayPal Commerce
You can enable Cards and Venmo from the same PayPal Commerce gateway configuration page. Enabling a payment method fails if the connected PayPal account does not have the required scopes for Advanced Cards or Venmo.
Existing PayPal Commerce merchants
- Open the existing PayPal gateway configuration in Chargebee.
- Enable Cards, Venmo, or both from the gateway configuration page.
- If prompted, or if enablement fails due to missing scopes, reconnect your PayPal account from the gateway configuration page.
New PayPal Commerce merchants
- Connect your PayPal account to Chargebee.
- Enable Cards or Venmo only if your PayPal account has the necessary scopes.
Capture settings for PayPal Commerce
Capture Settings is a PayPal Commerce gateway-level option under Advanced Configurations. You configure it once for the gateway, not per payment method.
Charging a customer involves two steps:
- Authorization: PayPal verifies the payment method and reserves the funds. The money is not yet moved out of the customer's account.
- Capture: The reserved funds are transferred to your account, and the customer is charged.
By default, Chargebee captures the funds immediately after a successful authorization. With delayed capture, Chargebee authorizes the payment at checkout and captures it after a delay that you configure. This gives you a window to confirm stock availability, complete order fulfillment, or run fraud checks before the customer is charged.
Delayed capture is enabled for your site by Chargebee. If the Capture Settings section is not visible on your Configure PayPal page, contact Chargebee Support.
What happens when the delay ends for PayPal Commerce
When the delay period ends, Chargebee checks the invoices linked to the authorization and does one of the following:
- Captures the payment, if a linked invoice still has an amount due. Chargebee captures the lower of the authorized amount and the total amount due across the linked invoices.
- Voids the authorization, if none of the linked invoices has an amount due. For example, the invoice was already paid another way, or it was voided because you canceled the subscription during the delay period. Chargebee voids the authorization when the delay period ends, not at the moment the invoice is voided.
If you void the authorization before the delay ends, either from the transaction in Chargebee or with the Void an authorization transaction API, Chargebee does not capture it when the delay period ends.
Increasing an invoice amount after the payment is authorized does not increase the amount that Chargebee captures. The capture is always limited to the amount that PayPal authorized.
Configure delayed capture for PayPal Commerce
Follow these steps to configure delayed capture for PayPal Commerce:
-
Log in to your Chargebee Billing site.
-
Go to Settings > Configure Chargebee > Payment Gateways and select PayPal.
-
Scroll to Capture Settings under Advanced Configurations.
-
Under Capture Type, select one of the following. Immediate Capture is selected by default.
- Immediate Capture: Chargebee captures the funds as soon as the payment is authorized.
- Manual Capture: Chargebee authorizes the payment and captures it after the delay you set.
-
Select Manual Capture. The Capture Delay list appears.
-
Select a delay period from the Capture Delay list. You can select No delay, 1 Hour, 6 Hours, 12 Hours, 1 Day, 3 Days, 5 Days, 7 Days, or Custom. Selecting Manual Capture with No delay is the same as immediate capture. To delay the capture, you must select a delay period.
-
If you select Custom, enter a whole number in Delay Value and select Minutes, Hours, or Days as the Unit. Decimal values are not supported, and the delay cannot exceed 7 days.
-
Click Apply and then click Confirm. The change takes effect immediately.
Ensure your PayPal account is enabled for separate authorization and capture. With delayed capture, the payment is authorized first and the funds are captured after the configured delay period.
Limitations of delayed capture for PayPal Commerce
Review the following before you turn on delayed capture:
- Delayed capture applies to card payments (Advanced Credit and Debit Card) that your customer initiates at checkout. It is not supported for the PayPal wallet or Venmo.
- Payments that Chargebee initiates on a stored payment method, such as automatic renewals, payment retries, and dunning attempts, are always captured immediately.
- The maximum delay is 7 days. PayPal authorizations expire after a period set by PayPal, so a longer delay increases the risk that the authorization can no longer be captured.
- Your PayPal account must be enabled for separate authorization and capture.
Configuring Cards (Advanced Credit and Debit Card payments - ACDC)
Follow the steps below to configure the settings for cards:
- On the Configure PayPal page, click Manage under Cards.
- Enable the following:
- Always retain card information in PayPal when customer updates it: Enabling this option stores the updated card information in PayPal rather than the default gateway.
- Enable 3D Secure: When enabled, payments made via card (debit or credit) are authenticated using 3D Secure, if applicable.
Supported tokens for PayPal Commerce
This integration supports the following tokens:
| Token | Description | Format & Sample |
|---|---|---|
| Permanent Token (PayPal JS) | Payment method ID generated at the gateway. | Format: |
| Chargebee Payment Intent ID (Chargebee.js) | This is the Payment Intent ID returned after a successful authorization process. | Format - |
| Vault ID | PayPal's current token format. Used for Cards, Venmo, and PayPal Wallet. Required when migrating Card or Venmo tokens to Chargebee. | Format: PayPal Vault ID |
| Billing Agreement ID (BAID) | PayPal's legacy token format. Deprecated by PayPal. Not supported for Cards or Venmo. Supported only for the existing PayPal Wallet integration, along with Vault ID. | Format: Billing Agreement ID |
Vault ID is PayPal's current token format. Billing Agreement ID (BAID) is the legacy token format and is deprecated by PayPal. For Cards and Venmo, use Vault ID only. For PayPal Wallet, both Vault ID and BAID are supported.
Migrate PayPal Card and Venmo tokens to Chargebee
When you migrate PayPal Card or Venmo tokens to Chargebee:
- Chargebee supports migration using only the PayPal Vault ID.
- Chargebee does not support the legacy Billing Agreement ID (BAID) for Cards and Venmo.
- For the existing PayPal Wallet integration, both Vault ID and BAID are supported.
Vault ID is PayPal's current token format. Billing Agreement ID is the legacy token format and is deprecated by PayPal.
Upgrade from PayPal Express Checkout to PayPal Commerce
PayPal Express Checkout and PayPal Commerce can coexist on the same Chargebee site. Keep Express connected for existing Billing Agreement IDs (BAIDs) and their renewals. Use Commerce for new PayPal Wallet Vault v3 purchases.
Configure Smart Routing to select your PayPal Commerce gateway account for new PayPal Wallet payment methods in each supported currency. Routing changes do not change the gateway account linked to existing payment methods. For custom API imports, explicitly pass the Commerce gateway_account_id.
Existing Express payment methods are not automatically migrated to Commerce. They remain on Express until the customer updates their payment method. The legacy Express gateway expects classic Billing Agreement IDs (B-...); do not send new Vault v3 tokens to that gateway.
Import PayPal Wallet Vault v3 tokens into PayPal Commerce
For a custom checkout that creates PayPal Wallet Vault v3 tokens, use Create a payment source using permanent token (POST /api/v2/payment_sources/create_using_permanent_token) to add the payment method to a Chargebee customer.
Before importing, create a new Vault v3 token under the same PayPal Business account connected to the Commerce gateway. For sandbox tests, use the same PayPal sandbox account connected to that gateway.
Use sandbox imports to validate token storage; a successful import does not verify subsequent renewal payments. Reference transactions are a prerequisite for live payments, as described in Prerequisites for PayPal Commerce. Validate renewal behavior in live after reference transactions are enabled on the connected PayPal Business account.
Pass these values in the request:
customer_id: The ID of the Chargebee customer to attach the payment source to.reference_id: The new PayPal Wallet Vault v3 token.gateway_account_id: The Chargebee gateway account ID for the connected PayPal Commerce gateway.type:paypal_express_checkout. This payment method type also applies to PayPal Wallet imports through Commerce; it does not select the legacy Express gateway.
A successful import stores the PayPal Wallet payment source on the customer. The existing primary payment source remains unchanged by default. To make the imported source primary, set replace_primary_payment_source to true in the import request. A payment source assigned directly to a subscription remains assigned even after the customer's primary source changes. To move those renewals to Commerce, change the subscription's assigned payment method to the imported source.
For account-context lookup failures or attempts to import an already stored token, see Why does importing a PayPal Vault payment token fail on PayPal Commerce?.
Checkout flow for PayPal Commerce cards
When a customer subscribes to a product or service from your website for the first time and chooses to pay using PayPal, a PayPal Vault ID is created, and Chargebee associates this Vault ID with that customer. The Vault ID allows Chargebee to charge your customers automatically without them having to perform any action (such as logging into PayPal and approving the transaction) during each renewal. In addition, it can be used to pay one-time charges as well. The Vault ID does not expire unless the customer cancels it.
The checkout flow for Advanced Credit and Debit Card payments (ACDC) via PayPal is as follows.
Prerequisite: Configure the First and Last Name as Mandatory fields for card payments.
- To initiate a purchase, click Proceed to Checkout from the Your Order page.
- Enter your Account Details, such as your First Name, Last Name, and Email Address, and click Next.
- Enter the Billing Address details and click Next.
- Add your card details and click Next.
- Complete the 3DS authentication when redirected to the bank page.
- Upon successful authentication, customers are redirected to the checkout to confirm the subscription purchase.
- Check the order information and click Pay & subscribe.