Payment Errors

Payment error handling allows your host application to hook into payment failure events - for example when a user has insufficient balance - and control how the game responds. This feature is opt-in. To enable it, notify your THNDR integration contact.

Once enabled, the integration is required. When a payment fails, the game emits a postMessage and waits for your app to respond with an action before proceeding. If your app does not respond, the game will hang indefinitely.

The exchange

The flow is a two-step message exchange between the game and your host application.

Step 1 - Game notifies your app

When a payment error occurs, the game sends:

{
  "message": "operator_handle_payment_error",
  "data": {
    "error": {}
  }
}

The error object contains details about what went wrong. Your app should inspect this to decide which action to return.

Step 2 - Your app responds with an action

Your host application must reply to the game with operator_payment_error_handled and one of four actions:

{
  "message": "operator_payment_error_handled",
  "data": {
    "action": "RETRY"
  }
}

Action	Behaviour
RETRY	The game retries the payment automatically
GENERIC_ERROR	The game displays a standard error screen
OPERATOR_ERROR	The game displays a custom error message defined by you
IGNORE	The game handles the error silently with no user-facing feedback

If you use OPERATOR_ERROR, include a message field with the text to display:

{
  "message": "operator_payment_error_handled",
  "data": {
    "action": "OPERATOR_ERROR",
    "message": "Your account has insufficient funds. Please top up to continue."
  }
}

Example listener

window.addEventListener("message", (event) => {
  // Validate origin
  if (event.origin !== "https://game.thndr-cdn.com") return;

  let msg;
  try {
    msg = JSON.parse(event.data);
  } catch (e) {
    return;
  }

  if (msg.message.endsWith("operator_handle_payment_error")) {
    const error = msg.data?.error;

    // Inspect the error and decide how to respond
    const response = {
      message: "operator_payment_error_handled",
      data: {
        action: "RETRY", // Replace with your logic
      },
    };

    const iframe = document.getElementById("thndr-iframe");
    iframe.contentWindow.postMessage(
      JSON.stringify(response),
      "https://game.thndr-cdn.com"
    );
  }
});