Criar payout

Quick Reference

WhatEnviar um pagamento de saída (payout) financiado por uma carteira

WhyPagar fornecedores, parceiros e clientes pela LATAM através de um único endpoint unificado

Reading Time10 min

DifficultyIntermediate

PrerequisitesAuthentication → Uma carteira com saldo → Um merchant cadastrado (quando exigido pela sua conta)

POST/api/v1/bank/wallet/payout/Bearer TokenCriar um payout debitando uma carteira

Como os payouts funcionam

Um payout é o fluxo de saída — dinheiro deixando a plataforma, o inverso de uma cobrança. Um único endpoint atende a todos os rails; o campo type_payout seleciona qual deles, e cada tipo exige seu objeto de destino correspondente.

Fluxo do payout

Status do payout

Status	Significado	Terminal?
`pending`	Criado, aguardando processamento	Não
`issued`	Enviado ao provider	Não
`realized`	Confirmado e liquidado	Sim
`returned`	Devolvido pelo banco receptor	Sim
`canceled`	Cancelado	Sim
`error`	Falhou no processamento	Sim
`expired`	Expirado	Sim

Cabeçalhos da requisição

Header	Valor	Obrigatório
`Authorization`	`Bearer {A55_ACCESS_TOKEN}`	Sim
`Content-Type`	`application/json`	Sim

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`wallet_uuid`	string (UUID)	Sim	Carteira que vai financiar o payout
`type_payout`	string	Sim	Rail de pagamento: `pix`, `bank_transfer`, `ted`, `spei`, `cash_pickup`
`value`	number (float)	Sim	Valor a enviar. Deve ser maior que zero
`description`	string	Sim	Descrição livre do payout
`currency`	string	Não	Código ISO 4217. Usa a moeda da carteira quando omitido
`merchant_id`	string (UUID)	Não	Merchant ao qual o payout pertence. Obrigatório quando sua conta usa merchants
`transaction_reference`	string	Não	Chave de idempotência externa (por carteira). Um UUID é gerado quando omitido
`schedule_date`	string	Não	`YYYY-MM-DD` para agendar o payout
`country_code`	string	Não	ISO 3166-1 alpha-2 do destino
`providers`	string[]	Não	UUIDs de providers para forçar o roteamento
`webhook_url`	string (URL)	Não	URL notificada nas mudanças de status
`pix_destination`	object	Condicional	Obrigatório quando `type_payout` é `pix`
`bank_destination`	object	Condicional	Obrigatório quando `type_payout` é `bank_transfer`, `ted` ou `spei`
`cash_destination`	object	Condicional	Obrigatório quando `type_payout` é `cash_pickup`

`pix_destination`

Campo	Tipo	Obrigatório	Descrição
`pix_address_key`	string	Sim	Valor da chave PIX
`pix_address_key_type`	string	Sim	Tipo da chave PIX (`cpf`, `cnpj`, `email`, `phone`, `evp`)
`beneficiary_name`	string	Não	Nome completo do beneficiário
`beneficiary_tax_id`	string	Não	CPF/CNPJ do beneficiário. Obrigatório para chaves email/phone/evp; opcional para chaves cpf/cnpj (usa a chave como documento)

`bank_destination` (bank_transfer / ted / spei)

Campo	Tipo	Obrigatório	Descrição
`country_code`	string	Sim	ISO-3166 alpha-2 ou alpha-3
`beneficiary_name`	string	Sim	Primeiro nome do beneficiário
`beneficiary_last_name`	string	Sim	Sobrenome do beneficiário
`document_type`	string	Sim	Cedula / RUC / DPI / RUT / CPF / etc.
`beneficiary_tax_id`	string	Sim	Número do documento do beneficiário
`account_number`	string	Condicional	Número da conta, CBU/CVU, CCI, CLABE, etc. Obrigatório a menos que use `bank_alias`
`bank_alias`	string	Condicional	Alias de CBU da Argentina (6-20 chars). Alternativa ao `account_number`
`bank_code`	string	Não	Código do banco no provider. TED Brasil: ISPB de 8 dígitos ou COMPE (ex.: `001`)
`account_type`	string	Não	Poupança / Corrente / Cash / RUT / etc. (varia por país)
`account_agency`	string	Não	Agência bancária (TED Brasil)
`bank_name`	string	Não	Nome do banco
`beneficiary_email`	string	Não	Obrigatório quando `account_type` é `Cash`
`beneficiary_phone`	string	Não	Telefone do beneficiário
`expiration_date`	string	Não	`YYYY-MM-DD` (redes de cash)

`cash_destination` (cash_pickup)

