Consultar un depósito y estados

Consultar un depósito

Lee uno de tus depósitos: estado, importes, pagador, datos de pago, tarjeta y reversiones. Úsalo para confirmar una notificación, recuperarte de un timeout o conciliar.

GET/api/v1/pay-in/transactions/{reference}


Autenticación	HTTP Basic (`api_key:api_secret`)
Mueve dinero	No
`{reference}`	La `reference` del depósito, tu `external_identifier` o el `id` del depósito.

curl https://sandbox-api.cashela.com/api/v1/pay-in/transactions/210000000000 \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Accept: application/json"

Respuesta `200`

El mismo objeto de depósito que devuelve Crear un depósito. Ejemplo de un depósito con tarjeta completado y cobrado en USD (valores ilustrativos):

{
  "success": true,
  "data": {
    "id": "1048577",
    "reference": "210000000001",
    "external_identifier": "order-2026-0002",
    "status": "COMPLETED",
    "status_message": null,
    "details": {
      "invoice_number": "INV-0002",
      "invoice_description": "Order 2026-0002",
      "invoice_country": "MEX",
      "invoice_currency": "MXN",
      "invoice_rate": 18.44,
      "invoice_fee": 0,
      "invoice_tax": 0,
      "invoice_amount": 92.18,
      "customer": { "first_name": "María", "last_name": "Pérez", "email": "maria.perez@example.com" },
      "paying": { "method": "Credit Card", "code": "international-credit-debit-card-visa", "name": "international-credit-debit-card-visa" },
      "charged_amount": 5,
      "charged_currency": "USD"
    },
    "card": { "network": "visa", "last4": "4242" },
    "reversals": { "refunds": [], "disputes": [] }
  },
  "message": "…"
}

Campo	Descripción
`status`	Ver Estados del depósito.
`details.invoice_*`	La factura que vio tu cliente. En opciones de tarjeta que cobran en USD es la estimación en moneda local.
`details.charged_amount`, `details.charged_currency`	Lo que realmente se cobró a tu cliente. La misma cifra que `amount` / `currency` en la notificación. En opciones de tarjeta que cobran en USD es el importe en USD.
`card`	`network` y `last4` de la tarjeta que pagó, o `null`.
`reversals.refunds[]`	Anulaciones y reembolsos del depósito: `intent` (`void`/`refund`), `amount`, `reason`, `status`, `requested_at`, `processed_at`…
`reversals.disputes[]`	Disputas de tarjeta sobre el depósito, si las hay.

Un depósito de otra cuenta y una referencia desconocida responden igual: 404.

Estados del depósito

Estado	Final	Significado
`ONHOLD`	No	Creado, a punto de enviarse a la red de pago.
`PROCESSING`	No	Esperando a que tu cliente pague. Un depósito con tarjeta sigue aquí mientras tu cliente reintenta tras una tarjeta rechazada.
`INREVIEW`	No	El documento del cliente no se pudo verificar automáticamente; el depósito espera una revisión manual, sin enlace de pago.
`COMPLETED`	Sí	Pagado. El importe neto se acredita en tu cuenta Cashela.
`DECLINED`	Sí	El pago fue rechazado. No se cobró nada.
`CANCELLED`	Sí	Cancelado, o vencido antes de pagarse. No se cobró nada.
`FAILED`	Sí	No se pudo crear el depósito con la red de pago. No se cobró nada.
`REVERSED`	Sí	Un depósito con tarjeta `COMPLETED` cuyo dinero se devolvió por completo: anulación total, reembolso total, o reembolsos parciales que suman el importe completo.

Conviene saber:

Un depósito que vence se informa como CANCELLED. No existe el estado EXPIRED.
Un reembolso parcial deja el depósito en COMPLETED; su detalle está en reversals.refunds.
Se envían notificaciones cuando un depósito llega a COMPLETED, DECLINED o CANCELLED, y otra vez cuando una anulación o un reembolso lo revierte (REVERSED, o COMPLETED tras un reembolso parcial). Ver Webhooks.
Concilia dinero solo en COMPLETED y REVERSED.

Anulaciones y reembolsos (depósitos con tarjeta)

Puedes devolver a la tarjeta el dinero de un depósito con tarjeta a través de la API. Las anulaciones y los reembolsos están disponibles solo para depósitos con tarjeta; cualquier otro depósito se rechaza con 422 y no se mueve nada.

