Acepta Clave

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

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

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.

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

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

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.

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

npm install recurrente-checkout

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

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.

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.

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