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. clientSecret REQUIRED string 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. fields object 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 fieldsoption. 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. billingDetails 'never'| 'auto' object name ''never' | 'auto' email ''never' | 'auto' phone ''never' | 'auto' address ''never' | 'auto' object line1 ''never' | 'auto' line2 ''never' | 'auto' city ''never' | 'auto' state ''never' | 'auto' country ''never' | 'auto' postalCode ''never' | 'auto' 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.

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

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 The Elements instance that was used to create the Payment Element. confirmParams object Parameters that will be passed on to the api. Refer to the Payment Intents API for a full list of parameters. return_url Required string The url your customer will be directed to after they complete payment. shipping RECOMMENDED objectThe shipping details for the payment, if collected. 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. 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. redirect 'always'| 'if_required' 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 The Elements instance that was used to create the Payment Element. confirmParams object Parameters that will be passed on to the api. Refer to the Setup Intents API for a full list of parameters. return_url Required string The url your customer will be directed to after they complete payment. 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. 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. redirect 'always'| 'if_required' 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.