# JS SDK Reference

# Setting Up

Include the Wooshpay.js script on each page of your site—it should always be loaded directly from `https://js.wooshpay.com`, rather than included in a bundle or hosted yourself.

### **Initializing Wooshpay.js**

Use `Wooshpay(publishableKey, options?)` to create an instance of the **`Wooshpay`** object. This object is the entrypoint to the rest of the JS SDK. Your publishable API key is required when calling this function, as it identifies your website to us. When you’re ready to accept live payments, replace the test key with your live key in production.

**Parameters**

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| publishableKey | M | string | Your publishable key. |
| options | O | object | Initialization options. |

# The Element Object

Elements are customizable UI components used to collect sensitive information in your payment forms. Use an `Elements` instance to create and manage a group of individual Element instances.

## Create an Elements object

### wooshpay.elements(options?)

This method creates an `Elements` instance, which manages a group of elements.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| options | O | object | A set of options to create this `Elements` instance with. <br>clientSecret REQUIRED string<br>Required to use with the Payment Element. The client secret for a PaymentIntent or SetupIntent. |

# The Element

Use `Element` instances to collect sensitive information in your checkout flow.

## Create a Payment Element

### elements.create('payments', options?)

This method creates an instance of the Payment Element.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| type | M | string | The type of Element being created, which is `payment` in this case. |
| options | O | object | Options for creating the Payment Element.<br>**fields** object<br>By default, the Payment Element will collect all necessary details to complete a payment. For some payment methods, this means that the Payment Element will collect details like name or email that you may have already collected from the user. If this is the case, you can prevent the Payment Element from collecting these data by using the `fields`option. If you disable the collection of a certain field with the `fields` option, you must pass that same data to confirmPayment or the payment will be rejected.<ul><li>billingDetails 'never'\| 'auto' object<ul><li>name ''never' \| 'auto'</li><li>email ''never' \| 'auto'</li><li>phone ''never' \| 'auto'</li><li>address ''never' \| 'auto' object<ul><li>line1 ''never' \| 'auto'</li><li>line2 ''never' \| 'auto'</li><li>city ''never' \| 'auto'</li><li>state ''never' \| 'auto'</li><li>country ''never' \| 'auto'</li><li>postalCode ''never' \| 'auto'</li></ul></li></ul></li><li>readOnly boolean Applies a read-only state to the Payment Element so that payment details can’t be changed. Default is false. Enabling the `readOnly` option doesn't change the Payment Element's visual appearance.</li></ul> |

## Get a Payment Element

### elements.getElement('payment')

This method retrieve a previously created Payment Element.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| type | M | string | The type of Element being created, which is `payment` in this case. |

#### Returns

`elements.getElement('payment')` returns one of the following:

* An instance of a Payment Element.
* `null`, when no Payment Element has been created.

## Mount an Element

### element.mount(domElement)

The `element.mount` method attaches your Element to the DOM. `element.mount` accepts either a CSS Selector (e.g., `'#card-element'`) or a DOM element.

You need to create a container DOM element to mount an `Element`. If the container DOM element has a label, the `Element` is automatically focused when its label is clicked. There are two ways to do this:

1. Mount the instance within a `<label>`.
2. Create a `<label>` with a `for` attribute, referencing the ID of your container.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| domElement | M | string \| DOM element | The CSS selector or DOM element where your Element will be mounted. |

## Listen to Element events

## Element events

The only way to communicate with your Element is by listening to an event. An Element might emit any of the events below. All events have a payload object that has an `elementType` property with the type of the `Element` that emitted the event.

## Ready Event

### element.on('ready', handler)

