🎧 Listening to Checkout Page Events

After the checkout page is generated and initialized, Deets will return tokenization events. These events contain a securely generated payment token, which is required to process a payment.

By listening to these checkout events, you can: ✅ Capture the payment token in real-time for seamless processing.
✅ Enhance security by validating transaction responses before processing.
✅ Improve customer experience by handling checkout success or failure efficiently.

---

🔎 Why Listen to Checkout Page Events?

When a customer submits their payment details via Deets iFrame, sensitive card data is never exposed to your system. Instead, Deets tokenizes the payment information and returns a secure token that represents the transaction.

You must listen to these checkout events because: 1️⃣ The payment token is sent via the event message. Without listening to the event, you won't receive the token.
2️⃣ The token is required to complete a payment. You'll use it in an API request to finalize the transaction.
3️⃣ Security and Compliance. Deets ensures PCI compliance by sending only non-sensitive tokenized data through the event listener.

By integrating the event listener correctly, your platform remains secure, PCI-compliant, and capable of handling real-time transactions smoothly.

---

🛠 Step 1: Set Up the Event Listener

To capture the tokenization event, add this line of code where the checkout form is embedded inside an iFrame:

window.addEventListener("message", handleTokenizationEvent);

This event listener will detect messages from Deets iFrame, allowing your system to extract the secure payment token.

---

🔑 Step 2: Extract the Token from the Event Data

When a transaction is completed, the event contains the tokenized payment details. The event data follows these structures:

Credit Card Payments

interface TokenizationResponse {
  type: "paymentCompleted";
  data: {
    message: "OK";
    data: {
      type: "tokenv3";
      id: string;  // Example: "474747aOlplH4747-1734960710"
      attributes: {
        label: "tokenv3";
        customerId: string;
      };
      customerId: string;  // Same as attributes.customerId
    };
  };
}

ACH Payments

interface ACHPaymentResponse {
  type: "achPaymentInitiated";
  data: {
    merchantId: string;
    miscData: string; // JSON string with additional data
    bank: {
      accountName: string;
      accountType: string; // "checking" or "savings"
      accountNumber: string; // This is the tokenized account number
      routingNumber: string;
    };
    StandardEntryClassCode: string; // "WEB"
    customer: {
      firstname: string;
      lastname: string;
      email: string;
    };
    transaction: {
      amount: string;
      currency: string;
      invoice: string;
    };
    encrypted_id: string;
  };
}

✅ Example Implementation

Here's how to listen for the event, extract the token, and process it:

const handleTokenizationEvent = (event: MessageEvent) => {
  // Validate the event origin to ensure it's from Deets
  if (!event.origin.includes("checkout.deets.com")) return;

  // Handle credit card payment event
  if (event.data?.type === "paymentCompleted") {
    const response = event.data as TokenizationResponse;
    const tokenId = response.data.data.id;  // Extract the token ID
    const customerId = response.data.data.customerId;  // Extract customer ID

    console.log("Received credit card token:", tokenId);
    console.log("Customer ID:", customerId);

    // Now, send this token to your backend for payment processing
  }
  
  // Handle ACH payment event
  if (event.data?.type === "achPaymentInitiated") {
    const response = event.data as ACHPaymentResponse;
    
    // Extract relevant data for processing
    const tokenizedAccountNumber = response.data.bank.accountNumber;
    const merchantId = response.data.merchantId;
    const routingNumber = response.data.bank.routingNumber;
    
    
    console.log("Received ACH payment data:");
    console.log("- Merchant ID:", merchantId);
    console.log("- Tokenized Account Number:", tokenizedAccountNumber);
    
    // Process the ACH payment with your backend
  }
};

// Attach event listener
window.addEventListener("message", handleTokenizationEvent);

🔄 Unmounting the Listener (Best Practice)

Since the checkout form may be reloaded multiple times, ensure the event listener is removed before adding a new one:

window.removeEventListener("message", handleTokenizationEvent);
window.addEventListener("message", handleTokenizationEvent);

---

⚠ Important Security Considerations

When handling payment tokens, always follow best security practices:

✅ Validate the Event Origin

Ensure the message originates from Deets' secure checkout domain:

if (!event.origin.includes("checkout.deets.com")) return;

This prevents malicious actors from injecting fake messages.

✅ Validate the Event Data

• Ensure the response matches the expected schema.
• Use a schema validation library (like zod or Joi) to validate response integrity.

✅ Handle Tokens Securely

• Never expose the payment token on the frontend. Always send it securely to your backend for further processing.
• Use HTTPS connections when sending the token to your server.

---

📋 TypeScript Types for Event Handling

For comprehensive type-checking in TypeScript applications, you can use this combined interface:

// Combined type for all possible checkout events
type CheckoutEventResponse = TokenizationResponse | ACHPaymentResponse;

// Parser function with type safety
function parseCheckoutEvent(event: MessageEvent): CheckoutEventResponse | null {
  if (!event.data?.type) return null;
  
  switch (event.data.type) {
    case "paymentCompleted":
      return event.data as TokenizationResponse;
    case "achPaymentInitiated":
      return event.data as ACHPaymentResponse;
    default:
      return null;
  }
}

// Usage example
window.addEventListener("message", (event) => {
  if (!event.origin.includes("checkout.deets.com")) return;
  
  const response = parseCheckoutEvent(event);
  if (!response) return;
  
  switch (response.type) {
    case "paymentCompleted":
      // Handle credit card payment
      const cardToken = response.data.data.id;
      processCardPayment(cardToken);
      break;
    case "achPaymentInitiated":
      // Handle ACH payment
      const achToken = response.data.bank.accountNumber;
      processACHPayment(achToken, response.data);
      break;
  }
});

---

🚀 Final Thoughts

By integrating Deets' event listener, you ensure a secure, fast, and seamless payment experience while maintaining full PCI compliance.

🔹 Without this event listener, you won't receive the payment token. This token is essential to process transactions securely.
🔹 Ensure proper validation and security checks before processing any payments.
🔹 Keep your checkout experience smooth by handling payment success or failure events efficiently.

Ready to go live? Start integrating Deets today and enable real-time, secure, and PCI-compliant payments for your business! 🚀