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.

Flujo

  1. Tu servidor crea el link con POST /payment-links y una Idempotency-Key.
  2. La respuesta trae la publicUrl de la página de pago y su payin, ambos en pending.
  3. Rediriges al cliente a esa URL (o la abres en un popup). El cliente paga.
  4. Clobepay valida el pago antes de liquidarlo y solo entonces pasa el payin a settled.
  5. Recibes el webhook payin.settled y marcas la orden como pagada.
Estados de un link de pago
pending
Pago acreditado
credited
Reembolso totalrefunded
Vencidoexpired

Crear un link

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

Formas de abrir la página de pago
FormaEstadoCómo
RedirecciónRecomendadaEnvía al cliente a publicUrl con un 302 o window.location.
Popup / pestaña nuevaDisponibleAbre publicUrl con window.open desde el clic del cliente para evitar bloqueadores.

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

Estados del link y de su payin
LinkPayinQué significa
pendingpendingCreado; el cliente no ha pagado o el pago está en validación.
creditedsettledPago validado y acreditado a tu comercio. Ya puedes entregar.
expiredexpiredVenció sin pago.
refundedrefundedPago 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.