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@example.com",
    "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"

​
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

​
Timeout Handling

If the request results in a timeout (connection interrupted before response), the order may have been processed successfully even without you receiving confirmation. Recommended flow in case of timeout:
  1. Wait 10-20 seconds after timeout
  2. Query by the externalId you sent:
curl -X GET "https://api.owem.com.br/v4/i/ledger/external-id/{externalId}" \
  -u "API_KEY:API_SECRET"
  1. Interpret the result:
    • 200 with data: The order was processed successfully, use the returned endToEndId
    • 400 with “Entry not found”: The order is still being processed or didn’t reach the system
    • If after 2-3 minutes it still returns “Entry not found”, the order was not received and you can try again
Never resend immediately after timeout. Always query by externalId first to avoid duplicate payments.
The webhook will be sent normally even in timeout cases on the original request. Use webhooks as the primary source of confirmation.

​
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