> ## 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.

# Receiving Crypto

> How CashWeb receives seller deposits and how partners should track them.

CashWeb receives crypto by generating a unique deposit address for each transaction. The seller sends funds to that address on the exact network specified when the transaction was created, and CashWeb monitors the deposit until it is confirmed.

## Deposit Flow

```mermaid theme={null}
sequenceDiagram
    participant Partner as "Partner Backend"
    participant CashWeb as "CashWeb API"
    participant Seller as "Seller"
    participant Chain as "Blockchain"
    participant Webhook as "Partner Webhook Endpoint"

    Partner->>CashWeb: "POST /transactions"
    CashWeb-->>Partner: "id, deposit_address, network, expires_at"
    Partner-->>Seller: "Show deposit address and network"
    Seller->>Chain: "Send crypto to deposit address"
    Chain-->>CashWeb: "Deposit detected"
    CashWeb-->>Webhook: "deposit.detected"
    Chain-->>CashWeb: "Required confirmations reached"
    CashWeb-->>Webhook: "deposit.confirmed"
```

## What Partners Need To Do

1. Create a transaction with `POST /transactions`.
2. Persist the returned `id`, `merchant_reference`, `deposit_address`, `network`, and `expires_at`.
3. Show the seller the deposit address and the exact network to use.
4. Wait for either partner webhooks or a polling read on the transaction.
5. Treat `deposit.confirmed` or the latest transaction state as the signal that CashWeb has received the crypto successfully.

## What CashWeb Returns

Successful transaction creation returns the fields needed for receiving crypto:

* `id`
* `deposit_address`
* `network`
* `expires_at`
* `status`
* `amount`
* `crypto_amount`
* `crypto_currency`

The initial transaction status is normally `awaiting_deposit`.

Use `id` as the transaction identifier from `POST /transactions`.
Only use `transaction_id` in endpoints or payloads that explicitly require that field name, such as the sandbox simulator request body.

## Important Rules

* The seller must send funds to the exact `deposit_address` returned for that transaction.
* The seller must use the exact `network` returned for that transaction.
* Sending funds on the wrong network can result in lost funds.
* Deposit windows expire after 30 minutes unless the transaction progresses first.
* Deposit addresses are transaction-specific. Do not reuse an old address for a new transaction.

## How CashWeb Confirms Receipt

CashWeb tracks the deposit lifecycle in two stages:

* `deposit.detected`: a matching blockchain deposit was seen and is waiting for confirmations
* `deposit.confirmed`: required confirmations were reached and CashWeb can proceed with the rest of the transaction lifecycle

You can consume these updates through:

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

## Example

```bash theme={null}
curl -X POST "$BASE_URL/transactions" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -H "Idempotency-Key: tx-create-2026-0001" \
  -d '{
    "quote_id": "9f8ad58e-f8d5-4e4f-b3f2-f44eaf8f95d1",
    "network": "bep20",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }'
```

Example response fields:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "deposit_address": "0x9d8D32b6D7DfDdAb66f6a79b9dA8fA2E30A91B7a",
    "network": "bep20",
    "expires_at": "2026-02-12T12:30:00Z",
    "status": "awaiting_deposit"
  }
}
```

## Staging Note

When testing against staging, the current sandbox-supported deposit pair is:

* `crypto_currency`: `usdt`
* `network`: `bep20`

That restriction applies only to sandbox testing and keeps upstream address allocation efficient.