LLiccenDocs

Criar transferência

Envia dinheiro do saldo da conta para uma chave Pix.

POST/v1/payoutsescopo: payout:write

Exige o header Idempotency-Key. Em transferência isso não é detalhe: sem a chave, um retry por timeout enviaria o dinheiro duas vezes.

Corpo

amount
inteiro (centavos)obrigatório
Mínimo e máximo por transferência são definidos pelo administrador da plataforma (padrão: a partir de R$ 5,00, sem teto).
pix_key_type
stringobrigatório
cpf, cnpj, email, phone ou random.
pix_key
stringobrigatório
A chave que recebe o valor.
method
stringopcional
Apenas "pix" na v1. Padrão "pix".
recipient_name
stringopcional
Nome de quem recebe.
recipient_document
stringopcional
CPF ou CNPJ de quem recebe.
description
stringopcional
Aparece no seu extrato de transferências.
reference
stringopcional
Seu identificador, devolvido nas respostas e eventos.
webhook_url
stringopcional
Recebe todos os eventos desta transferência, sem cadastro prévio. Precisa ser http(s) e pública.
webhook_secret
stringopcional
Assina as entregas feitas a webhook_url (header X-Webhook-Signature).

Exemplo

cURL
curl -X POST https://api.transakto.io/v1/payouts \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: repasse-2026-07-28-lote-3" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "pix_key_type": "cnpj",
    "pix_key": "12.345.678/0001-95",
    "recipient_name": "Fornecedor LTDA",
    "description": "Repasse semanal",
    "reference": "lote-3",
    "webhook_url": "https://meusistema.com.br/hooks/repasses",
    "webhook_secret": "um-segredo-bem-longo"
  }'
Resposta 201
{
  "id": "3b7a11d0-7e5c-4c6a-9d21-0e4f5a6b7c8d",
  "object": "payout",
  "status": "pending",
  "method": "pix",
  "amount": 150000,
  "fee": 0,
  "currency": "BRL",
  "description": "Repasse semanal",
  "reference": "lote-3",
  "recipient": {
    "name": "Fornecedor LTDA",
    "document": null,
    "pix_key_type": "cnpj",
    "pix_key": "12.345.678/0001-95"
  },
  "end_to_end_id": null,
  "failure_reason": null,
  "webhook_url": "https://meusistema.com.br/hooks/repasses",
  "processed_at": null,
  "created_at": "2026-07-28T14:00:00.000Z"
}

Dois modos de execução

O que acontece depois do 201 depende de uma configuração da conta.

Com envio automático desativado, a transferência fica em pending, na fila de aprovação manual da dashboard. Alguém precisa liberar. É o padrão, e o modo certo para quem move valores altos.

Com envio automático ativado, a resposta da criação já volta como processing e o envio ao adquirente acontece logo em seguida, sem intervenção. O desfecho (completed ou failed) chega pelo webhook.

Em qualquer um dos modos, o valor mais a tarifa saem do saldo disponível no momento da criação. Se a transferência falhar, o valor volta e o estado vira failed com failure_reason preenchido.

Erros comuns

AMOUNT_BELOW_MINIMUM e AMOUNT_ABOVE_MAXIMUM quando o valor sai dos limites configurados na plataforma (a mensagem traz o limite em centavos e em reais). INSUFFICIENT_BALANCE quando o disponível não cobre valor mais tarifa: consulte /v1/balance antes de montar lotes grandes.

AnteriorListar cobrançasPróximaConsultar transferência