Links de pago
Crea un cobro con página de pago alojada. Nace pending y se confirma solo cuando su payin queda settled.
Un link de pago es un cobro con página de pago alojada por Clobepay. Los datos de pago del cliente se capturan en esa página: nunca pasan por tu sitio ni por tu servidor. Se liquida en USDT.
Puedes crear links de pago con una llave de API. La respuesta incluye la
publicUrl, el objeto payin y metadata. También puedes crearlos desde el panel.Flujo
- Tu servidor crea el link con
POST /payment-linksy unaIdempotency-Key. - La respuesta trae la
publicUrlde la página de pago y su payin, ambos enpending. - Rediriges al cliente a esa URL (o la abres en un popup). El cliente paga.
- Clobepay valida el pago antes de liquidarlo y solo entonces pasa el payin a
settled. - Recibes el webhook
payin.settledy marcas la orden como pagada.
Regla clave: un link nace
pending y se confirma solo cuando su payin queda settled. El regreso del cliente a tu sitio no confirma el pago, y ningún aviso sin validar liquida un cobro.pending
Pago acreditado
credited
Reembolso totalrefunded
Vencidoexpired
Crear un link
amounten USDT, como texto decimal con hasta 2 decimales.orderReference: tu referencia de orden.metadata: hasta 20 llaves de hasta 500 caracteres. Se copia al payin y viaja en los webhooks. No pongas datos personales.- El comercio debe estar operativo y con su verificación aprobada; si no,
409 verification_not_approved.
POST/payment-links
curl -X POST "$CLOBEPAY_API_BASE/payment-links" \ -H "Idempotency-Key: order-10042" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"amount":"50.00","description":"Pedido 10042","orderReference":"10042","metadata":{"cart_id":"c_77"}}'Respuesta
{
"id": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
"publicId": "pay_8f2cK1mQ9vR4wL0tYbA3nC",
"publicUrl": "https://panel.clobepay.com/pagar/pay_8f2cK1mQ9vR4wL0tYbA3nC",
"orderReference": "10042",
"amount": "50.00",
"settlementAsset": "USDT",
"description": "Pedido 10042",
"status": "pending",
"expiresAt": "2026-11-20T18:00:00.000Z",
"creditedAt": null,
"settleAt": null,
"providerReference": null,
"receiptUrl": null,
"lastSyncedAt": null,
"createdAt": "2026-11-19T18:00:00.000Z",
"payerMethod": null,
"localQuote": null,
"providerFee": null,
"payin": {
"id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
"status": "pending"
}
}Mostrar la página de pago al cliente
No necesitas SDK ni librería: basta con la publicUrl del link. La página de pago es alojada e incluye la autenticación 3-D Secure de la tarjeta cuando aplica.
| Forma | Estado | Cómo |
|---|---|---|
| Redirección | Recomendada | Envía al cliente a publicUrl con un 302 o window.location. |
| Popup / pestaña nueva | Disponible | Abre publicUrl con window.open desde el clic del cliente para evitar bloqueadores. |
Al volver el cliente a tu sitio, o al cerrarse el popup, el link sigue en
pending: confirma la orden solo con el webhook payin.settled o consultando el payin.Consultar
curl -X GET "$CLOBEPAY_API_BASE/payment-links?status=pending" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"items": [
{
"id": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
"publicId": "pay_8f2cK1mQ9vR4wL0tYbA3nC",
"publicUrl": "https://panel.clobepay.com/pagar/pay_8f2cK1mQ9vR4wL0tYbA3nC",
"orderReference": "10042",
"amount": "50.00",
"settlementAsset": "USDT",
"description": "Pedido 10042",
"status": "pending",
"expiresAt": "2026-11-20T18:00:00.000Z",
"creditedAt": null,
"settleAt": null,
"providerReference": null,
"receiptUrl": null,
"lastSyncedAt": null,
"createdAt": "2026-11-19T18:00:00.000Z",
"payerMethod": null,
"localQuote": null,
"providerFee": null,
"payin": {
"id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
"status": "pending"
}
}
],
"total": 1,
"page": 1,
"pageSize": 20,
"settlementAsset": "USDT"
}Estados
| Link | Payin | Qué significa |
|---|---|---|
pending | pending | Creado; el cliente no ha pagado o el pago está en validación. |
credited | settled | Pago validado y acreditado a tu comercio. Ya puedes entregar. |
expired | expired | Venció sin pago. |
refunded | refunded | Pago reembolsado. |
Para decidir si una orden está pagada, usa siempre el estado del payin (Payins y depósitos).
Referencia de las rutas: Links de cobro.