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

# Quickstart

> End-to-end partner integration flow with concrete request and recovery patterns.

## Integration Flow

This guide includes the end-to-end happy path. If you specifically want the deposit-handling part, see the dedicated `Receiving Crypto` guide in the docs navigation.

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

    opt "Quoted pricing"
        Partner->>CashWeb: "POST /quotes"
        CashWeb-->>Partner: "quote_id, expires_at"
    end

    Partner->>CashWeb: "POST /transactions"
    CashWeb-->>Partner: "id, deposit_address, rate, amount, crypto_amount"

    Seller->>CashWeb: "Send crypto to deposit address"
    CashWeb-->>Webhook: "deposit.detected / deposit.confirmed / terminal events"
    Partner->>CashWeb: "GET /transactions/{id} or /reference/{merchant_reference}"
    CashWeb-->>Partner: "Canonical transaction state"
```

## 1) Create Quote

Use exactly one amount mode (`crypto_amount` or `fiat_amount`).

When testing against staging (`https://api-staging.cashweb.cash`), use the current sandbox-supported pair:

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

```bash theme={null}
curl -X POST "$BASE_URL/quotes" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -d '{
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "network": "bep20"
  }'
```

Use the quote before `expires_at`.

## 2) Create Transaction

Always send:

* `merchant_reference` (canonical partner key)
* `Idempotency-Key` (safe retries)

Use either:

* Quote mode: `quote_id`
* Direct mode: `fiat_amount` + `crypto_currency` + `network`

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

Persist:

* `id`
* `merchant_reference`
* `deposit_address`
* `expires_at`
* `rate`
* `amount`
* `crypto_amount`
* `crypto_currency`
* `network`

## 3) Handle Timeouts and Recovery

If create request times out, recover by reference:

```bash theme={null}
curl -X GET "$BASE_URL/transactions/reference/order-4551" \
  -H "X-API-KEY: $API_KEY"
```

## 4) Process Webhooks

* Verify `X-CW-Webhook-Signature`.
* Deduplicate by webhook `id`.
* Upsert transaction status only when state progression is valid for your system.

For recovery:

* `GET /webhooks/events`
* `GET /webhooks/events/{event_id}`
* `POST /webhooks/events/{event_id}/replay`

## 5) Reconcile Periodically

Use list + revenue endpoints with fixed windows and cursors:

* `GET /transactions`
* `GET /revenue`

Do not rely on webhook delivery timing as the only source of truth.

## 6) Test Lifecycle Progression In Staging

Use the standalone sandbox simulator to trigger partner lifecycle events against a known transaction:

You must first create the transaction and then pass the returned transaction `id` as `transaction_id`.

```bash theme={null}
curl -X POST "https://api-staging.cashweb.cash/api/v1/partner/sandbox/simulate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $SANDBOX_API_KEY" \
  -d '{
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "event": "deposit.confirmed"
  }'
```