Skip to main content

Getting Started

This guide walks you through integrating the Drop-in Checkout. By the end, you'll have a working payment form.

Prerequisites​

Before you begin:

  1. A Purse account with at least one payment method enabled
  2. A backend capable of creating client sessions via the Purse API

Integration Steps​

Step 1: Load the SDK​

Add the script tag to your HTML:

<!-- Sandbox -->
<script src="https://cdn.purse-sandbox.com/dropin-checkout/latest/purse.js"></script>
<!-- Production -->
<script src="https://cdn.purse-secure.com/dropin-checkout/stable/purse.js"></script>

The Purse object is available globally.

Step 2: Add a Container Element​

Create a container where the payment form will render:

<div id="loading-spinner">Loading...</div>
<div id="purse-dropin"></div>
<button id="pay-button" disabled>Pay</button>

The pay button starts disabled and will be enabled when the user has selected a valid payment method.

Step 3: Initialize the Drop-in​

Create an instance using your client session:

Pass the widget.data from your client session response:

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data
});

Step 4: Mount the Widget​

Attach the Drop-in to your container:

const container = document.getElementById("purse-dropin");
await dropin.mount(container);

Step 5: Enable the Pay Button​

Subscribe to isPaymentFulfilled to enable the pay button when the user has selected a valid payment method:

const payButton = document.getElementById("pay-button");

dropin.isPaymentFulfilled.subscribe((isFulfilled) => {
  payButton.disabled = !isFulfilled;
});

Step 6: Submit the Payment​

Trigger payment submission when the user clicks your pay button:

document.getElementById("pay-button").addEventListener("click", async () => {
  try {
    await dropin.submitPayment();
    // On success, the SDK handles redirection automatically
  } catch (error) {
    console.error("Payment failed:", error.message);
    // Display error to user
  }
});

Complete Example​

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Checkout</title>
  <style>
    body { font-family: system-ui, sans-serif; max-width: 480px; margin: 40px auto; padding: 20px; }
    #loading-spinner { text-align: center; padding: 40px; color: #666; }
    button { width: 100%; padding: 12px; background: #0066cc; color: white; border: none; border-radius: 6px; cursor: pointer; }
    button:disabled { opacity: 0.5; cursor: not-allowed; }
  </style>
</head>
<body>
  <div id="loading-spinner">Loading payment form...</div>
  <div id="purse-dropin"></div>
  <button id="pay-button" disabled>Pay</button>

  <script src="https://cdn.purse-sandbox.com/dropin-checkout/latest/purse.js"></script>
  <script>
    async function init() {
      try {
        const payButton = document.getElementById("pay-button");

        const dropin = await Purse.createDropinCheckout({
          session: "YOUR_CLIENT_SESSION_DATA", // From your backend
          eventListener: (event) => {
            if (event.code === "ready") {
              document.getElementById("loading-spinner").style.display = "none";
            }
            if (event.code === "error") {
              console.error("Drop-in error:", event.payload);
            }
          }
        });

        await dropin.mount(document.getElementById("purse-dropin"));

        // Enable pay button when payment method is selected
        dropin.isPaymentFulfilled.subscribe((isFulfilled) => {
          payButton.disabled = !isFulfilled;
        });

        payButton.addEventListener("click", async () => {
          payButton.disabled = true;
          payButton.textContent = "Processing...";

          try {
            await dropin.submitPayment();
          } catch (error) {
            console.error(error.message);
            payButton.disabled = false;
            payButton.textContent = "Pay";
          }
        });
      } catch (error) {
        console.error("Failed to initialize Drop-in:", error);
      }
    }

    init();
  </script>
</body>
</html>

What Happens After submitPayment()​

When submitPayment() is called:

  1. The SDK validates the selected payment method
  2. The SDK processes the payment and handles any required authentication (e.g., 3D Secure)
  3. The browser is redirected to your configured return URL with the payment result

You don't need to handle redirects manually — the SDK manages the entire flow and always redirects the user to your return URL upon completion.

Next Steps​