Checkout en el navegador

Checkout propioCopiar enlace

El checkout alojado resuelve los estados de pago por ti. Si construyes uno propio:

1. Consulta client.checkouts.retrieve(id).
2. Obtén client.checkouts.paymentMethods(id) y muestra lo que cada método pide. Si no trae ninguno, unavailable dice por qué: muéstralo y no pidas datos.
3. Envía client.checkouts.pay(id, input) con el amount del método que mostraste.
4. Si el pago queda pending, atiende su nextAction y espera el resultado con waitForChange.
5. Si falla, muestra el motivo y deja que el cliente pague de nuevo.

import { createClient } from "@boelabs/billete-sdk/client";

const client = createClient({ apiVersion: "2026-10-24" });
const checkout = await client.checkouts.retrieve("chk_ejemplo");
const methods = await client.checkouts.paymentMethods(checkout.id);

Cuando no hay con qué pagarCopiar enlace

Si el checkout no se puede pagar ahora, paymentMethods devuelve data vacío y unavailable con el motivo; si hay métodos, unavailable es null. Muestra su message antes de pedirle datos al cliente:

const { data: methods, unavailable } = await client.checkouts.paymentMethods(checkout.id);
if (unavailable) showNotice(unavailable.message, { retry: unavailable.code === "payments_unavailable" });

Lo que pide cada métodoCopiar enlace

Un mismo método puede atenderlo un proveedor u otro, y cada uno pide cosas distintas. Construye la pantalla con lo que devuelve paymentMethods, nunca con campos fijos en tu código:

De ahí salen dos recorridos:

• Paga primero y luego confirma. Con instructions y fields, el cliente envía el dinero, vuelve y escribe cómo pagó (por ejemplo, teléfono, banco y fecha de su Pago Móvil). Esos fields van en pay.
• Paga y luego escribe un código. Con verification: true, pay devuelve el pago pending con nextAction.type === "code". Si además hay instructions, el cliente envía el dinero antes de pay y escribe la referencia en el paso del código. Si no, el código llega por SMS después de pay.

Así se ven hoy los métodos de Billete:

Tasa congeladaCopiar enlace

Un precio en dólares o euros se cobra en bolívares a tasa BCV. Con cripto, un precio en bolívares, dólares o euros se cobra en USDT: el dólar a la par y lo demás a la tasa BCV del dólar. La tasa queda congelada para el checkout o cobro durante 30 minutos desde que se consultan sus métodos: hasta expiresAt de cada método, paymentMethods devuelve el mismo amount y el pago se cobra a esa tasa. Pasado ese tiempo, la siguiente consulta usa la tasa vigente y la congela de nuevo.

Envía en pay el amount que viste. Si ya no es el que se cobra (la tasa venció y el monto cambió, o cambió el total), el pago no se cobra y responde exchange_rate_changed (409, param: "amount"). Consulta de nuevo los métodos, muestra el nuevo monto y vuelve a enviar el pago. Sin amount, el pago se cobra a la tasa vigente al pagar.

Para probar esa respuesta sin esperar a que cambie la tasa, envía un amount distinto del que devolvió el método (por ejemplo, method.amount + 1). Billete lo rechaza igual que a un monto vencido, en prueba y en producción, y no cobra nada.

const method = methods.data.find((option) => option.id === "pago_movil")!;
await client.checkouts.pay(checkout.id, {
  method: method.id,
  amount: method.amount,
  // Lo que escribió el cliente en cada uno de `method.fields`, por su `key`.
  fields: values,
});

Al aplicar un cupón con client.checkouts.update(id, { coupon }) (en un cobro, client.invoices.update(id, { coupon })), el total cambia y también los montos convertidos: vuelve a pedir paymentMethods antes de pagar. allowCoupons dice si tu negocio acepta cupones de sus clientes.

Estados del pagoCopiar enlace

pay responde el checkout con su payment. Antes del primer intento, payment es null.

