Volver a la referencia

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.

Estados de un payin
pending
Pago validado
settled
Reembolso totalrefunded
Vencidoexpired
Fallidofailed
GET

Listar payins

/api/v1/payins

Más recientes primero. Scope payins:read.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

status
query
stringOpcional

Filtra por estado.

pending · settled · expired · failed · refunded

source
query
stringOpcional

Origen del payin.

payment_link · deposit_account · bank_transfer · crypto_deposit · internal_transfer

from
query
stringOpcional

ISO-8601: createdAt ≥ from.

to
query
stringOpcional

ISO-8601: createdAt ≤ to.

limit
query
numberOpcional

1–100 (20 por defecto).

startingAfter
query
stringOpcional

Cursor: un id público pi_… de la página anterior.

Respuestas

  • HTTP 200Lista con cursor.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 422invalid_statusstatus no es un valor permitido.
  • HTTP 422invalid_sourcesource no es un valor permitido.
  • HTTP 422invalid_fromfrom no es una fecha ISO-8601 válida.
  • HTTP 422invalid_toto no es una fecha ISO-8601 válida.
  • HTTP 422invalid_limitlimit no es un entero entre 1 y 100.
  • HTTP 422invalid_cursorstartingAfter no es el id (pi_…) de un payin de tu comercio.
GET/payins
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
}

GET

Consultar un payin

/api/v1/payins/{payinId}

Detalle por id público pi_…. Scope payins:read.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

payinId
path
stringObligatorio

Id público (pi_…).

Respuestas

  • HTTP 200Detalle.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404payin_not_foundNo existe o no pertenece a tu comercio.
GET/payins/{payinId}
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"
}