Skip to main content

​
Overview

The PIX OUT flow allows you to transfer funds from your Owem account to any bank account in Brazil using a PIX key.

​
Complete Flow

​
Step 1: Validate Balance

Before sending, check if there’s sufficient balance: 
curl -X GET "https://api.owem.com.br/v4/i/bank-accounts/{accountId}/balance" \
  -u "API_KEY:API_SECRET"

​
Step 2: Send Transfer

curl -X POST "https://api.owem.com.br/v4/i/bank-accounts/{accountId}/transfer/external" \
  -u "API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "[email protected]",
    "amount": 500.00,
    "description": "Supplier Payment #123",
    "externalId": "PAY-20251226-001"
  }'

​
Important Parameters

FieldDescription
pixKeyDestination PIX key (CPF, CNPJ, email, phone, random key)
amountAmount in BRL (> 0, two decimal places)
descriptionTransfer description (max 140 characters)
externalIdYour unique identifier for idempotency
Always send externalId to ensure idempotency. If the request fails and you retry, there won’t be duplication.

​
Step 3: Track Status

The initial response may come as processing. Use one of the options below to track: Configure webhook for pix_out:processing. The final status will be succeeded or failed. 
{
  "webhookId": "wh_abc123",
  "event": "pix_out:processing",
  "object": {
    "endToEndId": "E123456789...",
    "externalId": "PAY-20251226-001",
    "status": "succeeded",
    "grossAmount": 500.0,
    "feeAmount": 0.08,
    "netAmount": 500.08
  }
}

​
Option B: Direct Query

curl -X GET "https://api.owem.com.br/v4/i/bank-accounts/{accountId}/transfer/external/{endToEndId}" \
  -u "API_KEY:API_SECRET"

​
Option C: Ledger Query

# By externalId (your identifier)
curl -X GET "https://api.owem.com.br/v4/i/ledger/external-id/{externalId}" \
  -u "API_KEY:API_SECRET"

# By endToEndId (PIX identifier)
curl -X GET "https://api.owem.com.br/v4/i/ledger/end-to-end/{endToEndId}" \
  -u "API_KEY:API_SECRET"

​
Test Mode

To test without affecting real balance: 
{
  "pixKey": "[email protected]",
  "amount": 0.01,
  "description": "Test",
  "externalId": "TEST-001",
  "test": true,
  "testStatus": "succeeded"
}
Operations with test: true don’t affect balance, don’t generate Ledger entries, and don’t trigger real PIX integration.

​
Error Handling

HTTPCauseAction
400Invalid PIX keyCheck key format
404Account not foundVerify accountId
422Insufficient balanceCheck balance before sending
422Limit exceededCheck account limits
429Rate limitWait and retry

​
Best Practices

Ensures idempotency and facilitates reconciliation in your system.
Avoids 422 errors and improves user experience.
Don’t rely only on synchronous response. Configure webhooks to receive final status.
In case of timeout or 5xx error, implement retry with exponential backoff.
EventWhen it occurs
pix_out:processingTransfer registered/confirmed
pix_out:refunded_processingReturn initiated

​
Next Steps

Configure Webhooks

Receive real-time notifications

Reconciliation

Use the Ledger to reconcile