Triggered when the `Element` is fully rendered.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| event | M | string | The name of the event. In this case, `ready`. |
| handler | M | function | `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired. |

## Click Event

### element.on('click',handler)

Triggered when the `Element` is clicked.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| event | M | string | The name of the event. In this case, `click`. |
| handler | M | function | `handler(event) => void` is a **callback function** that you provide that will be called when the event is fired. |

## Input Validation

Elements validate customer input as it is typed. To help your customers catch mistakes, listen to `change` events on an `Element` and display any errors.

#### Example

```js
cardElement.on('change', function(event) {  
	var displayError = document.getElementById('card-errors');  
  if (event.error) {    
    displayError.textContent = event.error.message;  } 
  else {    
    displayError.textContent = '';  
  } 
}
```

# Payment Intents

## Confirm a PaymentIntent

### wooshpay.confirmPayment(options)

Use `wooshpay.confirmPayment` to confirm a PaymentIntent using data collected by the Payment Element. When called, `wooshpay.confirmPayment` will attempt to complete any required actions, such as authenticating your user by displaying a 3DS dialog or redirecting them to a bank authorization page. Your user will be redirected to the `return_url` you pass once the confirmation is complete.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| options | M | object | **elements Required object**<br>The Elements instance that was used to create the Payment Element.<br>**confirmParams object**<br>Parameters that will be passed on to the api. Refer to the Payment Intents API for a full list of parameters.<ul><li>**return\_url** Required string The url your customer will be directed to after they complete payment.</li><li>**shipping** RECOMMENDED objectThe shipping details for the payment, if collected.</li><li>**payment\_method\_data** object When you call `wooshpay.confirmPayment`, payment details are collected from the Element and passed to the PaymentIntents confirm endpoint as the payment\_method\_data parameter. You can also include additional `payment_method_data` fields, which will be merged with the data collected from the Element.<ul><li>**billing\_details** object The customer's billing\_details. Details collected by Elements will override values passed here. Billing fields that are omitted in the Payment Element via the `fields` option required.</li></ul></li></ul>**redirect** 'always'\| 'if\_required'<br>By default, wooshpay.confirmPayment will only redirect if your user chooses a redirect-based payment method. If you set redirect : "always", then wooshpay.confirmPayment will always redirect to your return\_url after a successful confirmation. |

#### Returns

`wooshpay.confirmPayment` will return a `Promise`. Upon a successful confirmation, your user will be redirected to the `return_url` you provide before the Promise ever resolves. If the confirmation fails, the `Promise` will resolve with an `{error}` object that describes the failure. When the error type is `card_error` or `validation_error`, you can display the error message in `error.message` directly to your user. Note that for some payment methods, your user will first be redirected to an intermediate page to authorize the payment. If they fail to authorize the payment, they will be redirected back to your `return_url` and the PaymentIntent will have a `status` of `requires_payment_method`. In this case you should attempt to recollect payment from the user.

For payment methods that jump to a new page to finalize the payment like Alipayplus, Alipay, etc, it will redirect to return\_url after successful confirmation; for payment methods that stay in the current site like WeChat\_Pay, Card, etc, it will not be redirected.

Note that `wooshpay.confirmPayment` may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.

## Retrieve a PaymentIntent

### wooshpay.retrievePaymentIntent(clientSecret)

Retrieve a PaymentIntent using its client secret.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| clientSecret | M | string | The client secret of the PaymentIntent to retrieve. |

#### Returns

This method returns a `Promise` which resolves with a `result` object. This object has either:

* `result.paymentIntent`: a PaymentIntent was retrieved successfully.
* `result.error`: an error.

# Setup Intents

## Confirm a SetupIntent

### wooshpay.confirmSetup(options)

Use `wooshpay.confirmSetup` to confirm a SetupIntent using data collected by the Payment Element. When called, `wooshpay.confirmSetup` will attempt to complete any required actions, such as authenticating your user by displaying a 3DS dialog or redirecting them to a bank authorization page. Your user will be redirected to the `return_url` you pass once the confirmation is complete.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| options | M | object | **elements Required object**<br>The Elements instance that was used to create the Payment Element.<br>**confirmParams object**<br>Parameters that will be passed on to the api. Refer to the Setup Intents API for a full list of parameters.<ul><li>**return\_url** Required string The url your customer will be directed to after they complete payment.</li><li>**payment\_method\_data** object When you call `wooshpay.confirmSetup`, payment details are collected from the Element and passed to the SetupIntents confirm endpoint as the payment\_method\_data parameter. You can also include additional `payment_method_data` fields, which will be merged with the data collected from the Element.<ul><li>**billing\_details** object The customer's billing\_details. Details collected by Elements will override values passed here. Billing fields that are omitted in the Payment Element via the `fields` option required.</li></ul></li></ul>**redirect** 'always'\| 'if\_required'<br>By default, wooshpay.confirmPayment will only redirect if your user chooses a redirect-based payment method. If you set redirect : "always", then wooshpay.confirmPayment will always redirect to your return\_url after a successful confirmation. |

#### Returns

`wooshpay.confirmSetup` will return a `Promise`. Upon a successful confirmation, your user will be redirected to the `return_url` you provide before the Promise ever resolves. If the confirmation fails, the `Promise` will resolve with an `{error}` object that describes the failure. When the error type is `card_error` or `validation_error`, you can display the error message in `error.message` directly to your user. Note that for some payment methods, your user will first be redirected to an intermediate page to authorize the payment. If they fail to authorize the payment, they will be redirected back to your `return_url` and the PaymentIntent will have a `status` of `requires_payment_method`. In this case you should attempt to recollect payment from the user.

For payment methods that jump to a new page to finalize the payment like Alipayplus, Alipay, etc, it will redirect to return\_url after successful confirmation; for payment methods that stay in the current site like WeChat Pay, Card, etc, it will not be redirected.

Note that `wooshpay.confirmSetup` may take several seconds to complete. During that time, you should disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error result, you should be sure to show that error to the customer, re-enable the form, and hide the waiting indicator.

## Retrieve a SetupIntent

### wooshpay.retrieveSetupIntent(clientSecret)

Retrieve a SetupIntent using its client secret.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| clientSecret | M | string | The client secret of the SetupIntent to retrieve. |

#### Returns

This method returns a `Promise` which resolves with a `result` object. This object has either:

* `result.setupIntent`: a Setupintent was retrieved successfully.
* `result.error`: an error.

# Checkout

### wooshpay.redirectToCheckout(options?)

Use `wooshpay.redirectToCheckout` to redirect your customers to Checkout page. When the customer completes their purchase, they are redirected back to your website.

#### Parameters

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| options | M | object | The parameter object. |

#### options object

| Name | Required (M/C/O) | Type | Description |
| :--- | :--------------- | :--- | :---------- |
| sessionId | M | string | The ID of the Checkout Session that is used in Checkout's client and server integration. |