PIX (Brazil)
PIX is the instant payment ecosystem created and managed by Banco Central do Brasil. Launched in November 2020, it enables real-time money transfers and payments 24/7/365 between any of the 700+ participating institutions, using flexible key types instead of traditional bank account numbers.
mcp2p exposes PIX as three MCP tools. Enable the rail by including "pix" in your rails array when calling createMcp2pServer.
Overview
- Settlement time: Under 10 seconds in normal conditions. Final in real time.
- Operating hours: 24/7/365 — PIX never closes.
- Currency: Brazilian real (BRL). Amounts in centavos (minor units).
- Routing: Via PIX key (CPF, CNPJ, email, phone, or EVP). No bank account number needed.
- Limits: Banco Central imposes default limits; your bank may apply additional restrictions. Night-time limits are lower by default.
Available tools
pix_send_payment
Send a PIX instant payment to any registered PIX key. Requires 2FA authorization.
| Parameter | Type | Required | Description |
|---|---|---|---|
| pixKey | string | Yes | Recipient PIX key. The SDK auto-detects the key type. |
| amount | number | Yes | Amount in centavos (minor units). E.g. 10000 = BRL 100.00 |
| description | string | No | Payment description visible to the recipient (max 140 chars) |
| verificationCode | string | No | 6-digit OTP from Twilio Verify. Omit on first call to trigger SMS. |
pix_check_status
Check the current status of a PIX payment by its end-to-end ID (E2EID).
| Parameter | Type | Required | Description |
|---|---|---|---|
| e2eId | string | Yes | End-to-end ID (E2EID) returned by pix_send_payment |
pix_request_refund
Request a PIX Devolução (refund) for a completed payment. Requires 2FA authorization.
| Parameter | Type | Required | Description |
|---|---|---|---|
| e2eId | string | Yes | E2EID of the original payment |
| amount | number | No | Amount to refund in centavos. Defaults to full amount if omitted. |
| reason | string | Yes | Refund reason: "FRAUD", "OPERATIONAL_FAULT", or "CUSTOMER_REQUEST" |
| verificationCode | string | No | 6-digit OTP. Omit on first call to trigger SMS. |
PIX key types
The SDK auto-detects the PIX key type from the value passed in the pixKey parameter. You do not need to specify the type explicitly. Detection runs in this priority order: CPF, CNPJ, phone (E.164), UUID v4 (EVP), then email.
| Type | Format | Example | Validation | Notes |
|---|---|---|---|---|
| CPF | 11 digits | 12345678909 | Modulus-11 algorithm with two check digits | Brazilian individual tax ID. Most common key type for individuals. |
| CNPJ | 14 digits | 11222333000181 | Modulus-11 algorithm with two check digits | Brazilian company registration number. |
| user@domain | user@example.com | Standard RFC 5322 email format | Must be registered as a PIX key with the recipient's bank. | |
| Phone | +55XXXXXXXXXXX | +5511999998888 | +55 country code, 10–11 digits after code | Brazilian mobile number in E.164 format. |
| EVP | UUID v4 | 123e4567-e89b-12d3-a456-426614174000 | Standard UUID v4 format | Random key (Chave Aleatória). Auto-generated by the payer's bank. |
PIX_INVALID_KEY before any SMS is sent. Pass CPF and CNPJ as digit-only strings (no dots, dashes, or slashes).Code example
// User: "Send BRL 150 to CPF 123.456.789-09"
// ── Turn 1: AI calls tool without verification code ──────────────────────────
// Tool call: pix_send_payment
// {
// pixKey: "12345678909", // CPF digits only — SDK auto-detects as CPF
// amount: 15000, // BRL 150.00 in centavos
// description: "Lunch split"
// }
//
// SDK response:
// {
// status: "2fa_required",
// message: "Verification code sent via SMS."
// }
// ── Turn 2: User provides code ────────────────────────────────────────────────
// Tool call: pix_send_payment (same params + verificationCode)
// {
// pixKey: "12345678909",
// amount: 15000,
// description: "Lunch split",
// verificationCode: "583921"
// }
//
// SDK response:
// {
// status: "success",
// e2eId: "E90400888202401261458300000000001",
// amount: 15000,
// currency: "BRL",
// settledAt: "2024-01-26T14:58:06Z"
// }Error codes
| Code | Description |
|---|---|
| PIX_INVALID_KEY | PIX key fails format or checksum validation |
| PIX_KEY_NOT_FOUND | PIX key is not registered in the DICT (Diretório de Identificadores) |
| PIX_LIMIT_EXCEEDED | Amount exceeds the Banco Central daily or per-transaction limit |
| PIX_INSUFFICIENT_FUNDS | Source account has insufficient balance |
| PIX_RECIPIENT_UNAVAILABLE | The recipient's institution is temporarily unavailable in the PIX network |
| PIX_TIMEOUT | Payment timed out waiting for Banco Central confirmation |
| PIX_DUPLICATE_E2EID | A payment with this E2EID already exists |
See the Error Codes page for the complete reference.
Next steps
- SPEI (Mexico) — Real-time MXN transfers via BANXICO
- PSE (Colombia) — NIT/CC validation and Colombian ACH payments
- Two-Factor Auth — Full 2FA configuration and security details