> ## 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.

# ZoPay SDK Overview

> @zopay/js — widget de pago para el navegador, sin claves.

`@zopay/js` es la librería de UI del navegador para ZoPay. Renderiza un widget de pago (QR + selector de moneda/red + polling de estado) a partir de un payment intent que tu **backend** creó.

```bash theme={null}
npm install @zopay/js
```

<Warning>
  **Keyless.** Este paquete nunca contiene, acepta ni transmite claves de ZoPay. Las claves secretas (`sk_test_…` / `sk_live_…`) viven en tu servidor.
</Warning>

## Cómo encaja en el flujo de pago

```
[el usuario hace click en "pagar" en me.com]
        │
        ▼
[tu frontend] ── POST /tu-backend/checkout/session ──▶ [tu backend]
                                                          │
                                          (tiene sk_live_)│
                                                          ▼
[tu backend] ── POST https://api.zopay.cash/connect/v1/payment-intents ──▶ [ZoPay API]
                (amount computado en el servidor desde el carrito)
            ◀── { id, amount, currency, addresses[…] } ───────────────────┘
        │
        ▼
[tu frontend] ── recibe intent ──▶ mountPaymentWidget(target, { intent, checkStatus })
                                        (widget muestra QR, polea estado)
```

**El backend del merchant crea el intent. El widget consume el resultado.** El widget nunca habla directo con ZoPay API — el callback `checkStatus` proxea las lecturas de estado a través de tu backend.

## API pública

| Export                                                      | Para qué sirve                                                                                  |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [`mountPaymentWidget`](/sdk-reference/mount-payment-widget) | Renderiza el widget completo (QR + selector + polling). Devuelve `{ destroy, refresh }`.        |
| [`createPoller`](/sdk-reference/create-poller)              | Máquina de estados de polling sin UI — para integraciones con UI a medida.                      |
| [`normalizeIntent`](/sdk-reference/normalize-intent)        | Mapea el envelope `PaymentIntent` de la API al shape `StatusInfo` que consume el widget/poller. |

## Lo que NO debes hacer

Estas no son preferencias estilísticas — son el modelo de seguridad del SDK.

1. **Nunca** pongas una clave `sk_test_…` o `sk_live_…` en código del navegador ni en ejemplos que subes a git.
2. **Nunca** crees un payment intent desde el navegador. Crear el intent requiere la clave secreta. Eso pasa en tu backend.
3. **Nunca** confíes en el `amount` que envía el cliente. Compútalo desde el carrito en tu backend.

Un ejemplo inseguro copiado-pegado es una brecha de producción. El SDK está diseñado para hacer el camino seguro el más corto.

## Sandbox vs producción

Un solo host: `https://api.zopay.cash`. El prefijo de la clave decide el modo:

* `sk_test_…` → sandbox (dinero ficticio en el sentido de aislamiento; redes reales).
* `sk_live_…` → producción.

Tu backend cambia la clave; **nada en `@zopay/js` cambia**.

Más sobre el modelo en [Entornos](/get-started/environments).

## Siguiente paso

<Card title="Quickstart SDK" icon="rocket" href="/sdk-reference/quickstart">
  Cómo crear el intent en el servidor y montar el widget en el navegador.
</Card>