For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
StatusDashboard
  • Getting Started
    • Introduction
    • Authentication
    • Rate Limits
    • Error Handling
  • Guides
    • Cash-In (Receiving Payments)
    • Cash-Out (Sending Payments)
    • PIX Keys Management
    • Webhooks Integration
    • MED (Special Returns)
  • API Reference
LogoLogo
StatusDashboard
On this page
  • Cash-Out (Sending Payments)
  • Flow 1 — Via PIX Key
  • Example: Payment via Phone Number
  • Flow 2 — Via Bank Details
  • Flow 3 — Via QR Code (Two-Step)
  • Step 1 — Decode the QR Code
  • Step 2 — Send the Payment
  • Optional Fields (All Flows)
  • Important Headers
  • Checking Payment Status
  • Transaction Statuses
  • Best Practices
Guides

Cash-Out (Sending Payments)

Was this page helpful?
Edit this page
Previous

PIX Keys Management

Next
Built with

Cash-Out (Sending Payments)

Cash-Out endpoints allow you to send PIX payments to any bank account in Brazil. There are three available flows depending on the information you have about the recipient.

Cash-Out endpoints use Bearer Token authentication. Always include the X-Idempotency-Key header to prevent duplicate payments.

Flow 1 — Via PIX Key

Send a payment directly using the recipient’s PIX key. The system resolves the key to obtain the recipient’s bank details automatically.

$curl -X POST https://api.brzip.com.br/api/v1/pix/cash-out \
>  -H "Authorization: Bearer <your-jwt>" \
>  -H "Content-Type: application/json" \
>  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
>  -d '{
>    "amount": "150.00",
>    "pix_key": "12345678901",
>    "pix_key_type": "CPF",
>    "description": "Payment via PIX key",
>    "reference": "pay-key-001"
>  }'

Required fields:

FieldTypeDescription
amountstringPayment amount in BRL (e.g., "150.00")
pix_keystringRecipient’s PIX key
pix_key_typestringKey type: CPF, CNPJ, EMAIL, PHONE, or EVP

Example: Payment via Phone Number

$curl -X POST https://api.brzip.com.br/api/v1/pix/cash-out \
>  -H "Authorization: Bearer <your-jwt>" \
>  -H "Content-Type: application/json" \
>  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440099" \
>  -d '{
>    "amount": "75.00",
>    "pix_key": "+5531999999999",
>    "pix_key_type": "PHONE",
>    "description": "Payment via phone number",
>    "reference": "pay-phone-001"
>  }'

Flow 2 — Via Bank Details

Send a payment using the recipient’s bank account details directly, without needing a PIX key.

$curl -X POST https://api.brzip.com.br/api/v1/pix/cash-out \
>  -H "Authorization: Bearer <your-jwt>" \
>  -H "Content-Type: application/json" \
>  -H "X-Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001" \
>  -d '{
>    "amount": "2500.00",
>    "receiver_name": "Acme Corp Ltda",
>    "receiver_document": "12345678000190",
>    "receiver_ispb": "00000000",
>    "receiver_branch": "0001",
>    "receiver_account": "98765432",
>    "receiver_account_type": "checking",
>    "description": "Supplier invoice #4521",
>    "reference": "pay-bank-001"
>  }'

Required fields:

FieldTypeDescription
amountstringPayment amount in BRL (e.g., "2500.00")
receiver_namestringRecipient’s full name or company name
receiver_documentstringRecipient’s CPF (11 digits) or CNPJ (14 digits)
receiver_ispbstringRecipient’s bank ISPB code (8 digits)
receiver_branchstringRecipient’s branch number
receiver_accountstringRecipient’s account number
receiver_account_typestringAccount type: checking, savings, salary, or payment

Flow 3 — Via QR Code (Two-Step)

The recommended approach for QR Code payments. First decode the QR Code, then send the payment using the pre-decoded data.

Step 1 — Decode the QR Code

$curl -X POST https://api.brzip.com.br/api/v1/pix/qrcode/decode \
>  -H "Authorization: Bearer <your-jwt>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "br_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-1234-567890123456..."
>  }'

Response:

1{
2  "success": true,
3  "qr_code_type": "static",
4  "pix_key": "26318747000186",
5  "amount": "10.00",
6  "receiver_name": "John Doe",
7  "receiver_ispb": "00000000",
8  "receiver_participant_name": "BCO DO BRASIL S.A.",
9  "end_to_end_id": "E54811417202603071234abcdef123456"
10}

Step 2 — Send the Payment

Use the end_to_end_id from the decode response as the X-Pix-Lookup-E2E header:

$curl -X POST https://api.brzip.com.br/api/v1/pix/cash-out \
>  -H "Authorization: Bearer <your-jwt>" \
>  -H "Content-Type: application/json" \
>  -H "X-Idempotency-Key: 770e8400-e29b-41d4-a716-446655440002" \
>  -H "X-Pix-Lookup-E2E: E54811417202603071234abcdef123456" \
>  -d '{
>    "amount": "10.00",
>    "description": "QR Code payment",
>    "reference": "pay-qr-001"
>  }'

Required fields:

FieldTypeDescription
amountstringPayment amount in BRL

Required header:

HeaderDescription
X-Pix-Lookup-E2Eend_to_end_id obtained from POST /api/v1/pix/qrcode/decode

Optional Fields (All Flows)

FieldTypeDescription
descriptionstringPayment description
referencestringYour internal reference ID
metadataobjectCustom key-value metadata

Important Headers

HeaderRequiredDescription
AuthorizationYesBearer <jwt>
X-Idempotency-KeyRecommendedUUID to prevent duplicate payments
X-Pix-Lookup-E2EFlow 3 onlyEndToEndID from QR Code decode

Checking Payment Status

Query the status of a Cash-Out by its transaction ID:

$curl -X GET https://api.brzip.com.br/api/v1/pix/cash-out/<cash-out-id> \
>  -H "Authorization: Bearer <your-jwt>"

Transaction Statuses

StatusDescription
processingPayment is being processed
completedPayment was successful
failedPayment failed
returnedPayment was returned by the recipient’s bank

Best Practices

  1. Always use idempotency keys to prevent duplicate payments in case of network issues.
  2. Use the two-step flow for QR Code payments — it allows you to show recipient details before confirming the payment.
  3. Check your balance before initiating large payments using GET /api/v1/pix/balance.
  4. Monitor webhooks for real-time status updates on your payments.
  5. Verify limits — ensure the payment amount is within your configured limits using GET /api/v1/pix/limits.