> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Acepta Clave

> Pon el botón Pagar con ⚡ Clave en tu propio e-commerce, como Link o Shop Pay, o acepta Clave con el checkout de Recurrente

**Clave** es el pago en un clic de Recurrente. Una persona guarda su método de pago una vez, en cualquier negocio que cobra con Recurrente, y desde ahí paga con **Pagar con ⚡ Clave** sin volver a escribir su tarjeta. Más de 420,000 personas ya tienen métodos de pago guardados en Clave.

Si conoces Link de Stripe o Shop Pay, Clave cumple el mismo papel y se integra igual: un botón en tu checkout que abre una ventana de Clave, donde el comprador se identifica, escoge su tarjeta y paga.

## Dos formas de aceptar Clave

|                            | Cómo funciona                                                                                                                            | Cuándo usarla                                                 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Botón de Clave**         | Pones **Pagar con ⚡ Clave** junto a tu propio formulario de pago. Al tocarlo, se abre una ventana de Clave y te avisamos cuando se pagó. | Ya tienes tu propio e-commerce                                |
| **Checkout de Recurrente** | Insertas el checkout en tu página o rediriges a él. Clave aparece solo para quien lo tiene, junto a tarjetas, cuotas y transferencias.   | Quieres todos los métodos de pago sin construir tu formulario |

Las dos empiezan igual: tu servidor crea un checkout con la API.

## Cómo funciona para el comprador

1. Ve **Pagar con ⚡ Clave** en tu página. Si su navegador ya tiene Clave y ya pagó con él en tu tienda, el botón muestra su tarjeta: **⚡ Clave | Visa •••• 4242**.
2. Lo toca y se abre una ventana de Clave (en el teléfono, una pestaña nueva). Tu página se oscurece con un aviso para volver a la ventana o cancelar.
3. En la ventana se identifica con su correo o teléfono y confirma un código de un solo uso que le llega por WhatsApp o correo. Si ya lo hizo antes en ese navegador, pasa directo.
4. Escoge su tarjeta y paga. Si hace falta 3D Secure, ocurre en la misma ventana.
5. La ventana se cierra sola y tu página recibe `onSuccess`.

Quien no tiene Clave paga con tarjeta en la misma ventana, y la tarjeta queda guardada en Clave para la próxima vez, en tu tienda o en cualquier otra.

## Agrega el botón de Clave

### 1. Crea un checkout desde tu servidor

```bash
curl https://app.recurrente.com/api/checkouts \
  -H "X-SECRET-KEY: $RECURRENTE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "name": "Pedido #1042",
      "amount_in_cents": 25000,
      "currency": "GTQ",
      "quantity": 1
    }],
    "success_url": "https://tutienda.com/pedidos/1042/gracias",
    "cancel_url": "https://tutienda.com/carrito"
  }'
```

La respuesta trae el `id` del checkout y su `checkout_url`. El `checkout_url` es lo único que necesita el botón: no hay llave pública ni dominios que registrar. Si necesitas la dirección de envío, pídela en el ítem con `address_requirement`. Consulta [Crear un checkout](/referencia-api/api-reference/checkouts/create-checkout).

Pon siempre `success_url`: es a donde regresa el comprador cuando el botón no puede abrir una ventana (más abajo).

### 2. Muestra el botón

```html
<script src="https://app.recurrente.com/clave/v1/clave.js"></script>

<div id="clave-button"></div>

<script>
  Clave.button("#clave-button", {
    url: checkoutUrl, // el checkout_url que recibió tu servidor
    onReady: (event) => {
      // event.available: este comprador ya tiene Clave
      // event.payable: false si el checkout ya se pagó o venció
    },
    onSuccess: (event) => {
      // event.checkoutId, event.shippingAddress
      // confírmalo en tu servidor antes de entregar (paso 3)
    },
    onCancel: () => {
      // cerró la ventana sin pagar: deja que pague de otra forma
    },
    onFailure: (event) => {
      console.warn(event.message) // configuración inválida, p. ej. un url que no es checkout_url
    },
  });
</script>
```

El botón ocupa el ancho de su contenedor y mide 48px de alto. Llama a `Clave.button` una vez por checkout; si cambia el carrito, crea otro checkout, llama `unmount()` sobre el anterior y monta el nuevo.

| Evento                                                | Cuándo                                                                                                                                        |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `onReady({ available, payable })`                     | El botón cargó. `available` es `true` si reconocimos al comprador por su navegador o por el cliente con el que creaste el checkout.           |
| `onSuccess({ checkoutId, pending, shippingAddress })` | Se pagó. `shippingAddress` trae la dirección que escogió en Clave, si el checkout la pedía.                                                   |
| `onCancel()`                                          | Cerró la ventana o tocó **Cancelar pago** sin pagar.                                                                                          |
| `onFailure({ message })`                              | El botón no se pudo montar. Los pagos rechazados se quedan en la ventana para que el comprador lo intente de nuevo; no te llegan como evento. |

