Pular para o conteúdo principal
Use estes exemplos quando o seu serviço for dono da criação, cancelamento e reconciliação de payouts. Todos os exemplos assumem um client configurado a partir do Início rápido do SDK para TypeScript.

​
Métodos do recurso

MétodoOperação da APIUso
client.transfers.create(params, opts?)POST /v2/transfersCriar uma transferência Pix Out.
client.transfers.retrieve(id, opts?)GET /v2/transfers/{id}Ler o estado atual da transferência.
client.transfers.list(params?, opts?)GET /v2/transfersListar transferências com paginação por cursor.
client.transfers.cancel(id, params?, opts?)POST /v2/transfers/{id}/cancelCancelar uma transferência pendente quando suportado.
client.transfers.listAutoPagingIterator(params?, opts?)Helper de cursorIterar todas as transferências entre páginas.

​
Criar uma transferência

const transfer = await client.transfers.create(
  {
    pix_key_type: "EMAIL",
    pix_key_value: "supplier@example.com",
    amount: 1200,
    description: "Supplier payout",
    external_ref: "payout_1001",
  },
  {
    idempotencyKey: "transfer_payout_1001",
    requestId: "req_payout_1001",
  },
);

console.log(transfer.data.id, transfer.data.status, transfer.meta.requestId);
amount é em centavos. Tipos de chave Pix suportados: CPF, CNPJ, EMAIL, PHONE e EVP.

​
Consultar e reconciliar

Use consultas para telas de back-office, jobs de reconciliação e checagens atrasadas de estado. 
const current = await client.transfers.retrieve("po_1001", {
  requestId: "reconcile_po_1001",
  timeoutMs: 10_000,
});

console.log(current.data.status);

​
Listar transferências

const page = await client.transfers.list({
  limit: 50,
  status: "pending",
});

for (const transfer of page.data.data) {
  console.log(transfer.id, transfer.status);
}

if (page.data.next_cursor) {
  const nextPage = await client.transfers.list({
    cursor: page.data.next_cursor,
    direction: "next",
    limit: 50,
  });
}
Respostas de listagem incluem next_cursor, prev_cursor e total. Use esses campos ao construir sua própria UI paginada.

​
Listar com paginação automática

for await (const item of client.transfers.listAutoPagingIterator({ limit: 100 })) {
  console.log(item.id, item.status);
}
Use paginação automática para jobs de lote, exportações e tarefas de reconciliação que precisam consumir todas as páginas disponíveis.

​
Cancelar com segurança

const cancelled = await client.transfers.cancel(
  "po_1001",
  { reason: "wrong recipient" },
  {
    idempotencyKey: "cancel_po_1001_wrong_recipient",
    requestId: "cancel_po_1001",
  },
);
O cancelamento depende do estado atual da transferência e do suporte do provedor. Se o cancelamento falhar, inspecione o erro tipado do SDK e reconcilie a transferência antes de tentar novamente.

​
Formato de resposta

Métodos de criação, consulta e cancelamento retornam { data, meta }. Métodos de listagem retornam { data, meta }, em que data é um envelope com cursor: 
{
  "success": true,
  "requestId": "req_3003",
  "data": [],
  "next_cursor": "cursor_next",
  "prev_cursor": null,
  "total": 80
}

​
Regra comum

Use pix_key_type e pix_key_value nos exemplos de SDK e API. Não use campos de entrada não documentados como pix_key ou recipient_name.