Iframe Integration

Before you start: allow your domain

The browser only allows the iframe on pages from domains you have authorized. Register them in the console, under Checkout. Without that, the iframe is blocked by the page security policy (frame-ancestors) and renders blank, even with a correct payload.

Register each origin as https://yourdomain.com, with no path or query, and include your staging domains too. Only the partner owner can change the list.

Basic Usage

Embed the checkout directly on your website:

<iframe
  src="https://trp.tonramp.io/trp/{payload}"
  width="440"
  height="700"
  frameborder="0"
  style="border: none; border-radius: 12px;"
></iframe>

With an active custom domain, set src to https://trp.yourdomain.com/trp/{payload}. Allowing the domain of the page that embeds the iframe is still required — that is a separate list, on the same Checkout screen.

Generating the payload

Generate the payload through the authenticated API (POST /v1/wallet/trp/generate) and use the payload field from the response in the iframe URL. The page only renders payments for a registered partner’s wallet.

Parameters

The iframe loads the same checkout page. No additional parameters are needed beyond the payload in the URL.

Recommended Dimensions

Device	Width	Height
Mobile	`100%`	`700px`
Desktop	`440px`	`700px`

Full Example

<!DOCTYPE html>
<html>
<head>
  <title>Payment - My Store</title>
</head>
<body>
  <h1>Complete your payment</h1>

  <div style="max-width: 440px; margin: 0 auto;">
    <iframe
      src="https://trp.tonramp.io/trp/trp010148UQBJ6gU8..."
      width="100%"
      height="700"
      frameborder="0"
      style="border: none; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);"
    ></iframe>
  </div>
</body>
</html>

Theme

The iframe respects the user’s operating system theme (light/dark) automatically via prefers-color-scheme. The user can also switch manually within the checkout.

Where the payment happens

The embedded TRP checkout page is the entry point: it shows the merchant, the amount, the link QR and live status. The USDT payment happens in the TonRamp app, opened by the buttons on the page, and therefore leaves the iframe (the links use target="_top").

PIX checkout is the opposite: https://api.tonramp.io/v1/c/{id} shows the PIX QR and the payment completes inside the frame.