Payins
Consulta las entradas de dinero de tu comercio.
Un payin es toda entrada de dinero a tu comercio, venga de un link de pago o de una cuenta de depósito. Todo payin nace pending y solo pasa a settled cuando Clobepay valida el pago. Un payin expired o failed no pasa a settled por sí solo. La liquidación es en USDT.
Listar payins
/api/v1/payins
Más recientes primero. Scope payins: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 · settled · expired · failed · refunded
sourcestringOpcionalOrigen del payin.
payment_link · deposit_account · bank_transfer · crypto_deposit · internal_transfer
fromstringOpcionalISO-8601: createdAt ≥ from.
tostringOpcionalISO-8601: createdAt ≤ to.
limitnumberOpcional1–100 (20 por defecto).
startingAfterstringOpcionalCursor: un id público pi_… de la página anterior.
Respuestas
- HTTP 200Lista con cursor.
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. - HTTP 422
invalid_sourcesource no es un valor permitido. - HTTP 422
invalid_fromfrom no es una fecha ISO-8601 válida. - HTTP 422
invalid_toto no es una fecha ISO-8601 válida. - HTTP 422
invalid_limitlimit no es un entero entre 1 y 100. - HTTP 422
invalid_cursorstartingAfter no es el id (pi_…) de un payin de tu comercio.
curl -X GET "$CLOBEPAY_API_BASE/payins?status=pending&limit=10" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"object": "list",
"data": [
{
"id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
"object": "payin",
"status": "pending",
"source": "payment_link",
"amount": "50.00",
"asset": "USDT",
"providerFee": null,
"netAmount": null,
"paymentLinkId": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
"providerReference": null,
"settledAt": null,
"availableAt": null,
"refundedAt": null,
"metadata": {
"cart_id": "c_77"
},
"createdAt": "2026-11-19T18:00:00.000Z",
"updatedAt": "2026-11-19T18:00:00.000Z"
}
],
"hasMore": false
}Consultar un payin
/api/v1/payins/{payinId}
Detalle por id público pi_…. Scope payins:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
payinIdstringObligatorioId público (pi_…).
Respuestas
- HTTP 200Detalle.
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
payin_not_foundNo existe o no pertenece a tu comercio.
curl -X GET "$CLOBEPAY_API_BASE/payins/pi_3Kx9mQ2vR8wL0tYbA4nC1e" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
"object": "payin",
"status": "settled",
"source": "payment_link",
"amount": "50.00",
"asset": "USDT",
"providerFee": null,
"netAmount": null,
"paymentLinkId": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
"providerReference": null,
"settledAt": "2026-11-19T18:05:00.000Z",
"availableAt": "2026-11-19T18:05:00.000Z",
"refundedAt": null,
"metadata": {
"cart_id": "c_77"
},
"createdAt": "2026-11-19T18:00:00.000Z",
"updatedAt": "2026-11-19T18:00:00.000Z"
}