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

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. Creamos el checkout con lo que hay en el carrito 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. Anota tus dominios

En Configuración → Botón Clave está el código listo para pegar, con el id de tu cuenta, y la lista de dominios donde vive el botón, por ejemplo mitienda.com. Agregar el primer dominio es lo que enciende el botón: solo se dibuja en esas páginas y los checkouts solo regresan a ellas; cada dominio cubre sus subdominios. Agrega localhost mientras desarrollas.

No hay llave pública: el id de tu cuenta ya es público, y solo sirve para dibujar el botón y abrir checkouts a tu nombre dentro de tus dominios. La API sigue usando tu llave secreta.

2. Muestra el botón

<script src="https://app.recurrente.com/clave/v1/clave.js"></script>
<div id="clave-button"></div>
<script>
  const button = Clave.button("#clave-button", {
    account: "98961cf7",
    items: [{ name: "Pedido #1042", amount_in_cents: 25000, currency: "GTQ" }],
    successUrl: "https://mitienda.com/pedidos/1042/gracias",
    cancelUrl: "https://mitienda.com/carrito",
    metadata: { order: "1042" },
    customer: { email: "ana@example.com" }, // opcional: el botón reconoce al comprador
    onReady: (event) => {
      // event.available: este comprador ya tiene Clave
    },
    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) // el id o el dominio no cuadran
    },
  });
  // Cambió el carrito: el botón se entera. Nada llega a Recurrente hasta el clic.
  button.update({ items: carrito.items });
</script>

No se crea nada hasta que el comprador toca el botón; el checkout que se crea entonces vence a las 3 horas si no se paga. Cada ítem se declara de dos maneras:

• Con un producto de Recurrente: product_id (o price_id) y quantity. El precio lo pone tu catálogo en Recurrente.
• Con el monto: name, amount_in_cents, currency y quantity. El precio lo pone tu página; lee el paso 3.

Si necesitas la dirección de envío, pídela en el ítem con address_requirement: "required". El botón ocupa el ancho de su contenedor y mide 48px de alto.

button.update({ items, successUrl, cancelUrl, metadata, customer, reference, signature }) cambia lo que el botón mandará al clic. button.unmount() lo quita.

3. Confirma el pago, y el monto, en tu servidor

Un evento del navegador no prueba que se pagó. Entrega el pedido cuando tu servidor reciba el webhook intent.succeeded, o cuando GET /api/checkouts/{id} devuelva status: paid. Los dos traen el checkout con su metadata y el amount_in_cents cobrado. Consulta Webhooks.

Si mandas los montos desde tu página, compara el monto. Lo fijó el navegador del comprador, que puede editarlo. Esos pagos llegan con amount_set_in_browser: true, en el webhook y en la API.

// En tu webhook de intent.succeeded
const order = findOrder(event.checkout.metadata.order);
if (event.amount_in_cents !== order.total_in_cents) return holdAndRefund(order);
fulfill(order);

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.

Firma el total (opcional)

Si mandas los montos desde la página pero quieres que el pago cuente como fijado por tu servidor, fírmalo. En Botón Clave está tu secreto de firma (sig_live_…); nunca lo pongas en la página. En tu servidor:

signature = sha256(reference + total_in_cents + currency + secreto_de_firma)

Por ejemplo, sha256("orden-1042" + "25000" + "GTQ" + "sig_live_…"), en hexadecimal. Pasa reference y signature a Clave.button. Si el total o la moneda no coinciden con los ítems, la firma no vale y el pago llega como fijado por el navegador. Manda currency en cada ítem cuando firmes.

Si tu servidor ya crea el checkout

Pasa url: checkout.checkout_url, el que devuelve POST /api/checkouts, en lugar de account e items. En ese modo no necesitas dominios: el checkout_url solo lo puede crear tu servidor con tu llave secreta. Si cambia el carrito, actualiza el checkout con PATCH /api/checkouts/{id}; el botón no necesita enterarse.

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 successUrl. Lo mismo pasa si el navegador bloquea la ventana. No tienes que hacer nada más que poner successUrl y confirmar el pago en tu servidor.

Pruebas

Usa el id de tu Sandbox como account 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 el id de cuenta 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 */ },
});

El checkout insertado abre con el botón Pagar con Clave, que abre la misma ventana de Clave; quien prefiera seguir en el formulario se identifica con su correo o teléfono y un código. 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 cuenta que acepta tarjetas acepta Clave, con el botón o dentro del checkout de Recurrente.

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

Llave pública no: el botón usa el id de tu cuenta, que ya es público. Dominios sí: la lista evita que otra página use tu nombre o mande al comprador a otro sitio. Si tu servidor ya crea el checkout y pasas url, tampoco necesitas dominios.

¿Qué significa amount_set_in_browser?

Que el monto llegó desde la página del comprador, no desde tu servidor ni desde tu catálogo en Recurrente. Compáralo con tu pedido antes de entregar, o firma el total para que llegue como fijado por tu servidor.

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