Pix Transfer

The full flow

Walk through the four stages: enter a key (or scan a QR), confirm the recipient returned by your resolver, enter the amount + an optional description, and view the receipt. The preview below is fully interactive — try 12345678909 as a CPF or scan the simulated QR.

Installation

npx ajaxui add pix-transfer

Pix Key Input

Single-input control that detects the key type as the user types and applies the right mask. Exposes detectPixKeyType() and formatPixKey() helpers for custom validation.

type PixKeyType = "cpf" | "cnpj" | "email" | "phone" | "random" | "emv" | "unknown"

detectPixKeyType("123.456.789-09")        // "cpf"
detectPixKeyType("[email protected]")      // "email"
detectPixKeyType("+5511999999999")        // "phone"
detectPixKeyType("a3f5...")               // "random" (32-36 hex chars)
detectPixKeyType("00020126...")           // "emv"  (Pix Copia e Cola)
formatPixKey("12345678909", "cpf")        // "123.456.789-09"

Recipient Preview

Shows the resolver output. By convention, the masked legal name returned by the SPI (e.g. "MAR*** DA S*** SI*****") is used verbatim — do not reveal full names client-side.

QR Scanner

Uses the browser's native BarcodeDetector when available (Chrome, Edge, mobile Safari 17+) with an "Upload image" fallback for unsupported browsers. The preview here uses the simulate button to avoid a camera permission prompt.

Receipt

End-state for a completed Pix. Shows recipient, amount, transaction ID, and the end-to-end ID returned by the BACEN SPI rail. Built-in Share and Download actions.

API surface

// Primitives
<PixKeyInput value onValueChange onSubmit ... />
<PixQrScanner onScan onError ... />
<PixRecipientPreview recipient loading />
<PixConfirmation recipient amount onAmountChange ... />
<PixReceipt tx onShare onDownload />

// Orchestrator
<PixTransferFlow
  currency="BRL" locale="pt-BR"
  resolveKey={async (key) => recipient}
  onSubmit={async (payload) => transactionSummary}
  initialMode="key"           // or "qr"
  maxAmount={5000}            // hard cap on amount input
  fee={0}                     // shown on the confirm step
/>

// Helpers
detectPixKeyType(s: string): PixKeyType
formatPixKey(s: string, t: PixKeyType): string

// Types
type PixKeyType = "cpf" | "cnpj" | "email" | "phone" | "random" | "emv" | "unknown"
interface PixRecipient { name; taxId; taxIdType; institution; branch?; accountType?; keyType; keyValue }
interface PixTransactionSummary { id; amount; currency; recipient; sender?; description?; date; endToEndId?; status }

Accessibility & safety

• The amount input uses type="number" with inputMode="decimal" for the right mobile keyboard.
• The flow exposes a numbered stepper (role="list") so screen readers announce progress.
• The confirm button is disabled while the amount is 0 or a send is in flight — re-submits are impossible.
• Mask the recipient's legal name and tax ID exactly as returned by your resolver. Never reveal more than the SPI does.
• Pix keys are sensitive — do not log them to analytics or error trackers in plain text.