Client SDK API

This section details the methods and objects provided by the PayWizard Web Element SDK.

PayWizard(clientToken, options)

Initializes the PayWizard SDK instance.

Parameter	Type	Required	Description
clientToken	string	✓	Developer Token, used for authentication
options	Object		Optional parameters, currently undefined

Returns

SDK instance, providing the initCheckout method to create a checkout session.

Example

const payWizard = PayWizard("your-client-token");

payWizard.initCheckout(params)

Creates a new checkout session and returns the checkout object.

Parameter	Type	Required	Description
params.clientId	string	✓	Unique client identifier
params.merchantId	string	✓	Unique merchant identifier
params.checkoutId	string	✓	Unique checkout session identifier (obtained from server-side call to "Create Online Payment Order" API)
params.elementsOptions	Object		UI configuration options
params.elementsOptions.appearance	Object		Appearance-related configuration
params.elementsOptions.appearance.width	string | number		iframe width
params.elementsOptions.appearance.theme	"light" | "night"		Interface theme
params.savePaymentMethods	boolean		Whether to allow saving the customer's payment methods

About params.checkoutId

checkoutId is the unique identifier for the checkout session, obtained by your server-side through calling the "Create Online Payment Order" API. Brief information about this API is mentioned in the "Core Integration Steps", and detailed information can be found in the Server-side API Details section at the end of the document.

Returns

Promise<Checkout> - A Promise that resolves to a Checkout object.

Example

const checkout = await payWizard.initCheckout({
  clientId: "your-client-id",
  merchantId: "your-merchant-id",
  checkoutId: "checkout-id-from-your-server",
  elementsOptions: {
    appearance: {
      theme: "light",
      width: "100%",
    },
  },
  savePaymentMethods: true,
});

Checkout Object

The Checkout object provides methods for managing the payment process. It is the return value after a successful call to payWizard.initCheckout().

checkout.session(options)

Sets session-related parameters.

Parameter	Type	Required	Description
options.customer	string		Unique customer identifier, used for payment method storage
options.card	string		Saved payment method identifier

About options.card

options.card is the identifier of the saved payment method (i.e., cardToken). If your user has previously agreed to save payment methods, you can obtain their cardToken list by calling the "Retrieve Bank Card Information by UserId" API on your server-side. Detailed information about this API can be found in the Server-side API Details section at the end of the document.

Returns

None

Example

checkout.session({
  customer: "cust_123456",
  card: "card_token_xyz",
});

checkout.mount(selector)

Mounts the payment interface to the specified DOM element.

Parameter	Type	Required	Description
selector	string	✓	CSS selector specifying the mount point

Returns

Promise<void> - A Promise that resolves when mounting is complete.

Example

await checkout.mount("#checkout-container");

checkout.unmount()

Unmounts the payment interface from the DOM.

Returns

None

Example

checkout.unmount();

checkout.destroy()

Destroys the checkout instance and cleans up all resources.

Returns

None

Example

checkout.destroy();

checkout.confirm()

Confirms the payment transaction.

Returns

Promise<Object> - A Promise containing the transaction result.

Note

If a redirectUrl was provided during initialization (via the server-side call to the "Create Online Payment Order" API), after calling confirm, the user may be redirected to that URL. When redirected, the URL will automatically append the following query parameters:

• checkoutId: The ID of this checkout session.

• result: The payment result status code (e.g., 0 for success, 1 for failure, 2 for processing).

• customerId: (Optional) If applicable, the customer ID will be returned.

• cardToken: (Optional) If applicable, the card identifier for subsequent payments will be returned. You need to handle these parameters on your server-side to complete the subsequent process.

Example

const result = await checkout.confirm();