Links de pago
Crea y consulta links de cobro en USDT.
Un link de pago es la forma de emitir un cobro. El cliente paga en la página pública (publicUrl). El link nace pending; cuando el pago se valida pasa a credited. No marques la orden como pagada hasta que el payin asociado esté settled (webhook payin.settled o GET /payins/{id}). Los datos de tarjeta no pasan por tu servidor. Los depósitos se consultan y registran en /deposit-accounts; el cobro al cliente se emite con un link de pago.
Crear un link de pago
/api/v1/payment-links
Crea un checkout en USDT. Scope payment_links:write.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Idempotency-KeystringObligatorio1–255 caracteres. Obligatoria en este POST. Si repites la misma llave y el mismo cuerpo, se devuelve la respuesta original (Idempotent-Replayed: true). Si el cuerpo cambia, 422 idempotency_key_reuse.
amountstringOpcionalImporte en USDT, texto decimal (p. ej. "50.00").
payerMethodstringOpcionalPreferencia de método de pago del cliente, si aplica.
localAmountstringOpcionalImporte en moneda local si cotizas antes de crear el link.
descriptionstringOpcionalTexto visible para el pagador.
orderReferencestringOpcionalReferencia de tu orden. Solo letras, números, punto, guion y guion bajo. Si omites el campo, se genera ord_ + 12 caracteres. El mismo orderReference puede devolver el link ya creado (HTTP 200).
expiresInSecondsnumberOpcionalVigencia en segundos (600–604800).
metadataobjectOpcionalHasta 20 llaves de texto (máx. 40 caracteres la llave, 500 el valor).
Respuestas
- HTTP 201Link creado.
- HTTP 200Ya existía un link con el mismo orderReference.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 400
idempotency_key_requiredFalta el header Idempotency-Key. - HTTP 400
Bad RequestEl cuerpo tiene campos no declarados (p. ej. order_reference en vez de orderReference) o de tipo inválido. message es un arreglo con un texto por campo. - HTTP 409
seller_not_operationalEl comercio no está operativo. - HTTP 409
verification_not_approvedLa verificación del comercio no está aprobada. - HTTP 409
idempotency_request_in_progressLa misma Idempotency-Key se está procesando. Reintenta igual. - HTTP 422
invalid_amountImporte inválido, o enviaste amount y localAmount a la vez. - HTTP 422
invalid_metadatametadata no cumple los límites (20 llaves de texto, 40 y 500 caracteres). - HTTP 422
idempotency_key_reuseReutilizaste la Idempotency-Key con otro cuerpo.
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"
}
}Listar links de pago
/api/v1/payment-links
Listado paginado. Scope payment_links:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
statusstringOpcionalFiltra por estado.
pending · credited · expired · refunded
pagenumberOpcionalPágina (desde 1).
Respuestas
- HTTP 200Listado. Esta ruta usa items, total, page y pageSize (no has_more).
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 422
invalid_statusstatus no es un valor permitido.
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"
}Consultar un link de pago
/api/v1/payment-links/{linkId}
Detalle por UUID (no uses publicId aquí). Scope payment_links:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
linkIduuidObligatorioUUID interno del link, no el publicId (pay_…).
refreshstringOpcionalSi es true o 1, consulta primero el estado actualizado del cobro.
Respuestas
- HTTP 200Detalle del link.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no pertenece a tu comercio. También si linkId no es un UUID.
curl -X GET "$CLOBEPAY_API_BASE/payment-links/7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17?refresh=true" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"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"
}
}