Campo	Tipo	Obrigatório	Descrição
`country_code`	string	Sim	País de destino
`bank_code`	string	Sim	Código da rede de cash (ex.: `010`, `456`)
`beneficiary_name`	string	Sim	Nome do beneficiário
`beneficiary_email`	string	Sim	O código de retirada é enviado para este email
`document_type`	string	Sim	Tipo de documento do beneficiário
`beneficiary_tax_id`	string	Sim	Número do documento do beneficiário
`beneficiary_last_name`	string	Não	Sobrenome do beneficiário
`beneficiary_phone`	string	Não	Telefone do beneficiário
`expiration_date`	string	Não	`YYYY-MM-DD` de expiração da retirada

Campos da resposta

Campo	Tipo	Descrição
`payout_uuid`	string	Identificador interno do payout
`external_id`	string	ID do payout no provider
`status`	string	Status atual do payout (ver tabela acima)
`type_payout`	string	Rail utilizado
`amount`	number (float)	Valor do payout
`fee`	number (float)	Taxa do provider
`currency`	string	Moeda ISO 4217
`description`	string	Descrição do payout
`country_code`	string	País de destino
`beneficiary_name`	string	Nome do beneficiário
`transaction_reference`	string	Chave de idempotência usada
`submitted_date`	string	Data de envio ao provider
`confirmed_date`	string	Data de confirmação
`schedule_date`	string	Data agendada, quando aplicável
`payment_code`	string	Código de retirada (apenas cash payouts)
`authorization_code`	string	Código de autorização do provider, quando disponível
`authorization_date`	string	Data de autorização, quando disponível
`transaction_id`	string	ID da transação no provider, quando disponível
`destination`	object	Eco dos dados de destino
`message`	array	Mensagens do provider/processamento
`created`	string	Timestamp de criação (ISO 8601)
`updated`	string	Timestamp da última atualização (ISO 8601)

Respostas de erro

Status	Código	Descrição
400	`errors.payout.validate_error`	Payload falhou na validação (sem `type_payout`, `value <= 0`, campos de destino faltando, etc.)
400	`errors.payout.destination_invalid`	Objeto de destino inválido para o `type_payout` escolhido
400	`errors.payout.provider_not_valid`	Nenhum provider elegível para este payout
400	`errors.wallet.payout_already_exists`	Já existe um payout com o mesmo `transaction_reference` para esta carteira
400	`errors.wallet.daily_transaction_limit_exceeded`	O limite diário da carteira seria excedido
400	`errors.wallet.merchant_invalid`	O merchant não pertence à conta da carteira
401	`unauthorized`	Token Bearer inválido ou expirado
404	`errors.wallet.not_found`	Carteira não encontrada
404	`errors.payout.merchant_not_found`	Merchant não encontrado
422	`errors.payout.insufficient_balance`	Saldo da carteira insuficiente para este payout

Exemplos de código

PIX out (Brasil)

cURL
Python
Node.js

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "pix",
    "value": 100.00,
    "currency": "BRL",
    "description": "Pagamento fornecedor #2048",
    "transaction_reference": "PAY-2048",
    "webhook_url": "https://your-app.com/webhooks/a55/payouts",
    "pix_destination": {
      "pix_address_key": "joao@example.com",
      "pix_address_key_type": "email",
      "beneficiary_name": "João Silva",
      "beneficiary_tax_id": "12345678901"
    }
  }'

import requests
import os

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

