Transferência PIX

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

---

Cabeçalhos da requisição

Cabeçalho	Valor	Obrigatório
Authorization	Bearer {A55_ACCESS_TOKEN}	Sim
Content-Type	application/json	Sim
Idempotency-Key	UUID v4	Recomendado

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
wallet_uuid	string (UUID)	Sim	Carteira de origem da transferência
amount	number	Sim	Valor da transferência em BRL (ex.: 500.00)
currency	string	Sim	Deve ser BRL
pix_key_type	string	Sim	cpf, cnpj, email, phone, random_key
pix_key	string	Sim	Valor da chave PIX correspondente ao tipo
recipient_name	string	Sim	Nome completo do destinatário
recipient_tax_id	string	Sim	CPF ou CNPJ do destinatário
description	string	Não	Descrição da transferência
reference_id	string	Não	Sua referência interna para conciliação

---

Campos da resposta

Campo	Tipo	Descrição
transfer_uuid	string	Identificador único da transferência
status	string	processing, completed, failed
amount	number	Valor transferido
currency	string	BRL
pix_key_type	string	Tipo de chave PIX utilizada
pix_key	string	Chave PIX de destino
recipient_name	string	Nome do destinatário confirmado
created_at	string	Timestamp de criação ISO 8601
completed_at	string	Timestamp de conclusão ISO 8601 (quando disponível)

---

Códigos de status HTTP

Status	Descrição
200	Transferência iniciada com sucesso
400	Chave PIX inválida ou campos obrigatórios ausentes
401	Token Bearer inválido ou expirado
403	Permissões insuficientes ou saldo insuficiente na carteira
404	Carteira não encontrada
409	Transferência duplicada (mesma Idempotency-Key)
422	Erro de validação (tipo de chave inválido, valor inválido)
429	Limite de requisições excedido
500	Erro interno do servidor — tente novamente com backoff exponencial

---

Exemplos de código

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);
}

---

Exemplo de resposta de erro

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

---

Criar cobrança PIX →Receba um pagamento PIX com QR code.Consultar carteira →Verifique o saldo da carteira antes da transferência.Webhooks →Receba notificação quando a transferência for concluída.