Payouts (PIX out)

Payout é a retirada de saldo via transferência PIX — o inverso de uma cobrança: em vez de receber, a plataforma envia dinheiro pra uma chave PIX. /v1/payouts usa a mesma API key do resto desta documentação — sempre saca o saldo do merchant dono da chave, nunca de uma conta escolhida por parâmetro.

Solicitar um saque

curl -X POST https://api.tamino.com.br/v1/payouts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2024-08-01" \
  -d '{
    "amountInCents": 10000,
    "pixKey": "11999999999",
    "pixKeyType": "phone",
    "externalId": "saque-2026-000123"
  }'

const payout = await gateway.payouts.create(
  { amountInCents: 10000, pixKey: "11999999999", pixKeyType: "phone", externalId: "saque-2026-000123" },
  { idempotencyKey: "payout-2024-08-01" },
);

{
  "id": "8f1c2a4e-3b7d-4c1a-9e2f-5d6a7b8c9d0e",
  "object": "payout",
  "externalId": "saque-2026-000123",
  "status": "processing",
  "merchantId": "0d303c3b-cb6d-417e-8aa7-2a5cc8fde653",
  "amountInCents": 10000,
  "feeAmountInCents": 100,
  "netAmountInCents": 9900,
  "feeMode": "deducted",
  "currency": "BRL",
  "pixKey": "11999999999",
  "pixKeyType": "phone",
  "recipientDocument": null,
  "endToEndId": null,
  "recipient": null,
  "failureReason": null,
  "approvedAt": null,
  "createdAt": "2026-10-27T12:00:00.000Z",
  "updatedAt": "2026-10-27T12:00:00.312Z",
  "processedAt": "2026-10-27T12:00:00.312Z"
}

pixKeyType aceita cpf, cnpj, email, phone ou random. recipientDocument (CPF/CNPJ do destinatário) é opcional, mas recomendado: com ele, o saque é recusado se a chave Pix não pertencer a esse CPF/CNPJ, em vez de cair na conta de outra pessoa. Idempotency-Key é opcional mas recomendado, mesmo header de qualquer outro endpoint transacional desta API — um retry de rede nunca saca duas vezes.

Seu id do pedido (externalId) e timeout

Mande em externalId o id do pedido de saque no seu sistema (até 64 caracteres: letras, números, ., _, : e -). Ele volta em todas as respostas e webhooks, e é único por conta: repetir o POST com o mesmo externalId devolve o saque que já existe, sem criar outro. O mesmo externalId com outro valor ou outra chave Pix responde 409.

Se o pedido der timeout ou erro de rede, você não recebe o nosso id, mas não perde o saque:

• consulte pelo seu id: GET /v1/payouts/external/{externalId} (404 = o saque não foi criado);
• ou simplesmente reenvie o mesmo pedido com o mesmo externalId — nunca sai um segundo Pix.

Com Idempotency-Key, um reenvio que chega enquanto o primeiro pedido ainda está sendo processado responde 409 — espere alguns segundos e tente de novo (ou consulte pelo externalId). Erros não ficam guardados na chave.

curl https://api.tamino.com.br/v1/payouts/external/saque-2026-000123 \
  -H "Authorization: Bearer sk_test_..."

Consultar e listar

curl https://api.tamino.com.br/v1/payouts/8f1c2a4e-... \
  -H "Authorization: Bearer sk_test_..."

curl https://api.tamino.com.br/v1/payouts?limit=20 \
  -H "Authorization: Bearer sk_test_..."

Depois que o banco confirma, a consulta traz o end-to-end do Pix (o identificador do comprovante no Bacen) e os dados de quem recebeu:

{
  "id": "8f1c2a4e-3b7d-4c1a-9e2f-5d6a7b8c9d0e",
  "object": "payout",
  "externalId": "saque-2026-000123",
  "status": "paid",
  "merchantId": "0d303c3b-cb6d-417e-8aa7-2a5cc8fde653",
  "amountInCents": 51675,
  "feeAmountInCents": 517,
  "netAmountInCents": 51158,
  "feeMode": "deducted",
  "currency": "BRL",
  "pixKey": "11222333000181",
  "pixKeyType": "cnpj",
  "recipientDocument": "11222333000181",
  "endToEndId": "E60701190202610262102abcdef123456",
  "recipient": {
    "name": "Fornecedor Exemplo LTDA",
    "document": "11222333000181",
    "documentType": "cnpj",
    "ispb": "60701190",
    "bankName": "Itaú Unibanco"
  },
  "failureReason": null,
  "approvedAt": null,
  "createdAt": "2026-10-26T21:02:42.926Z",
  "updatedAt": "2026-10-26T21:02:48.610Z",
  "processedAt": "2026-10-26T21:02:48.610Z"
}

GET /v1/payouts pagina por cursor, mesmo formato do resto da API: { "data": [...], "nextCursor": "...", "hasMore": true } — mande cursor=<nextCursor> pra próxima página. Aceita limit (padrão 20), status (ex.: ?status=paid) e externalId.

Campos

Objeto recipient (quem recebeu)

Cada campo só aparece quando o banco do recebedor informa — nunca é preenchido com o que foi pedido. Nome, CPF/CNPJ e ISPB vêm em praticamente todo saque; agência e conta dependem do banco.

Limites configuráveis

Além do saldo disponível, um super_admin ou tenant_admin pode configurar até três tetos independentes por tenant/merchant — por transação, por dia e por mês — pelo Backoffice ou pela API administrativa (/admin/payout-limit-rules, sessão de admin, não API key — essa é a única parte deste fluxo que continua exclusiva do Backoffice, já que é uma configuração operacional, não uma ação de cobrança/saque em si). Qualquer campo omitido não limita aquela dimensão. Quando mais de uma regra se aplica (ex.: uma regra geral da plataforma e uma específica de um merchant), vale a mais específica; em empate, a de maior priority. Um payout que excede algum limite configurado é rejeitado com um erro claro — pela API pública ou pelo Backoffice, o mesmo motor de limite vale pros dois — antes de qualquer tentativa de envio.

Status

A passagem pra failed ou cancelled chega pelo webhook payout.failed — exemplos dos dois casos em Webhooks.

Disponibilidade

O saque via API depende do recurso estar habilitado na sua conta. Se não estiver, a chamada retorna um erro indicando que o recurso não está disponível — fale com o suporte.