Los motivos de failure.code son insufficient_funds, payment_not_found, amount_mismatch, invalid_details, declined, provider_unavailable, expired (no terminó a tiempo), canceled (volvió atrás) y abandoned (salió de la página mientras se esperaba su código). Un checkout admite hasta 10 intentos de pago.

pay espera hasta 25 segundos la respuesta del proveedor antes de responder pending, así que muchos pagos llegan ya resueltos.

El paso del códigoCopiar enlace

const action = checkout.payment?.status === "pending" ? checkout.payment.nextAction : null;
if (action?.type === "code") {
  const next = await client.checkouts.submitPaymentCode(checkout.id, { code });
}

• label, length y message dicen qué pedir: "Referencia del pago", 6 dígitos.
• Un código incorrecto responde payment_code_invalid (422, param: "code") y el pago sigue esperando. Al quinto intento fallido, el pago pasa a failed.
• Con resendable: true, resendPaymentCode envía otro código. Pasado expiresAt, el código ya no sirve.
• cancelPayment vuelve atrás: el pago pasa a failed con canceled, nada se cobra y el cliente puede corregir sus datos o elegir otro método.
• Mientras la página espera el código, llama a notePayerPresence cada 15 segundos y al volver a la página. Después de la primera llamada, un minuto sin noticias cancela el pago como abandoned. Si el pago ya no espera un código, responde payment_code_not_expected: deja de enviarla.

Esperar el resultadoCopiar enlace

Mientras el pago esté pending, espera el siguiente cambio con waitForChange en vez de consultar cada pocos segundos: la API responde en cuanto el checkout cambia (el banco confirmó, el pago falló, llegó un código) o, si en 25 segundos no cambió nada, devuelve el mismo checkout y vuelves a esperar.

async function settled(checkout: PublicCheckout): Promise<PublicCheckout> {
  const waiting = checkout.status === "open" && checkout.payment?.status === "pending";
  return waiting ? settled(await client.checkouts.waitForChange(checkout)) : checkout;
}

const result = await settled(checkout);

waitForChange envía la revision del checkout que tienes (If-None-Match) y pide esperar (Prefer: wait=25); por HTTP, la respuesta es el checkout nuevo o 304 sin cambios. Los cobros tienen lo mismo con client.invoices.waitForChange. Si tu timeoutMs es menor de 30 segundos, la espera se acorta para terminar antes.

El resultado también llega a tu servidor por el webhook checkout.completed: es la fuente de verdad para entregar la compra. Si tu checkout no puede seguir (un método que no soportas, un error inesperado), envía al cliente a checkout.url, la página alojada del mismo checkout.

Errores frecuentesCopiar enlace

Todos llegan como BilleteError con code estable y un message en español que puedes mostrar al cliente. Estos son los que puede ver el pagador; el catálogo completo dice qué significa cada uno, y en TypeScript code tiene ese tipo.

Escenarios de pruebaCopiar enlace

Con un checkout de prueba, cada método trae testScenarios: lo que hay que enviar en cada paso para llegar a un resultado conocido. Sirven para rellenar tu formulario automáticamente mientras pruebas.

Qué vende el checkoutCopiar enlace

Cada ítem de checkout.items trae planId o productId y, si le diste una a ese plan o producto, su lookupKey: tu propio nombre para él (plus, camiseta_negra). Úsalo para mostrar lo tuyo sin guardar IDs de Billete en tu app. A diferencia de metadata, que nunca llega al navegador, lookupKey es público.

Un ítem de producto trae también imageUrl: la foto de su variante o, si no tiene, la principal del producto (null en los planes). Y checkout.merchant.logoUrl es el logo de tu negocio, si subiste uno en Configuración › General. Ambas direcciones son públicas y se pueden guardar en caché sin vencimiento.

Métodos del cliente públicoCopiar enlace

También existe carrierOffices(carrier) para consultar oficinas de envío. Checkouts y cobros incluyen submitPaymentCode, resendPaymentCode, notePayerPresence y cancelPayment, y un cobro se paga igual que un checkout.