Get a deposit & statuses

Get a deposit

Reads one of your deposits: its status, amounts, payer, payment details, card and reversals. Use it to confirm a notification, to recover after a timeout, or to reconcile.

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

Authentication	HTTP Basic (api_key:api_secret)
Moves money	No
{reference}	The deposit’s reference, your external_identifier, or the deposit id.

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

Response 200

The same deposit object Create a deposit returns. Example of a completed card deposit charged in USD (values illustrative):

{
  "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": "…"
}

Field	Description
status	See Deposit statuses.
details.invoice_*	The invoice your customer saw. For card options charged in USD, this is the local-currency estimate.
details.charged_amount, details.charged_currency	What your customer was actually charged. Same figure as amount / currency in the notification. For card options charged in USD, this is the USD amount.
card	network and last4 of the card that paid, or null.
reversals.refunds[]	Voids and refunds of the deposit: intent (void/refund), amount, reason, status, requested_at, processed_at…
reversals.disputes[]	Card disputes on the deposit, if any.

A deposit of another account and an unknown reference both answer 404.

Deposit statuses

Status	Final	Meaning
ONHOLD	No	Created, about to be sent to the payment network.
PROCESSING	No	Waiting for your customer to pay. A card deposit stays here while your customer retries after a declined card.
INREVIEW	No	The customer’s document could not be verified automatically; the deposit waits for a manual review, without a payment link.
COMPLETED	Yes	Paid. The net amount is credited to your Cashela account.
DECLINED	Yes	The payment was rejected. Nothing was charged.
CANCELLED	Yes	Cancelled, or expired before it was paid. Nothing was charged.
FAILED	Yes	The deposit could not be created with the payment network. Nothing was charged.
REVERSED	Yes	A COMPLETED card deposit whose money went back in full: a full void, a full refund, or partial refunds adding up to the full amount.

Good to know:

• A deposit that expires is reported as CANCELLED. There is no EXPIRED status.
• A partial refund leaves the deposit COMPLETED; its detail is in reversals.refunds.
• Notifications are sent when a deposit reaches COMPLETED, DECLINED or CANCELLED, and again when a void or refund reverses it (REVERSED, or COMPLETED after a partial refund). See Webhooks.
• Reconcile money only on COMPLETED and REVERSED.

Voids and refunds (card deposits)

You can give the money of a card deposit back to the card through the API. Voids and refunds are available for card deposits only; any other deposit is refused with 422 and nothing moves.

Endpoint	When	Amount
POST /api/v1/pay-in/transactions/{reference}/void	Before the card charge settles	Always the full amount
POST /api/v1/pay-in/transactions/{reference}/refund	After the card charge settles	Full (no amount) or partial (amount)

Both move money, are idempotent, and are limited to 12 requests per minute.

Request body (optional)

Field	Type	Description
reason	string (≤ 255)	Your reason, kept with the record.
amount	string	Refund only. Partial amount of the principal, as a decimal string with up to two decimals (for example "2.50"). Must not be 0. Omit it for a full refund. Ignored on a void.

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" }'

Response 200

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

wallet.reversed is the amount taken back from your Cashela balance, as a decimal string. notification.status tells you whether the notification was queued.

Fees on voids and refunds

• Full void or full refund: the whole charge goes back to the card. Cashela keeps its fee, so the amount taken back from your Cashela balance is the principal plus the Cashela fee: you absorb the fee. If your available balance does not cover it, the difference is recovered from your next settlements.
• Partial refund: the card gets back the amount you refund; the fee is kept.
• Your commercial agreement with Cashela may set other terms.

Rules and errors

HTTP	Code	When
403	PARTNER_PAYIN_REFUNDS_DISABLED	Card voids and refunds are temporarily not available. Nothing moved; retry later or contact support.
409	PARTNER_PAYIN_PARTIAL_REFUND_DECLINED	The card processor did not accept the partial refund. A partial refund needs a settled charge: retry after settlement, or void instead.
409	PARTNER_PAYIN_DEPOSIT_ALREADY_REVERSED	Void of a deposit already fully reversed. Nothing moves and no notification is sent.
409	PARTNER_PAYIN_REFUND_IN_PROGRESS	Another refund of this deposit is in progress. Retry shortly.
409	PARTNER_PAYIN_DEPOSIT_CHARGED_BACK	The deposit was charged back; it cannot be refunded.
422	PARTNER_PAYIN_REVERSAL_NOT_SUPPORTED	The deposit is not a card deposit. Nothing moves. Contact support for other methods.
422	PARTNER_PAYIN_REFUND_EXCEEDS_ORIGINAL	The refund would exceed what is left refundable (partials never exceed the principal), or the deposit is already fully reversed.
422	PARTNER_PAYIN_REFUND_PARTIALLY_REFUNDED	A full refund after a partial one. Refund the remaining amount explicitly with amount.
422	PARTNER_PAYIN_INVALID_REVERSAL_AMOUNT	The amount is not positive.
422	PARTNER_PAYIN_PARTIAL_REFUND_UNSUPPORTED	A partial refund is not supported for this deposit.
404	—	Unknown reference, or a deposit of another account.

After a full reversal the deposit reads REVERSED; after a partial refund it stays COMPLETED. In both cases you receive a notification with X-Cashela-Event set to partner.payin.transaction.voided or partner.payin.transaction.refunded.