WooshPay OpenAPI
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Back to WooshPay Website
  • JS SDK Reference

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
NameRequired (M/C/O)TypeDescription
publishableKeyMstringYour publishable key.
optionsOobjectInitialization 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#

NameRequired (M/C/O)TypeDescription
optionsOobjectA 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#

NameRequired (M/C/O)TypeDescription
typeMstringThe type of Element being created, which is payment in this case.
optionsOobjectOptions 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#

NameRequired (M/C/O)TypeDescription
typeMstringThe 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#

NameRequired (M/C/O)TypeDescription
domElementMstring | DOM elementThe 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#

NameRequired (M/C/O)TypeDescription
eventMstringThe name of the event. In this case, ready.
handlerMfunctionhandler(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#

NameRequired (M/C/O)TypeDescription
eventMstringThe name of the event. In this case, click.
handlerMfunctionhandler(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#

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#

NameRequired (M/C/O)TypeDescription
optionsMobjectelements 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#

NameRequired (M/C/O)TypeDescription
clientSecretMstringThe 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#

NameRequired (M/C/O)TypeDescription
optionsMobjectelements 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#

NameRequired (M/C/O)TypeDescription
clientSecretMstringThe 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#

NameRequired (M/C/O)TypeDescription
optionsMobjectThe parameter object.

options object#

NameRequired (M/C/O)TypeDescription
sessionIdMstringThe ID of the Checkout Session that is used in Checkout's client and server integration.
Modified at 2023-02-06 11:22:17
Built with