PIX payment (USDC → BRL)
The main use case. User scans a merchant's PIX QR (or types the key manually), confirms in USD, and Bridge streams BRL to the merchant.
Sequence
Screens
apps/mobile/app/pix/index.tsx— entry: Scan vs Manual.apps/mobile/app/pix/scan.tsx— expo-camera QR scan.apps/mobile/app/pix/manual.tsx— form entry.apps/mobile/app/pix/review.tsx— confirmation with USD equivalent.apps/mobile/app/pix/receipt.tsx— polls until terminal state.
Pricing math
packages/shared/src/pix/pricing.ts:
usdc = brl / rate * (1 + spreadBps / 10000)
With DEFAULT_GRINGO_SPREAD_BPS = 200, a £500-equivalent PIX payment lands the user ≈2% higher USDC debit; the extra is Bridge's developer_fee on the liquidation address.
Failure modes
| What broke | Where it surfaces |
|---|---|
| Invalid PIX key format | POST /pix/payments → 400 with per-type error message |
| Bridge rate unavailable | GET /pix/rate → 502 |
| Bridge liquidation address creation fails | POST /pix/payments → 502; no ledger row is created |
| USDC transfer fails on-chain | POST /transactions/:id/confirm → 400 with receipt reason |
| Drain fails at Bridge | Webhook drain_failed → pix_payment.status = failed |
| No drain webhook ever arrives | Payment stuck pending — see liquidation-addresses |