> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Transferências com o SDK TypeScript

> Crie transferências Pix, consulte e liste por cursor, cancele com segurança e reconcilie estado de payout usando o SDK TypeScript.

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](/pt/sdks/typescript/quickstart).

## Métodos do recurso

| Método                                                    | Operação da API                  | Uso                                                   |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------- |
| `client.transfers.create(params, opts?)`                  | `POST /v2/transfers`             | Criar 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/transfers`              | Listar transferências com paginação por cursor.       |
| `client.transfers.cancel(id, params?, opts?)`             | `POST /v2/transfers/{id}/cancel` | Cancelar uma transferência pendente quando suportado. |
| `client.transfers.listAutoPagingIterator(params?, opts?)` | Helper de cursor                 | Iterar todas as transferências entre páginas.         |

## Criar uma transferência

```ts theme={null}
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);
```

O `amount` da requisição e dos itens de listagem usa centavos numéricos. Nas respostas de criação, consulta e
cancelamento, o valor bruto em `data.amount` é uma string decimal. 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.

```ts theme={null}
const current = await client.transfers.retrieve("018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72", {
  requestId: "reconcile_018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72",
  timeoutMs: 10_000,
});

console.log(current.data.status);
```

## Listar transferências

```ts theme={null}
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

```ts theme={null}
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

```ts theme={null}
const cancelled = await client.transfers.cancel(
  "018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72",
  { reason: "wrong recipient" },
  {
    idempotencyKey: "cancel_018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72_wrong_recipient",
    requestId: "cancel_018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72",
  },
);
```

O cancelamento está disponível apenas nos estados compatíveis. Se 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:

```json theme={null}
{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "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`.