PIX transfer

POST/api/v1/bank/wallet/transfer/pix/Bearer Token

---

Request headers

Header	Value	Required
Authorization	Bearer {A55_ACCESS_TOKEN}	Yes
Content-Type	application/json	Yes
Idempotency-Key	UUID v4	Recommended

Request body

Field	Type	Required	Description
wallet_uuid	string (UUID)	Yes	Source wallet for the transfer
amount	number	Yes	Transfer amount in BRL (e.g., 500.00)
currency	string	Yes	Must be BRL
pix_key_type	string	Yes	cpf, cnpj, email, phone, random_key
pix_key	string	Yes	PIX key value matching the type
recipient_name	string	Yes	Recipient full name
recipient_tax_id	string	Yes	Recipient CPF or CNPJ
description	string	No	Transfer description
reference_id	string	No	Your internal reference for reconciliation

---

Response fields

Field	Type	Description
transfer_uuid	string	Unique transfer identifier
status	string	processing, completed, failed
amount	number	Transferred amount
currency	string	BRL
pix_key_type	string	PIX key type used
pix_key	string	PIX key destination
recipient_name	string	Confirmed recipient name
created_at	string	ISO 8601 creation timestamp
completed_at	string	ISO 8601 completion timestamp (when available)

---

HTTP status codes

Status	Description
200	Transfer initiated successfully
400	Invalid PIX key or missing required fields
401	Invalid or expired Bearer token
403	Insufficient permissions or wallet balance
404	Wallet not found
409	Duplicate transfer (same Idempotency-Key)
422	Validation error (invalid key type, amount)
429	Rate limit exceeded
500	Internal server error — retry with exponential backoff

---

Code examples

cURL

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/transfer/pix/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 770e8400-e29b-41d4-a716-446655440002" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "amount": 500.00,
    "currency": "BRL",
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-09",
    "recipient_name": "João Santos",
    "recipient_tax_id": "123.456.789-09",
    "description": "Supplier payment #2048",
    "reference_id": "PAY-2048"
  }'

Python

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://core-manager.a55.tech")

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/transfer/pix/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "amount": 500.00,
            "currency": "BRL",
            "pix_key_type": "cpf",
            "pix_key": "123.456.789-09",
            "recipient_name": "João Santos",
            "recipient_tax_id": "123.456.789-09",
            "description": "Supplier payment #2048",
            "reference_id": "PAY-2048",
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "770e8400-e29b-41d4-a716-446655440002",
        },
    )
    response.raise_for_status()
    transfer = response.json()
    print(f"Transfer: {transfer['transfer_uuid']} — Status: {transfer['status']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://core-manager.a55.tech";

try {
  const response = await fetch(`${base}/api/v1/bank/wallet/transfer/pix/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "770e8400-e29b-41d4-a716-446655440002",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      amount: 500.00,
      currency: "BRL",
      pix_key_type: "cpf",
      pix_key: "123.456.789-09",
      recipient_name: "João Santos",
      recipient_tax_id: "123.456.789-09",
      description: "Supplier payment #2048",
      reference_id: "PAY-2048",
    }),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const transfer = await response.json();
  console.log(`Transfer: ${transfer.transfer_uuid} — Status: ${transfer.status}`);
} catch (error) {
  console.error("PIX transfer failed:", error.message);
}

---

Error response example

{
  "transfer_uuid": null,
  "status": "error",
  "message": [
    {
      "code": "INSUFFICIENT_BALANCE",
      "source": "wallet",
      "description": "Wallet balance is insufficient for this transfer amount"
    }
  ]
}

---

Create PIX charge →Receive a PIX payment with QR code.Get wallet →Check wallet balance before transfer.Webhooks →Receive notification when transfer completes.