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

# Deposit Review And Recovery

> Handle customer-address deposits that cannot be safely matched to an active order.

# Deposit review and recovery

PayChain records detected customer-address deposits even when an Auto Deposit Intent cannot be safely matched. These deposits appear in the business dashboard and are excluded from withdrawal capacity until they are assigned, accepted, or refunded.

Only `invoice.paid` is safe for automatic order fulfillment. A `deposit.review_required` event is informational and always includes `safeToFulfill: false`.

## Review webhook

```json theme={null}
{
  "event": "deposit.review_required",
  "data": {
    "depositId": "4e29e1c7-...",
    "customerId": "353429c3-...",
    "externalCustomerRef": "customer_123",
    "chain": "sol",
    "networkId": "sol-mainnet",
    "asset": {
      "token": "USDC",
      "tokenMint": "EPjFWdd5...",
      "canonicalAssetId": "sol:USDC:EPjFWdd5...",
      "supported": true
    },
    "amount": {
      "raw": "5000000",
      "display": "5",
      "decimals": 6
    },
    "transaction": {
      "txHash": "5x...",
      "operationIndex": 0,
      "fromAddress": "8A...",
      "toAddress": "DR..."
    },
    "assignment": {
      "status": "review_required_amount_mismatch",
      "safeToFulfill": false,
      "expectedIntent": {
        "id": "a16d...",
        "externalOrderId": "order_789",
        "expectedAmountRaw": "6000000"
      }
    },
    "resolutionStatus": "review_required",
    "safeToFulfill": false
  }
}
```

Common assignment states are `unassigned_no_intent`, `review_required_asset_mismatch`, `review_required_amount_mismatch`, `review_required_ambiguous`, `review_required_unsupported_asset`, and `review_required_non_positive_net`. A non-positive settlement remains held and can only be refunded.

## List deposits needing review

```bash theme={null}
curl "https://api.paychainhq.io/api/v1/businesses/$BUSINESS_ID/deposits?status=review_required" \
  -H "X-API-Key: $PAYCHAIN_API_KEY"
```

## Assign to an intent

Assignment requires an active intent for the same business, customer, network, asset, and amount tolerance. A successful assignment creates the paid invoice and emits both `deposit.assigned` and `invoice.paid`.

```bash theme={null}
curl -X POST "https://api.paychainhq.io/api/v1/businesses/$BUSINESS_ID/deposits/$DEPOSIT_ID/assign" \
  -H "X-API-Key: $PAYCHAIN_API_KEY" \
  -H "Idempotency-Key: deposit_assign_$DEPOSIT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "intentId": "'$INTENT_ID'" }'
```

## Accept without an order

Acceptance applies normal payment fees and makes the merchant net amount available without attaching order identity. It emits `deposit.accepted`, not `invoice.paid`.

```bash theme={null}
curl -X POST "https://api.paychainhq.io/api/v1/businesses/$BUSINESS_ID/deposits/$DEPOSIT_ID/accept" \
  -H "X-API-Key: $PAYCHAIN_API_KEY" \
  -H "Idempotency-Key: deposit_accept_$DEPOSIT_ID"
```

## Refund the sender

Refunds return the gross token amount to the sender observed on-chain. A custom destination must use the normal withdrawal flow. Programmatic refunds require a payout API key whose policy permits the asset, network, amount, and sender destination.

```bash theme={null}
curl -X POST "https://api.paychainhq.io/api/v1/businesses/$BUSINESS_ID/deposits/$DEPOSIT_ID/refund" \
  -H "X-API-Key: $PAYCHAIN_PAYOUT_API_KEY" \
  -H "Idempotency-Key: deposit_refund_$DEPOSIT_ID"
```

PayChain emits `deposit.refund_pending`, followed by `deposit.refunded` or `deposit.refund_failed`. A failed refund returns the deposit to the review queue.

## Idempotency

Every resolution mutation requires `Idempotency-Key`. Reuse the same key when retrying the same action after a timeout. Do not use one key for different deposits or resolution actions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.