How to embed invoice data to your payment page

Overview

After creating an invoice, you can show payment details to the customer directly on the merchant website.

Use this guide to embed the Calypso checkout form with an iframe or build a custom checkout form using invoice response data.

Checkout form options

Option	Description
iframe checkout form	Embed the Calypso checkout page into your website. Calypso renders payment details and checkout UI.
Custom checkout form	Build your own payment UI using invoice response fields such as invoiceAddress, amount, currency, fiatAmount, and fiatCurrency.

iframe checkout form

Use iframe when you want the customer to stay on the merchant website while Calypso handles the invoice checkout form.

1. Create an invoice by using one of the Invoice API creation methods.
2. Get idempotencyKey from the invoice creation response.
3. Build the checkout URL: https://pay.calypso.money/invoice/{idempotencyKey}.
4. Embed this URL into an iframe on the merchant checkout page.

<iframe
  src="https://pay.calypso.money/invoice/{idempotencyKey}"
  title="Calypso invoice checkout"
  width="100%"
  height="720"
  style="border: 0;"
  allow="clipboard-write"
></iframe>

Replace {idempotencyKey} with the value returned in the invoice creation response.

Custom checkout form

Use a custom checkout form when you want full control over the payment UI.

Required invoice response fields

Invoice response field	Usage in custom form
invoiceAddress	Customer sends funds to this address.
amount	Amount to pay for fixed-amount invoices.
currency	Crypto currency shown to the customer.
fiatAmount	Fiat amount for SINGLE_FIAT invoice, if applicable.
fiatCurrency	Fiat currency for SINGLE_FIAT invoice, if applicable.
idempotencyKey	Can be used to build the Calypso payment link.
expiration	Shows when the invoice expires, if applicable.

HTML example

<div class="invoice">
  <h4 id="invoice-currency">USDT_TRX</h4>
  <p>
    <span id="invoice-amount">100</span>
    <span id="invoice-currency-short">USDT</span>
  </p>
  <button type="button" onclick="copyText('invoice-amount')">Copy Amount</button>

  <p id="invoice-address">TXx000000000000000000000000000000000000</p>
  <button type="button" onclick="copyText('invoice-address')">Copy Address</button>

  <img
    id="invoice-qr"
    src="https://api.qrserver.com/v1/create-qr-code/?data=TXx000000000000000000000000000000000000&size=150x150"
    alt="Invoice address QR code"
  />
</div>

<script>
  function copyText(elementId) {
    const element = document.getElementById(elementId);
    const textArea = document.createElement("textarea");
    textArea.value = element.innerText;
    document.body.appendChild(textArea);
    textArea.select();
    document.execCommand("copy");
    textArea.remove();
  }
</script>

Replace the placeholder values with the invoice response data returned by Invoice API.

Recommended handling

Case	Recommendation
Customer opens checkout	Show amount, currency, invoice address, and QR code.
Customer returns to returnUrl	Read the paymentStatus query parameter and show a success or failed page.
Payment status changes	Update order status through Invoice webhooks and verify invoice state through [POST] invoice if needed.
Invoice expires	Stop showing payment details and create a new invoice if payment is still required.

Use paymentStatus only for the customer-facing return page. Use Invoice webhooks or [POST] invoice as the source of truth for backend order processing.

Related docs

Document	Link
Create invoice via API	How to create an Invoice via API
Invoice webhooks	Invoice webhooks
Invoice API reference	Invoice API