response = requests.post(
    f"{base}/api/v1/bank/wallet/payout/",
    json={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "type_payout": "pix",
        "value": 100.00,
        "currency": "BRL",
        "description": "Pagamento fornecedor #2048",
        "transaction_reference": "PAY-2048",
        "webhook_url": "https://your-app.com/webhooks/a55/payouts",
        "pix_destination": {
            "pix_address_key": "joao@example.com",
            "pix_address_key_type": "email",
            "beneficiary_name": "João Silva",
            "beneficiary_tax_id": "12345678901",
        },
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)
payout = response.json()
print(f"Payout {payout['payout_uuid']} — status: {payout['status']}")

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://sandbox.api.a55.tech";

const payout = await fetch(`${base}/api/v1/bank/wallet/payout/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    type_payout: "pix",
    value: 100.0,
    currency: "BRL",
    description: "Pagamento fornecedor #2048",
    transaction_reference: "PAY-2048",
    webhook_url: "https://your-app.com/webhooks/a55/payouts",
    pix_destination: {
      pix_address_key: "joao@example.com",
      pix_address_key_type: "email",
      beneficiary_name: "João Silva",
      beneficiary_tax_id: "12345678901",
    },
  }),
}).then((r) => r.json());

console.log(`Payout ${payout.payout_uuid} — status: ${payout.status}`);

TED (Brasil)

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "ted",
    "value": 500.00,
    "currency": "BRL",
    "description": "Liquidação fornecedor",
    "transaction_reference": "PAY-2049",
    "bank_destination": {
      "country_code": "BR",
      "bank_code": "341",
      "account_type": "checking",
      "account_number": "12345-6",
      "account_agency": "0001",
      "bank_name": "Itaú",
      "beneficiary_name": "Maria",
      "beneficiary_last_name": "Costa",
      "document_type": "CPF",
      "beneficiary_tax_id": "98765432100"
    }
  }'

SPEI (México)

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "spei",
    "value": 1500.00,
    "currency": "MXN",
    "description": "Payout MXN",
    "transaction_reference": "PAY-2050",
    "bank_destination": {
      "country_code": "MX",
      "account_number": "012180012345678901",
      "beneficiary_name": "Carlos",
      "beneficiary_last_name": "Hernández",
      "document_type": "RFC",
      "beneficiary_tax_id": "HEGC800101XXX"
    }
  }'

Transferência bancária (LATAM)

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "bank_transfer",
    "value": 250.00,
    "currency": "ARS",
    "description": "Payout Argentina",
    "transaction_reference": "PAY-2051",
    "bank_destination": {
      "country_code": "AR",
      "bank_alias": "mi.alias.cbu",
      "beneficiary_name": "Lucía",
      "beneficiary_last_name": "Gómez",
      "document_type": "DNI",
      "beneficiary_tax_id": "20304050607"
    }
  }'

Retirada em dinheiro (Equador)

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "cash_pickup",
    "value": 200.00,
    "currency": "USD",
    "description": "Payout retirada em dinheiro",
    "transaction_reference": "PAY-2052",
    "cash_destination": {
      "country_code": "EC",
      "bank_code": "456",
      "beneficiary_name": "Pedro",
      "beneficiary_email": "pedro@example.com",
      "document_type": "Cedula",
      "beneficiary_tax_id": "1234567890"
    }
  }'

Exemplo completo de resposta

Payout PIX aceito

{
  "payout_uuid": "9b1f0c88-3a3c-4f2f-9d6e-1f0a2d4e88c1",
  "external_id": "MN-20260616-0001",
  "status": "issued",
  "type_payout": "pix",
  "amount": 100.00,
  "fee": 0.50,
  "currency": "BRL",
  "description": "Pagamento fornecedor #2048",
  "country_code": "BR",
  "beneficiary_name": "João Silva",
  "transaction_reference": "PAY-2048",
  "submitted_date": "2026-06-16",
  "confirmed_date": null,
  "schedule_date": null,
  "destination": {
    "pix_address_key": "joao@example.com",
    "pix_address_key_type": "email"
  },
  "message": [],
  "created": "2026-06-16T18:00:00Z",
  "updated": "2026-06-16T18:00:00Z"
}

Retirada em dinheiro aceita (inclui código de retirada)

{
  "payout_uuid": "5c2a13f0-5e74-4b21-9c6a-2bd9d9b0aa10",
  "external_id": "MN-20260616-0002",
  "status": "issued",
  "type_payout": "cash_pickup",
  "amount": 200.00,
  "fee": 1.20,
  "currency": "USD",
  "description": "Payout retirada em dinheiro",
  "country_code": "EC",
  "beneficiary_name": "Pedro",
  "transaction_reference": "PAY-2052",
  "payment_code": "EC-PICKUP-7788",
  "message": [],
  "created": "2026-06-16T18:05:00Z",
  "updated": "2026-06-16T18:05:00Z"
}

Sempre confirme via webhook

A resposta síncrona retorna o status inicial. Um payout normalmente passa de issued para realized de forma assíncrona. Configure a webhook_url e trate o webhook como fonte da verdade para o resultado final. Veja Webhook de payout.

Consultar payout →Consulte o status e os detalhes atuais de um payout.Listar payouts →Liste e filtre os payouts de uma carteira.Webhook de payout →Receba uma notificação quando o status do payout mudar.

Quick Reference

Como os payouts funcionam​

Fluxo do payout​

Status do payout​

Cabeçalhos da requisição​

Corpo da requisição​

pix_destination​

bank_destination (bank_transfer / ted / spei)​

cash_destination (cash_pickup)​

Campos da resposta​

Respostas de erro​

Exemplos de código​

PIX out (Brasil)​

TED (Brasil)​

SPEI (México)​

Transferência bancária (LATAM)​

Retirada em dinheiro (Equador)​

Exemplo completo de resposta​

Payout PIX aceito​

Retirada em dinheiro aceita (inclui código de retirada)​