Escrow & Refunds

Escrow

Every payment through 402.md goes to an escrow wallet, not directly to the merchant. This enables refunds, dispute resolution, and buyer protection.

Buyer → $49.00 USDC → 402.md Escrow Wallet
                            ↓
                  Hold period (0-72h)
                            ↓
                  Settlement: $46.55 → Merchant (95%)
                             $2.45  → 402.md (5%)

Hold periods

Hold periods are customizable via the holdPeriodHours field (minimum 0h, maximum 7 days).

Settlement

After the hold period expires, funds are settled to the merchant:

• Frequency: daily cron job (configurable to DAILY, WEEKLY, or MONTHLY)
• Minimum: $10 default (transactions below this amount accumulate until the threshold is reached)
• Fee: 5% — the merchant receives 95% of every payment
• Proof: each settlement includes a txHash as on-chain proof of the USDC transfer

Refunds

Seller-initiated refund

The merchant can refund any transaction:

POST /api/v1/refunds
Content-Type: application/json
Authorization: Bearer sk_live_xxx

{
  "transactionId": "tx_abc123",
  "amount": "49.00",
  "reason": "Customer requested cancellation"
}

If the funds are still in escrow, the refund is instant. If already settled, the merchant's balance is debited.

Buyer refund request

A buyer can request a refund, which the merchant must approve:

POST /api/v1/refund-requests
Content-Type: application/json

{
  "transactionId": "tx_abc123",
  "reason": "Service not as described"
}

Merchant approval

POST /api/v1/refund-requests/:id/approve
Authorization: Bearer sk_live_xxx

Webhook events

Refund events are sent to your configured webhook URL:

{
  "event": "refund.completed",
  "transactionId": "tx_abc123",
  "refundTxHash": "0x...",
  "amount": "49.00"
}

{
  "event": "refund.requested",
  "transactionId": "tx_abc123",
  "reason": "Service not as described"
}

See the Webhooks page for all event types and delivery details.

No chargebacks

Unlike credit card payments, crypto payments are irreversible. There are no chargebacks. Refunds are a new transaction initiated by the merchant or via 402.md.

This is a significant advantage for merchants — chargeback fraud costs the industry ~$125B/year. With 402.md, merchants have full control over refund decisions.