### 3. Confirma el pago en tu servidor

Un evento del navegador no prueba que se pagó. Entrega el pedido cuando tu servidor reciba el webhook `intent.succeeded` de ese checkout, o cuando `GET /api/checkouts/{id}` devuelva `status: paid`. Consulta [Webhooks](/guias-espanol/comenzar/webhooks).

Un pago con Clave llega como cualquier pago con tarjeta, con `details.used_presaved_payment_method: true`. Una vez pagado, la dirección también está en la API, bajo `payment.paymentable.address`.

## Navegadores dentro de apps

Instagram, Facebook, TikTok y WhatsApp abren los links en su propio navegador, donde una ventana nueva no puede avisarle a tu página. Ahí el botón lleva al comprador al checkout en la misma pestaña y, al pagar, lo regresa a tu `success_url`. Lo mismo pasa si el navegador bloquea la ventana. No tienes que hacer nada más que poner `success_url` y confirmar el pago en tu servidor.

## Pruebas

Crea el checkout con una [llave de Sandbox](/guias-espanol/guias/sandboxes-y-test-clocks) y el botón entra en modo prueba, como el de Link:

* Cualquier correo o teléfono tiene Clave.
* No enviamos ningún código. Escribe **000000**.
* La billetera de prueba ofrece la tarjeta **Visa •••• 4242**, y el pago se aprueba.
* La ventana dice **PRUEBA** junto al nombre de tu negocio.

Así recorres el flujo completo (botón, ventana, código, pago, `onSuccess` y webhook) sin una billetera real. Tu integración no cambia al pasar a producción: cambias la llave y listo.

Mientras desarrollas en `localhost`, el botón no muestra la tarjeta del comprador aunque ya la haya usado: eso depende de cookies que los navegadores solo comparten entre sitios con HTTPS. En producción funciona normal.

## Con el checkout de Recurrente

Si prefieres no construir tu formulario de pago, inserta el checkout completo. Clave aparece ahí solo, para quien lo tiene.

```bash
npm install recurrente-checkout
```

```html
<div id="recurrente-checkout-container"></div>
```

```javascript
import RecurrenteCheckout from "recurrente-checkout";

RecurrenteCheckout.load({
  url: checkoutUrl,
  onSuccess: (data) => { /* data.checkoutId: confírmalo en tu servidor */ },
  onFailure: (data) => { console.warn(data.error); },
  onPaymentInProgress: (data) => { /* solo transferencias bancarias */ },
});
```

Dentro del checkout insertado, el comprador se identifica con su correo o teléfono y un código, igual que en la ventana de Clave. Revisa [Embedded Checkouts](/guias-espanol/guias/embedded-checkouts).

## Reglas de marca

El botón ya trae la marca oficial; no lo dibujes tú. Si tu página menciona Clave en otro lugar, usa los archivos oficiales.

| Archivo                                   | URL                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| Botón de checkout (320×48, radio de 10px) | `https://www.recurrente.com/images/clave/brand/clave-button-checkout.svg` |
| Logo morado                               | `https://www.recurrente.com/images/clave/brand/clave-logo-purple.svg`     |
| Logo blanco                               | `https://www.recurrente.com/images/clave/brand/clave-logo-white.svg`      |

* **Texto:** "Pagar con ⚡ Clave". El rayo va antes de "Clave".
* **Color:** morado `#6C5CE7` con texto blanco. Clave nunca es verde.
* No dibujes un botón de Clave que abra otra cosa que Clave.

## Preguntas frecuentes

### ¿Tengo que activar Clave en mi cuenta?

No. Cualquier checkout que acepta tarjetas acepta Clave, con el botón o dentro del checkout de Recurrente.

### ¿Necesito una llave pública o registrar mis dominios?

No. El `checkout_url` solo lo puede crear tu servidor con tu llave secreta, y el resultado solo se le envía a la página que montó el botón.

### ¿Por qué el botón no mostró la tarjeta del comprador?

Lo hace cuando su navegador ya tiene Clave y ya confirmó un código en tu tienda, en navegadores que permiten cookies de terceros. En los demás muestra **Pagar con ⚡ Clave**, y el comprador se identifica con su código en la ventana.

### ¿Puedo saber qué pagos usaron Clave?

Los pagos hechos con un método guardado traen `details.used_presaved_payment_method: true` en el webhook.

### ¿Puedo ocultar Clave?

En tu e-commerce, simplemente no muestres el botón. En el checkout de Recurrente, Clave aparece donde el comprador lo tiene y el checkout acepta tarjetas.