Endpoint	Cuándo	Importe
`POST /api/v1/pay-in/transactions/{reference}/void`	Antes de que se liquide el cobro con tarjeta	Siempre el importe completo
`POST /api/v1/pay-in/transactions/{reference}/refund`	Después de que se liquide el cobro con tarjeta	Total (sin `amount`) o parcial (con `amount`)

Ambos mueven dinero, son idempotentes y están limitados a 12 peticiones por minuto.

Cuerpo de la petición (opcional)

Campo	Tipo	Descripción
`reason`	string (≤ 255)	Tu motivo, que se guarda con el registro.
`amount`	string	Solo reembolso. Importe parcial del principal, como texto decimal con hasta dos decimales (por ejemplo `"2.50"`). No puede ser `0`. Omítelo para un reembolso total. En la anulación se ignora.

curl -X POST https://sandbox-api.cashela.com/api/v1/pay-in/transactions/210000000001/refund \
  -u "$CASHELA_API_KEY:$CASHELA_API_SECRET" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{ "reason": "Customer returned the item", "amount": "2.50" }'

Respuesta `200`

{
  "success": true,
  "data": {
    "reference": "210000000001",
    "intent": "refund",
    "processor": { "status": "…" },
    "wallet": { "status": "…", "reversed": "2.50" },
    "notification": { "status": "queued" }
  },
  "message": "…"
}

wallet.reversed es el importe que se retira de tu saldo en Cashela, como texto decimal. notification.status indica si la notificación quedó en cola.

Comisiones en anulaciones y reembolsos

Anulación total o reembolso total: se devuelve a la tarjeta todo el cargo. Cashela conserva su comisión, así que lo que se retira de tu saldo en Cashela es el principal más la comisión de Cashela: tú asumes la comisión. Si tu saldo disponible no lo cubre, la diferencia se recupera de tus próximas liquidaciones.
Reembolso parcial: la tarjeta recibe el importe que reembolsas; la comisión se conserva.
Tu acuerdo comercial con Cashela puede fijar otras condiciones.

Reglas y errores

HTTP	Código	Cuándo
`403`	`PARTNER_PAYIN_REFUNDS_DISABLED`	Las anulaciones y reembolsos con tarjeta no están disponibles temporalmente. No se movió nada; reintenta más tarde o contacta con soporte.
`409`	`PARTNER_PAYIN_PARTIAL_REFUND_DECLINED`	El procesador de la tarjeta no aceptó el reembolso parcial. Un reembolso parcial necesita un cobro liquidado: reintenta tras la liquidación, o anula.
`409`	`PARTNER_PAYIN_DEPOSIT_ALREADY_REVERSED`	Anulación de un depósito ya revertido por completo. No se mueve nada y no se envía notificación.
`409`	`PARTNER_PAYIN_REFUND_IN_PROGRESS`	Hay otro reembolso de este depósito en curso. Reintenta en unos momentos.
`409`	`PARTNER_PAYIN_DEPOSIT_CHARGED_BACK`	El depósito tuvo un contracargo; no se puede reembolsar.
`422`	`PARTNER_PAYIN_REVERSAL_NOT_SUPPORTED`	El depósito no es con tarjeta. No se mueve nada. Contacta con soporte para otros métodos.
`422`	`PARTNER_PAYIN_REFUND_EXCEEDS_ORIGINAL`	El reembolso superaría lo que queda por reembolsar (los parciales nunca superan el principal), o el depósito ya está revertido por completo.
`422`	`PARTNER_PAYIN_REFUND_PARTIALLY_REFUNDED`	Un reembolso total después de uno parcial. Reembolsa el resto de forma explícita con `amount`.
`422`	`PARTNER_PAYIN_INVALID_REVERSAL_AMOUNT`	El `amount` no es positivo.
`422`	`PARTNER_PAYIN_PARTIAL_REFUND_UNSUPPORTED`	Este depósito no admite reembolso parcial.
`404`	—	Referencia desconocida, o un depósito de otra cuenta.

Tras una reversión total el depósito pasa a REVERSED; tras un reembolso parcial sigue en COMPLETED. En ambos casos recibes una notificación con X-Cashela-Event igual a partner.payin.transaction.voided o partner.payin.transaction.refunded.

Consultar un depósito y estados