> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashweb.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> Create, recover, list, and cancel partner transactions with production-safe patterns.

## Transaction Create Modes

`POST /transactions` supports exactly one pricing mode:

1. Quote mode: provide `quote_id`.
2. Direct mode: provide `fiat_amount` + `crypto_currency` + `network`.

Do not send both modes together.

In direct mode, CashWeb uses the latest available market rate when the transaction is created and derives `crypto_amount`. Partners do not send `rate` or `crypto_amount`.

## Canonical Reference

`merchant_reference` is your partner-owned canonical identifier.

* Unique per partner (case-insensitive).
* Required for timeout recovery.
* Recommended as your primary reconciliation key.

## Expiry and Deadlines

* Quote validity: 120 seconds.
* Transaction deposit expiry: 30 minutes.

If a transaction is near expiry, fetch latest state before any user-facing action.

## Create Response Shape

Successful create responses include:

* `id`
* `deposit_address`
* `network`
* `expires_at`
* `status`
* `rate`
* `amount`
* `crypto_amount`
* `crypto_currency`
* `merchant_reference`
* `merchant_id`
* `terminal_id`

Example:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "deposit_address": "TXyz1234567890abcdef1234567890abcd",
    "network": "trc20",
    "expires_at": "2026-02-12T12:30:00Z",
    "status": "awaiting_deposit",
    "rate": "1615.00",
    "amount": "161500.00",
    "crypto_amount": "100.00",
    "crypto_currency": "usdt",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }
}
```

## Recovery Endpoints

* `GET /transactions/{id}`
* `GET /transactions/reference/{merchant_reference}`

Use reference-based recovery when your create call timed out and transaction ID is unknown.

## TSQ Response Shape

Transaction status query responses include deposit reconciliation fields:

* `crypto_currency`
* `crypto_amount`
* `rate`
* `amount`
* `created_at`
* `updated_at`
* `deposit_id`
* `deposit_status`
* `confirmations`
* `required_confirmations`
* `received_at`
* `confirmed_at`

## List Endpoint (Cursor-Only)

`GET /transactions` is cursor-based.

Use:

* `limit` (1..100)
* `cursor` from prior `next_cursor`

Never construct cursor values manually.

## Cancellation Rules

`POST /transactions/{id}/cancel` is idempotent with `Idempotency-Key`.

Cancellation is state-dependent. Non-cancellable states return `409 Conflict`.

## Seller Identification

`seller_phone` is optional partner metadata for seller linkage and reconciliation. Partner transaction creation is not blocked by KYC checks.