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.
ZoPayConfig, Network, and PaymentWidgetOptions Types
TypeScript interfaces for SDK initialization (ZoPayConfig), blockchain network objects (Network), and payment widget configuration (PaymentWidgetOptions).
These interfaces cover the three main configuration concerns in the ZoPay SDK: how you authenticate and connect to the API (ZoPayConfig), the shape of a blockchain network object returned from the API (Network), and the options you pass when mounting the embedded payment widget (PaymentWidgetOptions).
import { ZoPayConfig, Network, PaymentWidgetOptions } from 'zopay-sdk';
ZoPayConfig
ZoPayConfig is the object you pass to the ZoPay constructor.
| Field | Type | Description |
|---|
apiKey | string | Your ZoPay API key. Use this for server-side or trusted-environment integrations where the key can be kept secret. Required. |
baseUrl | string | The base URL for the ZoPay REST API. Defaults to the production endpoint when omitted. Override this to point at a staging or self-hosted environment. |
paymentLinkBaseUrl | string | The base URL used when constructing shareable payment links. Override this if you host a custom payment page at a different domain. Falls back to baseUrl. |
apiTimeoutMs | number | Request timeout in milliseconds. Default: 10000. Minimum enforced: 3000. Aggressive timeouts combined with retries can drop slow-but-successful responses, so values below 3000ms are clamped. |
maxRetries | number | Max retries for transient network/server errors. Default: 2. |
Network
Network describes a blockchain network supported by ZoPay. You receive arrays of Network objects when querying available networks.
| Field | Type | Description |
|---|
id | string | Unique identifier for the network, assigned by ZoPay. |
code | string | Short machine-readable code for the network (for example, "SOL" for Solana). Use this value when specifying networks in CreatePaymentIntentParams. |
name | string | Human-readable display name for the network (for example, "Solana"). |
is_active | boolean | Whether the network is currently available for payments. Only active networks can be used when creating a payment intent. |
PaymentWidgetOptions is the configuration object you pass to mountPaymentIntentWidget(). It controls where the widget renders, its visual theme, and the callbacks fired on completion or error.
| Field | Type | Description |
|---|
elementId | string | The id of the DOM element into which the widget is mounted. The SDK queries document.getElementById(elementId) and renders the widget inside it. |
theme | "light" | "dark" | Visual theme for the widget. Defaults to "light" when omitted. Choose "dark" to match a dark-mode interface. |
onSuccess | (info: PaymentIntentInfoResponse) => void | Callback invoked when the payment reaches a completed state. The full PaymentIntentInfoResponse object is passed as the argument so you can read transaction details or redirect the user. |
onError | (error: Error) => void | Callback invoked when an unrecoverable error occurs inside the widget, such as a network failure during polling. |
pollInterval | number | How often, in milliseconds, the widget polls the API for a status update. Lower values give faster confirmation feedback but increase API traffic. Defaults to a sensible interval when omitted. |
showValidatePaymentButton | boolean | When true, renders a manual “Validate Payment” button inside the widget that lets users trigger a status check immediately instead of waiting for the next poll cycle. Defaults to false. |
nonSolanaNetworkFeeNotice | string | Overrides the default notice for rows whose network is not SOL. Defaults to "Se aplicará un cargo adicional de ~50 céntimos de USDT para redes distintas a SOL." |
