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

{
  "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

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.

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.

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.

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.

Start here

Developers

Go live

Deposit Review And Recovery

Deposit review and recovery

Review webhook

List deposits needing review

Assign to an intent

Accept without an order

Refund the sender

Idempotency

​Deposit review and recovery

​Review webhook

​List deposits needing review

​Assign to an intent

​Accept without an order

​Refund the sender

​Idempotency

Deposit review and recovery

Review webhook

List deposits needing review

Assign to an intent

Accept without an order

Refund the sender

Idempotency