BRZ API Documentation

What This API Does

PIX In (BRL → Crypto): Your users pay with PIX, receive crypto in their wallet
PIX Out (Crypto → BRL): Your users send crypto, receive BRL via PIX

Perfect for exchanges, wallets, payment processors, or any app handling Brazilian payments.

Quick Overview: 4 Steps to Integration

Step 1: Get Your Bearer Token (30 seconds)

Required for all API operations:

curl -X POST https://ramp.transfero.tools/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

Step 2: Set Up API Key Authentication (2 minutes)

Generate an RSA key pair and register it:

# Generate keys
openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

# Sign key name and register (see Authentication Guide for complete steps)
KEY_NAME="MyProductionKey"
printf "%s" "$KEY_NAME" | openssl dgst -sha256 -sign private_key.pem -out signature.bin
SIGNATURE_B64=$(openssl base64 -in signature.bin -A)

# Register with API using Bearer token
curl -X POST https://ramp.transfero.tools/v1/api-keys \
  -H "Authorization: Bearer your_bearer_token" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"$KEY_NAME\",\"publicKey\":\"$(cat public_key.pem | tr '\n' '\\n')\",\"signature\":\"$SIGNATURE_B64\"}"

Step 3: Create Clients (using dual authentication)

# All business operations require BOTH Bearer token AND API key signatures

# Generate signature for the request
TIMESTAMP_MS=$(($(date +%s%N)/1000000))
REQUEST_METHOD="POST"
REQUEST_PATH="/v1/clients/"
REQUEST_BODY='{"name": "João Silva", "email": "[email protected]", "tax_id": "12345678901"}'

CONTENT_TO_SIGN="${TIMESTAMP_MS}${REQUEST_METHOD}${REQUEST_PATH}${REQUEST_BODY}"
printf "%s" "$CONTENT_TO_SIGN" | openssl dgst -sha256 -sign private_key.pem -out request_signature.bin
REQUEST_SIGNATURE=$(openssl base64 -in request_signature.bin -A)

# Make the authenticated request
curl -X POST https://ramp.transfero.tools/v1/clients/ \
  -H "Authorization: Bearer your_bearer_token" \
  -H "X-API-Key: your_key_hash" \
  -H "X-API-Timestamp: $TIMESTAMP_MS" \
  -H "X-API-Signature: $REQUEST_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$REQUEST_BODY"

Step 4: Start Processing Transactions (immediately)

# PIX In: User pays 100 BRL, gets USDC (dual authentication required)

# Generate signature for the transaction request
TIMESTAMP_MS=$(($(date +%s%N)/1000000))
REQUEST_METHOD="POST"
REQUEST_PATH="/v1/pix-in-requests/"
REQUEST_BODY='{
  "amount_brl": "100.00", 
  "to_currency": "USDC", 
  "blockchain": "Polygon", 
  "wallet_address": "0x123...", 
  "client_email": "[email protected]", 
  "external_id": "abc123"
}'

CONTENT_TO_SIGN="${TIMESTAMP_MS}${REQUEST_METHOD}${REQUEST_PATH}${REQUEST_BODY}"
printf "%s" "$CONTENT_TO_SIGN" | openssl dgst -sha256 -sign private_key.pem -out request_signature.bin
REQUEST_SIGNATURE=$(openssl base64 -in request_signature.bin -A)

# Make the transaction request
curl -X POST https://ramp.transfero.tools/v1/pix-in-requests/ \
  -H "Authorization: Bearer your_bearer_token" \
  -H "X-API-Key: your_key_hash" \
  -H "X-API-Timestamp: $TIMESTAMP_MS" \
  -H "X-API-Signature: $REQUEST_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$REQUEST_BODY"

Authentication Requirements

Operation	Bearer Token	API Signature	Example
API Key Management	✅ Required	❌ Not needed	`POST /v1/api-keys`
Business Operations	✅ Required	✅ Required	`POST /v1/clients/`

All business endpoints require BOTH Bearer token AND API key signature for enhanced security.

What You'll Get

For PIX In: QR Code + PIX Copia e Cola for user payment
For PIX Out: Crypto deposit address and blockchain for user to send funds

Both flows handle conversion rates, blockchain fees, and settlement automatically.

Signature Generation Quick Reference

For all business operations, generate signatures using this pattern:

# 1. Create content string: {timestamp}{method}{path}{body}
CONTENT_TO_SIGN="${TIMESTAMP_MS}${REQUEST_METHOD}${REQUEST_PATH}${REQUEST_BODY}"

# 2. Sign with your private key (use printf, not echo -n)
printf "%s" "$CONTENT_TO_SIGN" | openssl dgst -sha256 -sign private_key.pem -out signature.bin

# 3. Base64 encode the signature
REQUEST_SIGNATURE=$(openssl base64 -in signature.bin -A)

# 4. Clean up
rm -f signature.bin

Next Steps

Authentication Guide - Detailed dual authentication setup
API Documentation - Complete endpoint reference
Interactive Docs - Test endpoints live

Need Help?

Check our interactive Swagger UI for live testing
All endpoints include detailed examples
Response formats are consistent and well-documented

Ready to integrate? Let's start with the Authentication Guide!