Web Element Integration

PayWizard Web Element SDK

The PayWizard Web Element SDK provides a powerful and secure set of payment processing tools, helping developers easily integrate payment functionalities into web applications and keep their system out of the PCI DSS scope.

Overview

The PayWizard Web Element SDK is a secure and flexible payment integration solution that provides a seamless payment experience within your website using iframe technology. The SDK is designed to simplify the payment process while ensuring the highest level of security and compatibility.

Core Features

  • Secure Payment Interface - Isolates sensitive information via iframe

  • Multiple Payment Methods - Supports various payment options including credit cards, debit cards, etc.

  • Flexible Theme Customization - Adapts to your website's design style

  • Payment Method Storage - Simplifies payment process for returning customers

  • Multi-language Support - Provides localized experience for global users

  • Responsive Design - Offers a consistent experience across various devices

Payment Flow Overview

Installation and Setup

Using Script Tag

Add the following script to the <head> section of your HTML page:

<script src="https://cdn.paywizard.com/sdk/paywizard_0.0.2.umd.js"></script>

Basic HTML Structure

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>PayWizard Integration</title>
    <script src="https://cdn.paywizard.com/sdk/paywizard_0.0.2.umd.js"></script>
  </head>
  <body>
    <!-- The payment interface will be mounted to this container -->
    <div id="checkout-container"></div>

    <!-- Payment Button -->
    <button id="pay-button">Complete Payment</button>
  </body>
</html>

Core Integration Steps

This section details the core steps for integrating the PayWizard SDK, corresponding to the interaction sequence in the Payment Flow Overview.

Step 1: Merchant System Creation of Payment Order

The first step in the payment process is to call PayWizard's "Create Online Payment Order" API on your server-side. The purpose of this API is to register a new payment transaction with the PayWizard system and obtain a checkoutId. This checkoutId is a crucial parameter required for subsequent client-side SDK initialization.

Key Actions

  • Your server sends a request to the PayWizard server, including information such as order amount, transaction type, redirectUrl (for synchronous result redirection), and notifyUrl (for asynchronous result notification).

  • The PayWizard server returns the checkoutId and other relevant information (corresponds to Flowchart Step 2).

For detailed API request and response format, please refer to the Create Online Payment Order API details section later in this document.

Step 2: Client Checkout Page SDK Initialization and Checkout

After obtaining the checkoutId, you need to initialize the PayWizard SDK on the client-side (the user's browser) and create a checkout session. PayWizard will validate the access and order validity and return the result to the client.

// Initialize the SDK with your developer Token
const payWizard = PayWizard("your-client-token");

// Create a checkout session using the checkoutId obtained from the server
async function initializeCheckout(checkoutIdFromServer) {
  const checkout = await payWizard.initCheckout({
    clientId: "your-client-id",
    merchantId: "your-merchant-id",
    checkoutId: checkoutIdFromServer, // **IMPORTANT**: Use the checkoutId returned from the server in the previous step
    elementsOptions: {
      appearance: {
        width: "100%", // Control iframe width
        theme: "light", // Optional: "light" or "night"
      },
    },
    savePaymentMethods: true, // Enable payment method storage feature
  });
  // Paywizard-->>Checkout Page: 4. Validate access and order validity result (This is handled internally by initCheckout)
  return checkout;
}
// Example call:
const checkout = await initializeCheckout("checkout-id-from-your-server");

For detailed parameters of the PayWizard() and initCheckout() methods, please refer to the Client-side SDK Method Details.

Step 3: Client Checkout Page Session Configuration (Optional)

If your system supports user accounts and you wish to leverage PayWizard's payment method storage feature (i.e., allowing users to select saved cards for payment), you can configure session parameters in this step, such as the customer identifier (customer) and saved payment method identifier (card).

// The checkout object is the instance returned from the initCheckout in the previous step
checkout.session({
  customer: "customer-id-from-your-server", // Optional, your system's user ID
  card: "saved-card-token-from-your-server", // Optional, Token of the saved payment method
});

If you need to retrieve the user's saved payment methods (cardToken), your server-side can call the Retrieve Bank Card Information by UserId API. For detailed information, please refer to the description of the checkout.session(options) method.

Step 4: Client Checkout Page Rendering of Payment Interface

After configuration, call the mount method to render PayWizard's secure payment form (in the form of an iframe) into the specified DOM element on your page.

<!-- Ensure this container exists on the page -->
<div id="checkout-container"></div>
// The checkout object is the instance returned from the initCheckout in the previous step
await checkout.mount("#checkout-container");

For detailed information, please refer to the description of the checkout.mount(selector) method.

Step 5: Client Checkout Page Processing Payment and Retrieving Synchronous Result

When the user fills in the payment information and clicks the payment button on your page, call the confirm method to submit the payment (corresponds to Flowchart Step 5). PayWizard processes the payment (internally interacting with the payment channel, i.e., Flowchart Steps 6 and 7), and then returns the synchronous result to the client, or redirects to the redirectUrl you specified when creating the order (corresponds to Flowchart Step 8).

<!-- Payment Button -->
<button id="pay-button">Complete Payment</button>
// The checkout object is the instance returned from the initCheckout in the previous step
document.getElementById("pay-button").addEventListener("click", async () => {
  try {
    const result = await checkout.confirm(); // Corresponds to Flowchart Step 5
    console.log("Payment successful (synchronous result):", result); // Part of Flowchart Step 8
    // The result object contains the transaction result.
    // Handle successful payment logic based on the result, such as redirecting to a success page or displaying a success message.

    // Note: If redirectUrl was specified during server-side "Create Online Payment Order",
    // calling confirm may automatically redirect the page to that redirectUrl (corresponds to Flowchart Step 8).
    // In this case, the redirectUrl will include query parameters: checkoutId, result, customerId (optional), cardToken (optional).
    // You need to handle these parameters on the page pointed to by redirectUrl.
  } catch (error) {
    console.error("Payment failed (synchronous result):", error);
    // Handle payment failure logic
  }
});

For detailed information, please refer to the description of the checkout.confirm() method.

Step 6: Merchant System Processing Asynchronous Notification

In addition to the synchronous result obtained by the client through the confirm() method (or received via redirectUrl), the PayWizard server will also send an asynchronous notification to the notifyUrl you provided in the "Create Online Payment Order" API. This ensures that your system reliably receives the final payment result even if the user closes the browser or the network is interrupted.

Your server-side needs to:

  • Provide a publicly accessible notifyUrl endpoint.

  • Receive the POST request sent by PayWizard (usually in JSON format, please refer to PayWizard's notification specifications for details).

  • Verify the signature of the received notification (see PayWizard's signature verification documentation) to ensure security.

  • Update the order status in your system based on the notification content (e.g., mark as payment successful, failed, etc.).

  • Return a successful response (e.g., HTTP 200) to the PayWizard server, indicating that the notification has been successfully received and processed.

This step corresponds to Step 9 in the flowchart. The notifyUrl is set during the Create Online Payment Order API call.

PreviousQuick Start - Online PaymentNextClient Checkout Page SDK

Last updated