# Payment Method Helpers
> **Deprecated**
>
> Payment Method Helpers are deprecated. They still work and existing integrations are unaffected, but they're no longer the recommended approach. For new integrations, use [Payment Components](https://www.chargebee.com/docs/payments/2.0/payment-components/overview) instead - actively maintained and built to support multiple payment methods. For what changes when you move across, see [Comparison with Card Components and the Payment method helper](https://www.chargebee.com/docs/payments/2.0/payment-components/overview#comparison-with-card-components-and-the-payment-method-helper).
## Overview
This page documents the Payment Method Helpers API, which provides methods to handle payment authorization flows for various payment methods including cards, bank transfers, digital wallets, and cryptocurrencies. Payment method helpers initiate the payment process and guide users through payment authorization.
## Prerequisites
Before using the Payment Method Helpers API, ensure you have [initialized Chargebee.js](https://www.chargebee.com/docs/js/settingup-api-ref) in your application.
## Tutorials
For a step-by-step integration, see the [Payment Method Helper tutorials](https://www.chargebee.com/tutorials/topics/payment-method-helper/).
## Card payments
### 3DS handler
The 3DS handler object created using the [`load3DSHandler()`](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#load3dshandler) method provides methods to manage 3D Secure (3DS) authentication flows for card payments.
#### `setPaymentIntent()`
Sets the payment intent for the 3DS handler. The `paymentIntent` must be created on your server side using the [Create payment intent API](https://apidocs.chargebee.com/docs/api/payment_intents/create-a-payment-intent). The payment intent contains information about the payment gateway and the amount to be charged. If you're using the payment gateway's JavaScript library alongside this module, you pass the gateway JavaScript instance to this method.
##### Syntax
```js
threeDSHandler.setPaymentIntent(paymentIntent, options);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
- `options` (Object)
- `stripe` (Object) Stripe.js instance. Learn more about creating an instance of the Stripe object.
- `braintree` (Object) Braintree.js client instance
- `adyen` (Object) Adyen.js checkout instance
##### Return value
None.
##### Examples
```js
chargebee.load3DSHandler().then(threeDSHandler => {
// Set the payment intent.
threeDSHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
```
```js
chargebee.load3DSHandler().then(threeDSHandler => {
// In case you are using Adyen web components, you can pass the Adyen instance to this method.
threeDSHandler.setPaymentIntent(paymentIntent, {
adyen: adyenCheckoutInstance,
});
});
```
#### `updatePaymentIntent()`
Updates the payment intent attached to the 3DS handler. Use this method when the payment amount changes due to user interaction (for example, applying a discount coupon or adding tax). Make an API call to your server to [update the payment intent](https://apidocs.chargebee.com/docs/api/payment_intents/update-a-payment-intent), then pass the updated payment intent to this method.
##### Syntax
```js
threeDSHandler.updatePaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
let threeDSHandler;
chargebee.load3DSHandler().then(threeDSPaymentHandler => {
threeDSHandler = threeDSPaymentHandler;
// Set the payment intent.
threeDSHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
function updatePaymentIntent() {
// Make an API call to your server to update the payment intent
// using Chargebee's Update payment intent API.
return updateIntentApi().then(updatedIntent => {
return updatedIntent;
});
}
function onApplyCoupon() {
// Handle estimate amount change.
updatePaymentIntent().then(paymentIntent => {
// Set the updated payment intent to 3DS handler.
threeDSHandler.updatePaymentIntent(paymentIntent);
});
}
function onSubmit() {
return threeDSHandler.handleCardPayment();
}
```
#### `getPaymentIntent()`
Retrieves the payment intent object currently attached to the 3DS handler instance.
##### Syntax
```js
threeDSHandler.getPaymentIntent();
```
##### Return value
Returns the payment intent object.
#### `handleCardPayment()`
Initiates the 3DS flow for the card details entered.
> **Prerequisites**
>
> - Payment gateway settings and the card issuing bank must be configured to support 3DS.
> - [`setPaymentIntent()`](#setpaymentintent) must be called before calling handleCardPayment().
After successful 3DS authorization, the payment intent is marked as authorized. The payment intent ID can then be used to [create subscriptions](https://apidocs.chargebee.com/docs/api/subscriptions/create-subscription-for-items) or [create `card` payment sources](https://apidocs.chargebee.com/docs/api/payment_sources/create-using-payment-intent) for the customer.
> **Cross-currency transactions**
>
> For cross-currency transactions from INR to another currency (for example, USD payment using an INR card), the following values are required:
>
> - `plan`: Name or description of the product.
> - `customerBillingAddress`: Customer billing address.
> - `shippingAddress`: Shipping address.
##### Syntax
```js
threeDSHandler.handleCardPayment(paymentInfo, callbacks);
```
##### Parameters
**Parameters**
- `paymentInfo` (Object) Card details collected or payment tokens can be passed here. Additionally, billing details can also be passed.
- `element` (Object) Instance of gateway card component used can be passed here. For example: Adyen web components.
- `card` (Object) Card details.
- `number` (String, required) Credit card number.
- `expiryMonth` (String, required) Card expiration month.
- `expiryYear` (String, required) Card expiration year.
- `cvv` (String, required) CVV of card.
- `preferredScheme` (String) Customer's preferred scheme for co-branded cards.
- `firstName` (String, required if Worldpay gateway is used) First name of the customer.
- `lastName` (String) Last name of the customer.
- `tokenizer` (Function) A function that returns a gateway's card temp token.
- `cbToken` (String) Chargebee's temporary token.
- `additionalData` (Object) Additional information that needs to be passed for improving the chances of frictionless checkout flow.
- `plan` (String) Plan name
- `billingAddress` (Object) Card Billing Address
- `firstName` (String, required if Worldpay gateway is used) First name associated with billing address
- `lastName` (String) Last name associated with billing address
- `phone` (String) Phone number associated with the billing address
- `addressLine1` (String) Billing address line 1 (eg. number, street, etc).
- `addressLine2` (String) Billing address line 2 (eg. suite, apt #, etc.).
- `addressLine3` (String) Billing address line 3 (eg. suite, apt #, etc).
- `city` (String) City or locality name
- `state` (String) State
- `stateCode` (String) 2 letter code for US states or equivalent
- `countryCode` (String) 2 letter country code
- `zip` (String) Zip code or postal code
- `customerBillingAddress` (Object) Customer's Billing Address
- `firstName` (String, required if Worldpay gateway is used) First name associated with billing address
- `lastName` (String) Last name associated with billing address
- `phone` (String) Phone number associated with the billing address
- `addressLine1` (String) Billing address line 1 (eg. number, street, etc).
- `addressLine2` (String) Billing address line 2 (eg. suite, apt #, etc.).
- `addressLine3` (String) Billing address line 3 (eg. suite, apt #, etc).
- `city` (String) City or locality name
- `state` (String) State
- `stateCode` (String) 2 letter code for US states or equivalent
- `countryCode` (String) 2 letter country code
- `zip` (String) Zip code or postal code
- `shippingAddress` (Object) Shipping Address
- `firstName` (String, required if Worldpay gateway is used) First name associated with shipping address
- `lastName` (String) Last name associated with shipping address
- `phone` (String) Phone number associated with the shipping address
- `addressLine1` (String) Shipping address line 1 (eg. number, street, etc).
- `addressLine2` (String) Shipping address line 2 (eg. suite, apt #, etc.).
- `addressLine3` (String) Shipping address line 3 (eg. suite, apt #, etc).
- `city` (String) City or locality name
- `state` (String) State
- `stateCode` (String) 2 letter code for US states or equivalent
- `countryCode` (String) 2 letter country code
- `zip` (String) Zip code or postal code
- `email` (String, required if Worldpay gateway is used) Mail ID of the customer.
- `phone` (String) Phone number
- `mandate` (Object) Enabling this parameter will request Additional Factor Authentication (AFA) and mandate setup to the gateway. Applicable only for cards issued in India.
- `requireMandate` (Boolean) Set the value as `true` to create a mandate. The default value is `false`.
- `description` (String) Send the plan name in this description. This plan name will appear on the AFA page.
- `document` (Object, required if EBANX or dLocal gateway is used) The document details (e.g., national IDs or passports) used for document verification and payment processing by EBANX and dLocal.
- `number` (String) The document number.
- `type` (String) The type of document. Refer to the EBANX table or dLocal table below for the possible values.
- `callbacks` (Object) Callbacks to be used for this operation.
- `change` (Function) This function will be called during each step of 3DS flow
- `success` (Function) This function will be called if 3DS Authorization is successful
- `error` (Function) This function will be called if 3DS Authorization has failed
- `challenge` (Function) When this callback is implemented, the transaction will proceed in a redirect workflow if supported by the gateway. This callback function will be called with a redirect URL when the 3DS transaction requires a challenge. This workflow is currently supported by Adyen, Braintree and Stripe payment gateways.
##### Return value
Returns a promise that resolves to an authorized payment intent object.
##### Example
```js
let threeDSHandler;
chargebee.load3DSHandler().then(threeDSPaymentHandler => {
threeDSHandler = threeDSPaymentHandler;
// Set the payment intent
threeDSHandler.setPaymentIntent(paymentIntent);
// Additional logic here
});
function onSubmit() {
return threeDSHandler.handleCardPayment(
{
card: {
firstName: "First Name",
lastName: "Last Name",
number: "xxxx xxxx xxxx xxxx",
cvv: "",
expiryMonth: "10",
expiryYear: "2019",
},
additionalData: {
// You can pass additional information to improve the chances of frictionless authorization.
billingAddress: {
firstName: "",
lastName: "",
phone: "",
addressLine1: "",
addressLine2: "",
addressLine3: "",
city: "",
state: "",
stateCode: "",
countryCode: "",
zip: "",
},
email: "john@example.com",
phone: "",
},
},
{
change: function (intent) {
// Triggers on each step transition.
},
success: function (intent) {
// Triggers when card is 3DS authorized.
},
error: function (intent, error) {
// Triggers when 3DS authorization fails.
},
}
).then(authorizedPaymentIntent => {
// Make an API call to your server to use the authorized payment intent
// to create a subscription.
return createSubscriptionApi(authorizedPaymentIntent.id);
});
}
```
#### `cancel()`
Cancels an ongoing 3DS flow. The transaction is canceled with the gateway, and the payment attempt is marked as refused with an authentication failed status.
An error is returned if no payment intent is set or if there is no ongoing 3DS transaction.
This method is primarily used with the `challenge` callback implementation, where the 3DS redirection URL is provided.
Call this method after invoking `handleCardPayment()` while a 3DS transaction is in progress. This method does not cancel an authorized payment intent.
##### Syntax
```js
threeDSHandler.cancel();
```
##### Return value
Returns a promise.
##### Example
```js
let threeDSHandler = chargebee.create3DSHandler();
threeDSHandler
.handleCardPayment(
{
card: {
firstName: "John",
lastName: "Doe",
number: "4111111111111111",
cvv: "123",
expiryMonth: "12",
expiryYear: "2025",
},
},
{
challenge: (redirect_url) => {
// Open this redirect URL in a popup window.
},
}
)
.then((intent) => {
console.log("Payment authorized successfully.");
})
.catch((error) => {
console.error("Payment authorization failed:", error);
});
function onCloseWindow() {
threeDSHandler.cancel();
}
```
### Bancontact payment handler
The [Bancontact payment handler](https://www.chargebee.com/tutorials/bancontact-integration-with-chargebee-js/) integrates the Bancontact payment method on your site or application.
The [Bancontact payment handler object](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#load-modulename) created using the `load()` method provides methods to manage Bancontact payment flows.
#### `getPaymentIntent()`
Retrieves the payment intent attached to the payment method handler object.
##### Syntax
```js
bancontactHandler.getPaymentIntent();
```
##### Return value
Returns the payment intent object.
#### `setPaymentIntent()`
Attaches a payment intent to the payment method handler object. The payment intent contains information about the gateway and the payment.
##### Syntax
```js
bancontactHandler.setPaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
let bancontactHandler;
chargebee.load('bancontact').then(_bancontactHandler => {
bancontactHandler = _bancontactHandler;
// Set the payment intent
bancontactHandler.setPaymentIntent(paymentIntent);
// Additional logic here
});
```
#### `updatePaymentIntent()`
Updates the payment intent attached to the payment method handler object. Use this method after making changes to the payment intent.
##### Syntax
```js
bancontactHandler.updatePaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
let bancontactHandler;
chargebee.load('bancontact').then(_bancontactHandler => {
bancontactHandler = _bancontactHandler;
// Set the payment intent.
bancontactHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
function onApplyCoupon() {
// Make an API call to your server to update the payment intent with the new amount.
updatePaymentIntentApi().then(updatedPaymentIntent => {
// Set the updated payment intent.
bancontactHandler.updatePaymentIntent(updatedPaymentIntent);
});
}
```
#### `handlePayment()`
Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.
##### Syntax
```js
bancontactHandler.handlePayment(paymentInfo, callbacks);
```
##### Parameters
**Parameters**
- `paymentInfo` (Object) Transaction-related information. The fields to pass depend on the gateway that processes the payment.
- `element` (Object, required if using Adyen and raw card details aren't passed in card) The Adyen card component instance that collects the card details. Use this instead of `card` to avoid handling raw card details on your page.
- `card` (Object, required if using Adyen and the Adyen card component isn't passed in element) Raw card details collected on your page. Passing raw card details requires PCI DSS compliance; use `element` instead where possible.
- `number` (String, required) Card number.
- `expiryMonth` (String, required) Card expiration month.
- `expiryYear` (String, required) Card expiration year.
- `firstName` (String) Cardholder's first name.
- `lastName` (String) Cardholder's last name.
- `cardBillingAddress` (Object) Billing address associated with the card. Sent to Adyen along with the card details.
- `firstName` (String) First name associated with the address.
- `lastName` (String) Last name associated with the address.
- `phone` (String) Phone number associated with the address.
- `addressLine1` (String) Address line 1.
- `addressLine2` (String) Address line 2.
- `addressLine3` (String) Address line 3.
- `city` (String) City.
- `state` (String) State name.
- `stateCode` (String) Two-letter state code.
- `countryCode` (String) Two-letter ISO 3166-1 alpha-2 country code.
- `zip` (String) Postal code.
- `userName` (String, required if using Checkout.com, Mollie, or Stripe) Full name of the payer, used as the account holder name on the payment. Required by Checkout.com, Mollie, and Stripe. Because Smart routing can select any of the configured gateways, provide this field for every Bancontact payment.
- `userEmail` (String, required if using Checkout.com or Stripe) Email address of the payer. Required by Checkout.com and Stripe. Mollie also sends this address to the gateway when you provide it.
- `country` (String, required if using Checkout.com) Two-letter ISO 3166-1 alpha-2 country code of the payer.
- `currencyCode` (String) Currency code of the payment currency. If not provided, currency code from Payment Intent will be used.
- `amount` (String) Total amount to be paid. If not provided, amount value from Payment Intent will be used.
- `retainPaymentMethod` (Boolean) Whether Stripe retains the payment method for future payments. Applies to Stripe only.
- `customer` (Object) Details of the payer.
- `firstName` (String) First name of the payer. Sent to Checkout.com only.
- `lastName` (String) Last name of the payer. Sent to Checkout.com only.
- `email` (String) Email address of the payer. Sent to Adyen and Checkout.com.
- `company` (String) Company name of the payer. Sent to Checkout.com only.
- `billingAddress` (Object) Billing address of the payer. Sent to Checkout.com only.
- `firstName` (String) First name associated with the address.
- `lastName` (String) Last name associated with the address.
- `phone` (String) Phone number associated with the address.
- `addressLine1` (String) Address line 1.
- `addressLine2` (String) Address line 2.
- `addressLine3` (String) Address line 3.
- `city` (String) City.
- `state` (String) State name.
- `stateCode` (String) Two-letter state code.
- `countryCode` (String) Two-letter ISO 3166-1 alpha-2 country code.
- `zip` (String) Postal code.
- `callbacks` (Object) Callback that can be passed during the payment process.
- `error` (Function) Triggers when there is an error during the transaction.
- `success` (Function) Triggers when transaction is successfully completed.
- `change` (Function) Triggers when there is a change in the transaction state.
The `paymentInfo` fields to pass depend on the gateway that processes the payment. Because [Smart routing](https://www.chargebee.com/docs/payments/2.0/payment-gateways-and-configuration/gateway_settings#smart-routing) can select any of your configured gateways, pass the fields required by every gateway you have enabled for Bancontact. For Adyen, pass either `element` or `card`; the payment fails if you pass neither.
##### Return value
Returns a promise that resolves to a payment intent object after successful payment authorization.
##### Example
**Details**
**For Adyen Card Components**
```js
bancontactHandler.handlePayment(
{
element: cardElement,
},
{
success: function (paymentIntent) {
console.log("Payment successful: ", paymentIntent);
},
error: function (error) {
console.log("Payment failed: ", error);
},
}
);
```
**For raw card details**
```js
bancontactHandler.handlePayment(
{
card: {
number: "6703444444444449",
expiryMonth: "12",
expiryYear: "2025",
},
},
{
success: function (paymentIntent) {
console.log("Payment successful: ", paymentIntent);
},
error: function (error) {
console.log("Payment failed:", error);
},
}
);
```
## Wallet-based payments
### PayPal payment handler
The [PayPal payment handler](https://www.chargebee.com/tutorials/paypal-integration-with-chargebee-js/) integrates the PayPal payment method on your site or application.
The PayPal payment handler object can be created by [loading](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#load-modulename) the payment method using a Chargebee instance.
#### `getPaymentIntent()`
Retrieves the payment intent attached to the payment method handler object.
##### Syntax
```js
payPalHandler.getPaymentIntent();
```
##### Return value
Returns the payment intent object.
##### Example
```js
let paypalHandler;
chargebee.load('paypal').then(_paypalHandler => {
paypalHandler = _paypalHandler;
// Set the payment intent
paypalHandler.setPaymentIntent(paymentIntent);
// Additional logic here
});
function onClick() {
paypalHandler.getPaymentIntent();
}
```
#### `setPaymentIntent()`
Sets the payment intent for payment processing.
##### Syntax
```js
paypalHandler.setPaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
let paypalHandler;
chargebee.load('paypal').then(_paypalHandler => {
paypalHandler = _paypalHandler;
// Set the payment intent.
paypalHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
```
#### `updatePaymentIntent()`
Updates the payment intent attached to the payment method handler object.
##### Syntax
```js
paypalHandler.updatePaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
let paypalHandler;
chargebee.load('paypal').then(_paypalHandler => {
paypalHandler = _paypalHandler;
// Set the payment intent.
paypalHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
function onUpdateCart() {
// Make an API call to your server to update the payment intent.
updatePaymentIntent().then(paymentIntent => {
// Set the updated payment intent.
paypalHandler.updatePaymentIntent(paymentIntent);
});
}
```
#### `mountPaymentButton()`
Mounts the PayPal payment button to the DOM.
##### Syntax
```js
paypalHandler.mountPaymentButton(selector, options);
```
##### Parameters
**Parameters**
- `selector` (String, required) A valid CSS Selector for the element where the payment button should be mounted.
- `options` (Object) Options for PayPal button.
- `locale` (String) The locale code of the country and language to display on the button.Learn more.
- `style` (Object) To define the color, shape, size, and label of the button, use the button style parameters. Learn more.
- `layout` (String) Determines if the buttons are stacked horizontally or vertically. Allowed: `horizontal`, `vertical`.
- `height` (Integer) Height of the button in `px`. Allowed: `25 to 55 (Note: The button's default maximum height is 55px)`.
- `size` (String) Size of the button. Allowed: `small`, `medium`, `large`, `responsive`.
- `color` (String) Color of the button. Allowed: `gold`, `blue`, `silver`, `white`, `black`.
- `shape` (String) Shape of the button. Allowed: `pill`, `rect`.
- `label` (String) Label option for the button. Allowed: `checkout`, `credit`, `pay`, `buynow`, `paypal`, `installment`.
- `installmentperiod` (String) Set installmentperiod to set the number of payments during the installment period if you have selected installment as label.
- `tagline` (Boolean) tagline to be enabled or not for the button.
- `funding` (Object) Displays or hides the specified funding methods.Learn more.
- `allowed` (String[]) Display the funding methods if it is eligible.
- `disallowed` (String[]) Hide funding methods.
##### Return value
Returns a promise that resolves after successfully mounting the PayPal button.
##### Example
```js
let paypalHandler;
chargebee.load("paypal").then((_paypalHandler) => {
paypalHandler = _paypalHandler;
// Set the payment intent.
paypalHandler.setPaymentIntent(paymentIntent);
// Mount the button to the DOM.
return paypalHandler.mountPaymentButton("#button-holder");
});
```
#### `handlePayment()`
Waits for payment processing to complete the transaction.
##### Syntax
```js
paypalHandler.handlePayment(callbacks);
```
##### Parameters
**Parameters**
- `callbacks` (Object) Callback that can be passed during the payment process.
- `error` (Function) Triggers when there is an error during the transaction.
- `success` (Function) Triggers when transaction is successfully completed.
- `change` (Function) Triggers when there is a change in the transaction state.
- `cancel` (Function) Triggers when the transaction is canceled.Note: `cancel` callback is applicable only for Adyen, Braintree, and PayPal Express Checkout gateways.
##### Return value
Returns a promise that resolves to a payment intent object after successful payment authorization.
##### Example
```js
let paypalHandler;
chargebee
.load("paypal")
.then((_paypalHandler) => {
paypalHandler = _paypalHandler;
// Set the payment intent.
paypalHandler.setPaymentIntent(paymentIntent);
// Mount the button to the DOM.
return paypalHandler.mountPaymentButton("#button-holder");
})
// Wait for payment authorization to complete.
.then(() => paypalHandler.handlePayment())
.then((authorizedPaymentIntent) => {
// Use the authorized payment intent to create a subscription.
createSubscription(authorizedPaymentIntent);
});
```
### Google Pay payment handler
The [Google Pay payment handler](https://www.chargebee.com/tutorials/google-pay-integration-with-chargebee-js/) integrates the Google Pay payment method on your site or application.
#### `getPaymentIntent()`
Retrieves the payment intent attached to the Google Pay payment handler.
##### Syntax
```js
googlePayHandler.getPaymentIntent();
```
##### Return value
Returns the payment intent object.
#### `setPaymentIntent()`
Sets the payment intent for payment processing.
##### Syntax
```js
googlePayHandler.setPaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
chargebee.load('google-pay').then(googlePayHandler => {
googlePayHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
```
#### `updatePaymentIntent()`
Updates the payment intent attached to the payment method handler object.
##### Syntax
```js
googlePayHandler.updatePaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
let googlePayHandler;
chargebee.load('google-pay').then(_googlePayHandler => {
googlePayHandler = _googlePayHandler;
// Set the payment intent.
googlePayHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
function onUpdateCart() {
// Make an API call to your server to update the payment intent.
updatePaymentIntent().then(paymentIntent => {
// Set the updated payment intent.
googlePayHandler.updatePaymentIntent(paymentIntent);
});
}
```
#### `mountPaymentButton()`
Mounts the Google Pay button to the DOM.
##### Syntax
```js
googlePayHandler.mountPaymentButton(selector, buttonOptions, paymentOptions);
```
##### Parameters
**Parameters**
- `selector` (String, required) A valid CSS Selector for the element where the payment button should be mounted.
- `buttonOptions` (Object) Button options available for customizing Google Pay button. Learn more about supported button options for Google Pay.
- `buttonColor` (String) Color of the Google Pay button. Allowed: `default`, `black`, `white`.
- `buttonType` (String) Type of the Google Pay button. Allowed: `long`, `short`, `book`, `buy`, `checkout`, `donate`, `order`, `pay`, `plain`, `subscribe`.
- `buttonSizeMode` (String) Button size options. Allowed: `static`, `fill`.
- `buttonLocale` (String) Locale options for the Google Pay Button.
- `paymentOptions` (Object) Config for Google Pay.
- `requestPayerEmail` (Boolean) Set this flag to true, to return payer email after payment authorization.
- `requestBillingAddress` (Boolean) Set this flag to true, to return billing address after payment authorization.
- `requestShippingAddress` (Boolean) Set this flag to true, to return shipping address after payment authorization.
##### Return value
Returns a promise that resolves after successfully mounting the payment button.
##### Example
```js
chargebee.load("google-pay").then((googlePayHandler) => {
// Set the payment intent.
googlePayHandler.setPaymentIntent(paymentIntent);
return googlePayHandler.mountPaymentButton("#button-holder");
});
```
#### `handlePayment()`
Waits for payment authorization to complete.
##### Syntax
```js
googlePayHandler.handlePayment(callbacks);
```
##### Parameters
**Parameters**
- `callbacks` (Object) Callback that can be passed during the payment process.
- `error` (Function) Triggers when there is an error during the transaction.
- `success` (Function) Triggers when transaction is successfully completed.
- `change` (Function) Triggers when there is a change in the transaction state.
##### Return value
Returns a promise that resolves to a payment intent object after successful payment authorization.
##### Example
```js
let googlePayHandler;
chargebee
.load("google-pay")
.then((_googlePayHandler) => {
googlePayHandler = _googlePayHandler;
// Set the payment intent.
googlePayHandler.setPaymentIntent(paymentIntent);
return googlePayHandler.mountPaymentButton("#button-holder");
})
.then(() => googlePayHandler.handlePayment())
.then((paymentIntent) => {
// Use payment intent to create a subscription
});
```
### Apple Pay payment handler
The [Apple Pay payment handler](https://www.chargebee.com/tutorials/apple-pay-integration-with-chargebee-js/) integrates the Apple Pay payment method on your site or application.
#### `canMakePayments()`
Checks whether the device supports the Apple Pay payment method.
##### Syntax
```js
applePayHandler.canMakePayments();
```
##### Return value
Returns a boolean value indicating Apple Pay support.
##### Example
```js
const isApplePayAvailable = applePayHandler.canMakePayments();
```
#### `applePayCapabilities()`
Checks whether the device supports Apple Pay and whether the user's Apple Wallet contains an active payment method eligible for web payments.
Call this method before calling [`mountPaymentButton()`](#mountpaymentbutton-2) to determine if Apple Pay can be used on the current device.
> **Gateway support**
>
> Pass `merchantIdentifier` for every gateway except [Adyen](https://www.chargebee.com/docs/payments/2.0/payment-gateways-and-configuration/adyen). If you omit it for any other gateway, the returned promise rejects with a gateway support error.
##### Syntax
```js
applePayHandler.applePayCapabilities(merchantIdentifier);
```
##### Parameters
**Parameters**
- `merchantIdentifier` (String, required if the gateway is not Adyen.) Your Apple merchant identifier. Optional for the Adyen gateway. For all other gateways, the returned promise rejects when this parameter is not passed.
##### Return value
Returns a promise that resolves to a [`PaymentCredentialStatusResponse`](https://developer.apple.com/documentation/applepayontheweb/paymentcredentialstatusresponse) object.
##### Example
```js
applePayHandler.applePayCapabilities("YOUR_APPLE_PAY_MERCHANT_ID").then(capabilities => {
switch (capabilities.paymentCredentialStatus) {
case "paymentCredentialsAvailable":
// Display an Apple Pay button and offer Apple Pay as the payment option.
break;
case "paymentCredentialStatusUnknown":
// Display an Apple Pay button and offer Apple Pay as a possible payment option.
break;
case "paymentCredentialsUnavailable":
// Offer Apple Pay as a payment option, but don't make it the default payment option.
break;
case "applePayUnsupported":
// Don't display an Apple Pay button or offer Apple Pay as a payment option.
break;
}
});
```
#### `mountPaymentButton()`
Mounts the Apple Pay button to the DOM.
> **Note**
>
> Before calling this method, check whether the device supports Apple Pay using one of the following methods:
> - [`canMakePayments()`](#canmakepayments) for a boolean check.
> - [`applePayCapabilities()`](#applepaycapabilities) for the status of the customer's payment credentials.
##### Syntax
```js
applePayHandler.mountPaymentButton(selector, options);
```
##### Parameters
**Parameters**
- `selector` (String, required) A valid CSS Selector for the element where the payment button should be mounted.
- `options` (Object) Other options and button customizations.
- `buttonType` (String) Button type as provided by Apple. Learn more.
- `buttonColor` (String) Button color as provided by Apple. Learn more. Allowed: `black`, `white`.
- `locale` (String)
- `requestPayerName` (Boolean) If `true`, the payer's name is included under `paymentIntent.payer_info`, in the resolved promise returned by `handlePayment()`. For the Stripe gateway, the payer's billing address is also included.
- `requestPayerEmail` (Boolean) If `true`, the payer's email address is included under `paymentIntent.payer_info`, in the resolved promise returned by `handlePayment()`.
- `requestPayerPhone` (Boolean) If `true`, the payer's phone number is included under `paymentIntent.payer_info`, in the resolved promise returned by `handlePayment()`.
- `requestBilling` (Boolean) If `true`, the payer's billing address is included under `paymentIntent.payer_info`, in the resolved promise returned by `handlePayment()`.
- `requestShipping` (Boolean) If `true`, the payer's shipping address is included under `paymentIntent.payer_info`, in the resolved promise returned by `handlePayment()`.
- `recurringPaymentRequest` (Object) Represents a request to set up a recurring payment using Apple Pay merchant token (MPAN). The schema must match ApplePayRecurringPaymentRequest.
##### Return value
Returns a promise that resolves after successfully mounting the payment button.
##### Example
```js
applePayHandler.mountPaymentButton("#applepay-button", {
locale: "en_US",
buttonColor: "black",
buttonType: "plain",
recurringPaymentRequest: {
paymentDescription: "Premium Membership Subscription",
regularBilling: {
label: "Monthly Subscription",
amount: "9.99"
},
trialBilling: {
label: "Free Trial - First Month",
amount: "0.00"
},
billingAgreement: "You authorize monthly charges for the Premium Membership.",
managementURL: "https://example.com/account/subscription",
tokenNotificationURL: "https://example.com/api/payment/token-notify"
}
});
```
#### `handlePayment()`
Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.
##### Syntax
```js
applePayHandler.handlePayment(callbacks);
```
##### Parameters
**Parameters**
- `callbacks` (Object) Callbacks that can be passed during the payment process.
- `error` (Function) Triggers when there is an error during the transaction.
- `success` (Function) Triggers when transaction is successfully completed.
- `response` Object containing `paymentIntent`, `shippingAddress` and `billingAddress`
- `change` (Function) Triggers when there is a change in the transaction state.
- `click` (Function) Triggers when the user clicks the button to initiate the transaction.
##### Return value
Returns a promise that resolves to a payment intent object after successful payment authorization.
##### Example
```js
applePayHandler
.handlePayment()
.then((paymentIntent) => {
console.log("Payment successful", paymentIntent);
// Use the authorized payment intent to create a subscription.
})
.catch((error) => {
console.log("Payment failed", error);
});
```
### Payconiq by Bancontact handler
The [Payconiq by Bancontact payment handler](https://www.chargebee.com/tutorials/payconiq-by-bancontact-integration-with-chargebee-js/) integrates the Payconiq by Bancontact payment method on your site or application.
The Payconiq by Bancontact payment method handler object can be created using the `load()` [method](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#load-modulename) of a Chargebee instance.
#### `handlePayment()`
Initiates the payment process by opening a modal popup overlay that displays a QR code for the customer to scan with their Payconiq app.
The modal stays open while the customer scans the QR code and completes the payment. It closes automatically when authorization completes.
##### Syntax
```js
chargebee.handlePayment("payconiq_by_bancontact", options);
```
##### Parameters
**Parameters**
- `paymentIntent` (Function) Function that returns a payment intent object created on your server side.
- `renderInfo` (Object) Configuration options for customizing the Payconiq by Bancontact payment interface.
- `heading` (String) Heading text displayed to the user. Default: `Scan QR code`.
- `timerLabel` (String) Timer label text. Include `{time}` where you would like the timer to appear in the text. Default: `This QR code is valid for {time}`.
- `timerDurationSeconds` (Number) Duration of the timer in seconds. Default: `900` (15 minutes).
- `buttonText` (String) Text displayed on the payment button. Default: `Pay with Payconiq App`.
- `callbacks` (Object) Callback that can be passed during the payment process.
- `error` (Function) Triggers when there is an error during the transaction.
- `success` (Function) Triggers when transaction is successfully completed.
- `change` (Function) Triggers when there is a change in the transaction state.
##### Return value
Returns a promise that resolves to a payment intent object.
> **Important**
>
> The promise resolves early with a payment intent that has status `in_progress` (not `authorized`). The promise resolves as soon as the modal opens and the QR code is displayed, before the customer completes the payment. You must poll for authorization before creating a subscription. See the [Payconiq by Bancontact tutorial](https://www.chargebee.com/tutorials/payconiq-by-bancontact-integration-with-chargebee-js/#step-3-monitor-payment-status) for details.
##### Example
```js
chargebee.load("payconiq_by_bancontact").then(() => {
chargebee.handlePayment("payconiq_by_bancontact", {
paymentIntent: () => {
return createPaymentIntent();
},
renderInfo: {
heading: "Scan QR code.",
timerLabel: "This QR code is valid for {time}.", // Timer will be reflected in place of {time}.
timerDurationSeconds: 15 * 60, // 15 minutes.
buttonText: "Continue to Payconiq by Bancontact.",
}
}).then(intent => {
// Payment intent status is `in_progress` at this point - customer needs to scan QR code.
// Poll for authorization before creating subscription.
return waitForAuthorization(intent.id).then(authorizedIntent => {
return createSubscription(authorizedIntent.id);
});
}).catch(error => {
console.error('Payment failed:', error);
});
});
function createSubscription(paymentIntentId) {
return fetch('/subscriptions', {
method: 'POST',
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
paymentIntentId: paymentIntentId,
plan_id: 'pro_plan',
plan_quantity: 1,
billingAddress: {
// Add billing address details.
},
customer: {
// Add customer details.
}
})
}).then(response => response.json());
}
```
### Venmo handler
The [Venmo payment handler](https://www.chargebee.com/tutorials/venmo-integration-with-chargebee-js/) integrates the Venmo payment method on your site or application.
The Venmo payment method handler object can be created using the `load()` [method](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#load-modulename) of a Chargebee instance.
#### `getPaymentIntent()`
Retrieves the payment intent attached to the payment method handler object.
> **Retrieve billing address from Venmo**
>
> When using the [Braintree payment gateway for Venmo payments](https://www.chargebee.com/docs/payments/2.0/venmo-braintree.html), the `payment_intent` object returned by default does not include `billing_address`. This information may be required for tasks such as calculating sales tax. To ensure that `payer_info.billing_address` is included in the `payment_intent` object, [enable Enriched Customer Data (ECD)](https://developer.paypal.com/braintree/articles/guides/payment-methods/venmo#enriched-customer-data) in the Braintree Control Panel. Once enabled, Chargebee automatically includes this customer detail.
##### Syntax
```js
venmoHandler.getPaymentIntent();
```
##### Return value
Returns the payment intent object.
##### Example
```js
let venmoHandler;
chargebee.load('venmo').then(_venmoHandler => {
venmoHandler = _venmoHandler;
// Set the payment intent.
venmoHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
function onClick() {
venmoHandler.getPaymentIntent();
}
```
#### `setPaymentIntent()`
Associates a payment intent with the Venmo payment method handler for payment processing.
##### Syntax
```js
venmoHandler.setPaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
let venmoHandler;
chargebee.load('venmo').then(_venmoHandler => {
venmoHandler = _venmoHandler;
// Set the payment intent
venmoHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
```
#### `updatePaymentIntent()`
Updates the payment intent associated with the Venmo payment method handler.
##### Syntax
```js
venmoHandler.updatePaymentIntent(paymentIntent);
```
##### Parameters
**Parameters**
- `paymentIntent` (Object, required) Payment Intent object
##### Return value
None.
##### Example
```js
let venmoHandler;
chargebee.load('venmo').then(_venmoHandler => {
venmoHandler = _venmoHandler;
// Set the payment intent.
venmoHandler.setPaymentIntent(paymentIntent);
// Additional logic here.
});
function onUpdateCart() {
// Make an API call to your server to update the payment intent.
updatePaymentIntent().then(paymentIntent => {
// Set the updated payment intent.
venmoHandler.updatePaymentIntent(paymentIntent);
});
}
```
#### `mountPaymentButton()`
Mounts the Venmo payment button to the DOM.
##### Syntax
```js
venmoHandler.mountPaymentButton(selector);
```
##### Parameters
**Parameters**
- `selector` (String, required) A valid CSS Selector for the element where the payment button should be mounted.
##### Return value
Returns a promise that resolves after successfully mounting the Venmo payment button.
##### Example
```js
let venmoHandler;
chargebee.load("venmo").then((_venmoHandler) => {
venmoHandler = _venmoHandler;
// Set the payment intent.
venmoHandler.setPaymentIntent(paymentIntent);
// Mount the button to the DOM.
return venmoHandler.mountPaymentButton("#button-holder");
});
```
#### `handlePayment()`
Waits for payment processing to complete the transaction.
##### Syntax
```js
venmoHandler.handlePayment(callbacks);
```
##### Parameters
**Parameters**
- `callbacks` (Object) Callback that can be passed during the payment process.
- `error` (Function) Triggers when there is an error during the transaction.
- `success` (Function) Triggers when transaction is successfully completed.
- `change` (Function) Triggers when there is a change in the transaction state.
##### Return value
Returns a promise that resolves to a payment intent object after successful payment authorization.
##### Example
```js
let venmoHandler;
chargebee
.load("venmo")
.then((_venmoHandler) => {
venmoHandler = _venmoHandler;
// Set the payment intent.
venmoHandler.setPaymentIntent(paymentIntent);
// Mount the button to the DOM.
return venmoHandler.mountPaymentButton("#button-holder");
})
// Wait for payment authorization to complete.
.then(() => venmoHandler.handlePayment())
.then((authorizedPaymentIntent) => {
// Use the authorized payment intent to create a subscription.
createSubscription(authorizedPaymentIntent);
});
```
## Bank-based payments
### Initiating bank payments
All bank-based payment method transactions are initiated using the `chargebee.handlePayment()` method.
> **Note**
>
> This workflow is common for all Chargebee.js-supported bank payment methods.
Supported payment methods:
- iDEAL
- SOFORT
- dotpay
- Netbanking e-Mandate
- Direct debit
#### `handlePayment()`
Initiates the payment process. This method should be invoked from Chargebee instance object. Upon initiation, user maybe redirected to the bank's webpage for authorizing the payment.
##### Syntax
```js
cbInstance.handlePayment(paymentMethodType, paymentOptions);
```
##### Parameter
- `paymentMethodType` (Enum, required) Name of the payment method type. Allowed: `ideal`, `sofort`, `bancontact`, `dotpay`, `netbanking_emandates`, `klarna_pay_now`, `direct_debit`.
- `paymentOptions` (Object) Options for the payment method type.
- `paymentIntent` (Function, required) Pass a function that resolves to a Payment Intent object. Learn more object.
- `paymentInfo` (Object) Payment details and additional information.
- `element` (Object, required if Using card component) Instance of gateway's hosted card fields can be passed here. For example: Adyen web components, Stripe elements.
- `card` (Object, required if Using raw card details) Card details.
- `number` (String, required) Credit card number.
- `expiryMonth` (String, required) Card expiration month.
- `expiryYear` (String, required) Card expiration year.
- `cvv` (String, required) Card CVV code.
- `firstName` (String, required if Worldpay gateway is used.) Cardholder's first name.
- `lastName` (String) Cardholder's last name.
- `tokenizer` (Function, required if Using gateway tokenization.) A function that returns a gateway's card temporary token.
- `cbToken` (String, required if Using Chargebee's Components & Fields) Chargebee's temporary token.
- `currencyCode` (String) Currency code of the payment currency. If not provided, currency code from Payment Intent will be used.
- `amount` (String) Total amount to be paid. If not provided, amount value from Payment Intent will be used.
- `issuerBank` (String, required if Using iDEAL payment) The bank to which the user has to be redirected for authorization.
- `userName` (String, required if using Stripe for iDEAL or SOFORT) Full name of the payer. Required for Stripe iDEAL and Stripe SOFORT. For iDEAL, Stripe uses it as the account holder name on the SEPA Direct Debit mandate; it must match the name on the payer's bank account exactly, or the payment can fail. Because Smart routing can select any of these gateways, provide this field for every iDEAL or SOFORT payment.
- `userEmail` (String, required if using Stripe for iDEAL or SOFORT) Email address of the payer. Required for Stripe iDEAL and Stripe SOFORT. For iDEAL, Stripe uses it to create the SEPA Direct Debit mandate. Because Smart routing can select any of these gateways, provide this field for every iDEAL or SOFORT payment.
- `country` (String, required if using Stripe for SOFORT) Two-letter ISO 3166-1 alpha-2 country code of the payer.
- `plaid` (Object, required if Using Direct debit via Stripe ACH.) Plaid enables applications to connect with users' bank accounts.
- `userId` (String) Plaid user id.
- `locale` (String) Locale code in ISO 639-1 format (en, fr). By default, `en` will be used.
- `useGateway` (Boolean, required if using ACH, Autogiro, BACS, or SEPA via GoCardless) When `true`, Chargebee redirects the customer to the GoCardless payment page to collect bank account details. Customer fields are used to prefill that page. Check your GoCardless plan to see whether you can collect `bankAccount` details yourself.
- `customer` (Object, required if using Netbanking, UPI, SEPA (via Adyen, Stripe, BlueSnap, Checkout.com, or GoCardless), ACH (via GoCardless, BlueSnap, Braintree, or Stripe Financial Connections), Autogiro (via GoCardless), or BACS (via GoCardless or Stripe)) Customer with whom the subscription will be associated. Required for most Direct Debit schemes.
- `firstName` (String) First name. For most Direct Debit schemes, required if `company` is not provided.
- `lastName` (String) Last name. For most Direct Debit schemes, required if `company` is not provided.
- `email` (String, required if using Direct Debit (SEPA, ACH, Autogiro, or BACS), except Chargebee Payments ACH and Adyen ACH) Email address of the customer.
- `phone` (String) Phone number
- `company` (String) Company name. For most Direct Debit schemes, required if `firstName` and `lastName` are not provided.
- `billingAddress` (Object, required if using Stripe BACS) Billing address of the customer. Required for Stripe BACS. Also sent to GoCardless and Checkout.com SEPA.
- `addressLine1` (String) Address line 1.
- `addressLine2` (String) Address line 2.
- `addressLine3` (String) Address line 3.
- `city` (String) City.
- `state` (String) State name.
- `stateCode` (String) Two-letter state code.
- `countryCode` (String) Two-letter ISO 3166-1 alpha-2 country code.
- `zip` (String) Postal code.
- `bankAccount` (Object, required if using Netbanking, SEPA (via Adyen, Stripe, BlueSnap, Checkout.com, or GoCardless), ACH (via GoCardless, BlueSnap, Adyen, Braintree, or Chargebee Payments), Autogiro (via GoCardless), or BACS (via Stripe or GoCardless)) Bank account details of the customer.
- `bank` (String) Name of account holder's bank.
- `beneficiaryName` (String) Name of the beneficiary to whom the money is going to be sent.
- `accountNumber` (String) Bank account number.
- `accountType` (Enum) Represents the account type used to create a payment source. Available for Authorize.net ACH and Razorpay Net Banking(mandates) users only. If not passed, account type is taken as null. Allowed: `checking`, `savings`, `business_checking`, `current`.
- `ifscCode` (String) Indian Financial System Code (IFSC) is a unique code assigned to your bank's branch for online money transfers
- `iban` (String, required if using SEPA via Adyen, Stripe, BlueSnap, Checkout.com, or GoCardless (unless you pass local bank fields for GoCardless)) Account holder's International Bank Account Number.
- `nameOnAccount` (String, required if using ACH via Chargebee Payments) The name of the individual or entity associated with the bank account.
- `routingNumber` (String) A code that is used to identify financial organisations or banks when making a payment
- `accountHolderType` (String, required if using ACH via BlueSnap or Braintree) Type of entity that holds the bank account. Allowed: `individual`, `company`.
- `bankCode` (String) A unique identifier assigned by financial institutions to identify a specific bank branch in a country's banking system.
- `countryCode` (String) Two-letter ISO 3166-1 alpha-2 country code of the bank account. Use `US` for GoCardless ACH, `SE` for Autogiro, and `GB` for Stripe BACS.
- `swedishIdentityNumber` (String, required if Using Autogiro via GoCardless.) A unique identifier used to identify individuals in Sweden for various purposes, such as tax and social security purposes.
- `upi_app` (String) Applicable only for:Razorpay gatewayMobile web browsers (Android or iOS)The ID of the UPI app to be used for the UPI mandate authorization. Must be a valid `id` returned by the `fetchUpiInstalledAppList()` method. When not provided or when the value is invalid, the user is prompted to select a UPI app from the list of supported UPI apps.
- `additionalData` (Object) Additional information that needs to be passed for improving the chances of frictionless checkout flow.
- `plan` (String) Plan name
- `billingAddress` (Object) Card Billing Address
- `firstName` (String, required if Worldpay gateway is used) First name associated with billing address
- `lastName` (String) Last name associated with billing address
- `phone` (String) Phone number associated with the billing address
- `addressLine1` (String) Billing address line 1 (eg. number, street, etc).
- `addressLine2` (String) Billing address line 2 (eg. suite, apt #, etc.).
- `addressLine3` (String) Billing address line 3 (eg. suite, apt #, etc).
- `city` (String) City or locality name
- `state` (String) State
- `stateCode` (String) 2 letter code for US states or equivalent
- `countryCode` (String) 2 letter country code
- `zip` (String) Zip code or postal code
- `customerBillingAddress` (Object) Customer's Billing Address
- `firstName` (String, required if Worldpay gateway is used) First name associated with billing address
- `lastName` (String) Last name associated with billing address
- `phone` (String) Phone number associated with the billing address
- `addressLine1` (String) Billing address line 1 (eg. number, street, etc).
- `addressLine2` (String) Billing address line 2 (eg. suite, apt #, etc.).
- `addressLine3` (String) Billing address line 3 (eg. suite, apt #, etc).
- `city` (String) City or locality name
- `state` (String) State
- `stateCode` (String) 2 letter code for US states or equivalent
- `countryCode` (String) 2 letter country code
- `zip` (String) Zip code or postal code
- `shippingAddress` (Object) Shipping Address
- `firstName` (String, required if Worldpay gateway is used) First name associated with shipping address
- `lastName` (String) Last name associated with shipping address
- `phone` (String) Phone number associated with the shipping address
- `addressLine1` (String) Shipping address line 1 (eg. number, street, etc).
- `addressLine2` (String) Shipping address line 2 (eg. suite, apt #, etc.).
- `addressLine3` (String) Shipping address line 3 (eg. suite, apt #, etc).
- `city` (String) City or locality name
- `state` (String) State
- `stateCode` (String) 2 letter code for US states or equivalent
- `countryCode` (String) 2 letter country code
- `zip` (String) Zip code or postal code
- `email` (String, required if Worldpay gateway is used) Mail ID of the customer.
- `phone` (String) Phone number
- `mandate` (Object) Enabling this parameter will request Additional Factor Authentication (AFA) and mandate setup to the gateway. Applicable only for cards issued in India.
- `requireMandate` (Boolean) Set the value as `true` to create a mandate. The default value is `false`.
- `description` (String) Send the plan name in this description. This plan name will appear on the AFA page.
- `document` (Object, required if EBANX or dLocal gateway is used) The document details (e.g., national IDs or passports) used for document verification and payment processing by EBANX and dLocal.
- `number` (String) The document number.
- `type` (String) The type of document. Refer to the EBANX table or dLocal table below for the possible values.
- `callbacks` (Object) Callbacks to be used for this operation.
- `change` (Function) This function will be called during each step of 3DS flow
- `success` (Function) This function will be called if 3DS Authorization is successful
- `error` (Function) This function will be called if 3DS Authorization has failed
- `challenge` (Function) When this callback is implemented, the transaction will proceed in a redirect workflow if supported by the gateway. This callback function will be called with a redirect URL when the 3DS transaction requires a challenge. This workflow is currently supported by Adyen, Braintree and Stripe payment gateways.
- `redirectMode` (Boolean) Default value of this flag is `false`. When this is `true`, the entire page will be redirected to the `success_url` or `failure_url` instead of opening a new window. Note: `success_url` and `failure_url` must be provided while creating a payment intent for utilizing the redirectMode.
- `mandateText` (String, required if Using ACH via Braintree) Text implying proof of customer authorization. For example, 'I authorize Braintree to debit my bank account on behalf of My Online Store.'
##### Return value
A promise that resolves to an authorized payment intent object.
### iDEAL payment handler
The [iDEAL payment handler](https://www.chargebee.com/tutorials/ideal-integration-with-chargebee-js/) integrates the iDEAL payment method on your site or application.
#### `handlePayment()`
Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.
[Learn more.](https://www.chargebee.com/docs/js/payment-handler-api-ref#initiating-bank-payments)
##### Parameters
iDEAL uses the common bank `handlePayment()` parameters. See [Initiating bank payments](https://www.chargebee.com/docs/js/payment-handler-api-ref#initiating-bank-payments) for the full `paymentInfo` reference, including `userName` and `userEmail`. These two fields are required for the [Stripe gateway](https://www.chargebee.com/docs/payments/2.0/payment-gateways-and-configuration/stripe-ideal#handling-recurring-payments) (`userName` must match the name on the payer's bank account exactly). Because [Smart routing](https://www.chargebee.com/docs/payments/2.0/payment-gateways-and-configuration/gateway_settings#smart-routing) can select any of these gateways, provide both fields for every iDEAL payment.
##### Example
```js
chargebee.handlePayment("ideal", {
paymentIntent: () => {
// Make a call to your server to create a Chargebee payment intent.
return createPaymentIntent();
},
callbacks,
paymentInfo: {
// Required for Stripe.
userName: "Jane Doe",
userEmail: "janedoe@example.com",
}
});
```
#### `mountBankList()` deprecated
> **Deprecation notice**
>
> This method is deprecated and will no longer be supported after April 1, 2025.
>
> To ensure continued functionality, upgrade to the [latest version](https://www.chargebee.com/tutorials/ideal-integration-with-chargebee-js/) of the integration.
Attaches a dropdown element to the page that displays the list of banks supported by the gateway.
> **Note**
>
> For iDEAL payments, [Adyen Web Components](https://docs.adyen.com/payment-methods/ideal/web-component) can be used as an alternative to `mountBankList()`. After selecting a bank in the Adyen component, pass the information to the `paymentInfo` parameter in the `handlePayment()` method.
##### Syntax
```html
```
```js
idealPaymentHandler.mountBankList(selector, options);
```
##### Parameters
**Parameters**
- `selector` (String, required) A valid CSS Selector for the element where the payment button should be mounted.
- `options` (Object) Configuration options
- `locale` (String)
- `currency` (String) Currency code
- `gateway_account_id` (String) Chargebee gateway account ID
- `style` (Object) Style customizations for bank drop-down component
##### Return value
Returns a promise that resolves after successfully mounting the bank list.
##### Example
```js
chargebee.load("ideal").then((idealHandler) => {
// Mount bank list.
return idealHandler.mountBankList("#drop-down-container", {
currency: "USD",
});
});
```
#### `getSelectedBank()` deprecated
> **Deprecation notice**
>
> This method is deprecated and will no longer be supported after April 1, 2025.
>
> To ensure continued functionality, upgrade to the [latest version](https://www.chargebee.com/tutorials/ideal-integration-with-chargebee-js/) of the integration.
Retrieves the details of the bank selected by the user from the dropdown element.
##### Syntax
```js
idealHandler.getSelectedBank();
```
##### Return value
Returns an object containing the details of the selected bank:
```js
{
id: 'bank-id',
name: 'Name of the bank.'
}
```
### SOFORT payment handler
The [SOFORT payment handler](https://www.chargebee.com/tutorials/sofort-integration-with-chargebee-js/) integrates the SOFORT payment method on your site or application.
#### `handlePayment()`
Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.
[Learn more.](https://www.chargebee.com/docs/js/payment-handler-api-ref#initiating-bank-payments)
##### Parameters
SOFORT uses the common bank `handlePayment()` parameters. See [Initiating bank payments](https://www.chargebee.com/docs/js/payment-handler-api-ref#initiating-bank-payments) for the full `paymentInfo` reference. `country`, `userName`, and `userEmail` are required for the Stripe gateway. Adyen, Mollie, and Checkout.com do not require `paymentInfo` fields. Because [Smart routing](https://www.chargebee.com/docs/payments/2.0/payment-gateways-and-configuration/gateway_settings#smart-routing) can select any of your configured gateways, pass the Stripe fields whenever Stripe is enabled for SOFORT.
##### Example
```js
chargebee.handlePayment("sofort", {
paymentIntent: () => {
// Make an API call to the server to create a payment intent.
return createPaymentIntent();
},
paymentInfo: {
userName: "John Doe",
userEmail: "johndoe@example.com",
country: "US", // Country code.
},
});
```
### Klarna Pay Now payment handler
The [Klarna Pay Now payment handler](https://www.chargebee.com/tutorials/klarna-pay-now-integration-with-chargebee-js/) integrates the Klarna Pay Now payment method on your site or application.
The Klarna Pay Now payment handler object can be created by [loading](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#load-modulename) the payment method using a Chargebee instance.
#### `handlePayment()`
Initiates the payment process. After successful authorization, the payment intent is marked as authorized. The payment intent ID can then be used to create subscriptions or payment methods.
##### Syntax
```js
chargebee.handlePayment("klarna_pay_now", paymentOptions);
```
##### Parameters
**Parameters**
- `paymentIntent` (Function, required) Function that returns a payment intent object created on your server side.
- `paymentInfo` (Object, required) Transaction-related information.
- `userEmail` (String, required) Email address of the payer.
- `country` (String, required) Two-letter ISO 3166-1 alpha-2 country code of the payer.
- `lineItems` (Array