Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zopay.cash/llms.txt

Use this file to discover all available pages before exploring further.

​
mountPaymentIntentWidget: Render the QR Payment Widget

Render per-network QR codes, redacted wallet addresses, and a copy button into a DOM element. Optionally auto-polls for payment completion.
mountPaymentIntentWidget takes the response from createPaymentIntent and renders a fully functional payment UI into the element you specify. For each address in the response it generates a QR code, displays a redacted version of the wallet address (showing only the first and last three characters), and provides a copy-to-clipboard button. When onSuccess is provided and the response includes a ref_code, the widget automatically starts polling the API at pollInterval milliseconds and calls onSuccess as soon as the payment is confirmed. This method throws an Error if the target element is not found, or if result.success is false or result.addresses is empty. Always check result.success before calling this method, or handle errors via the onError callback.

​
Signature

zopay.mountPaymentIntentWidget(
  result: CreatePaymentIntentResponse,
  options: PaymentWidgetOptions
): void

​
Parameters

ParameterTypeDescription
resultCreatePaymentIntentResponseThe full response object returned by createPaymentIntent. The widget reads result.addresses, result.amount, result.currency, and result.ref_code to build its UI.
options.elementIdstringThe id of the DOM element that will host the widget. Any existing content inside the element is replaced.
options.theme"light" | "dark"Visual theme for the widget. Applies the zopay-light or zopay-dark CSS class to the root widget element.
options.onSuccess(info: PaymentIntentInfoResponse) => voidCalled when the API reports payment_status === 'completed'. Receives the full PaymentIntentInfoResponse so you can update your UI or redirect the user. Also enables automatic polling when combined with a ref_code in the result.
options.onError(error: Error) => voidCalled when an error occurs during QR code generation, clipboard access, or payment verification. The widget continues running after non-fatal errors.
options.pollIntervalnumberMilliseconds between automatic status checks. Only active when onSuccess is provided and result.ref_code is present. Set to a higher value on high-traffic deployments to reduce API load.
options.showValidatePaymentButtonbooleanWhen true, a manual “Validar pago” button is rendered below the QR codes. Clicking it triggers an immediate status check via getPaymentIntentInfo and calls onSuccess if payment is confirmed. Useful when you prefer to let the customer trigger verification themselves rather than polling automatically.
options.nonSolanaNetworkFeeNoticestringText shown under the network title and above the QR when this row’s network code is not Solana (SOL). Defaults to "Se aplicará un cargo adicional de ~50 céntimos de USDT para redes distintas a SOL." if omitted.

​
What gets rendered

The widget renders a zopay-widget container with:
  • Header — displays the amount, currency, and reference code.
  • Address blocks — one section per network address, each containing:
    • The network name (e.g., “Red ETH”).
    • A fee notice, if the network is not SOL.
    • A QR code image generated from the wallet address.
    • The redacted wallet address (e.g., "3Bc.....xyz").
    • A copy-to-clipboard button.
  • Polling status indicator — a text element updated with each poll result (e.g., "Pago completado").
  • Validate button (optional) — shown only when showValidatePaymentButton is true.

​
Auto-polling behavior

Polling starts immediately after the widget mounts if both of the following conditions are met:
  1. options.onSuccess is provided.
  2. result.ref_code is a non-empty string.
The widget calls getPaymentIntentInfo({ payment_id: ref_code }) at each pollInterval. When payment_status === 'completed', the interval is cleared and onSuccess is invoked. Network errors during polling are silently retried on the next interval.

​
Example

import {
  ZoPay,
  CreatePaymentIntentResponse,
  PaymentIntentInfoResponse,
} from 'zopay-sdk';

const zopay = new ZoPay({
  apiKey: 'YOUR_API_KEY',
  paymentLinkBaseUrl: 'https://your-api.com',
});

async function startPayment(currency: string, networkCode: string): Promise<void> {
  const result: CreatePaymentIntentResponse = await zopay.createPaymentIntent({
    amount: 100,
    currency: currency,
    networks: [networkCode],
    description: 'Order #1042',
    metadata: { orderId: '1042' },
  });

  if (!result.success) {
    throw new Error(result.message || result.error);
  }

  zopay.mountPaymentIntentWidget(result, {
    elementId: 'payment-container',
    theme: 'dark',
    pollInterval: 5000,
    showValidatePaymentButton: false,
    nonSolanaNetworkFeeNotice: 'Se aplicará un cargo adicional de ~50 céntimos de USDT para redes distintas a SOL.',
    onSuccess: (info: PaymentIntentInfoResponse) => {
      document.getElementById('payment-container')!.hidden = true;
      document.getElementById('success-banner')!.hidden = false;
      console.log('Payment confirmed. Total received:', info.transaction_summary.total_received);
    },
    onError: (err: Error) => {
      console.error('Widget error:', err.message);
    },
  });
}