> ## 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.

# Transfers with the TypeScript SDK

> Create Pix transfers, retrieve and list them by cursor, cancel safely, and reconcile payout state with the TypeScript SDK.

Use these examples when your service owns payout creation, cancellation, and reconciliation.

All examples assume a configured `client` from the [TypeScript SDK Quickstart](/sdks/typescript/quickstart).

## Resource methods

| Method                                                    | API operation                    | Use                                       |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------- |
| `client.transfers.create(params, opts?)`                  | `POST /v2/transfers`             | Create a Pix Out transfer.                |
| `client.transfers.retrieve(id, opts?)`                    | `GET /v2/transfers/{id}`         | Read the current transfer state.          |
| `client.transfers.list(params?, opts?)`                   | `GET /v2/transfers`              | List transfers with cursor pagination.    |
| `client.transfers.cancel(id, params?, opts?)`             | `POST /v2/transfers/{id}/cancel` | Cancel a pending transfer when supported. |
| `client.transfers.listAutoPagingIterator(params?, opts?)` | Cursor helper                    | Iterate every transfer across pages.      |

## Create a transfer

```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);
```

Request `amount` and list-item amounts are numeric cents. Create, retrieve, and cancel responses expose the gross
`data.amount` as a decimal string. Supported Pix key types are `CPF`, `CNPJ`, `EMAIL`, `PHONE`, and `EVP`.

## Retrieve and reconcile

Use retrieve calls for back-office screens, reconciliation jobs, and delayed state checks.

```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);
```

## List transfers

```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,
  });
}
```

List responses include `next_cursor`, `prev_cursor`, and `total`. Use those fields when building your own paginated UI.

## List with auto-pagination

```ts theme={null}
for await (const item of client.transfers.listAutoPagingIterator({ limit: 100 })) {
  console.log(item.id, item.status);
}
```

Use auto-pagination for batch jobs, exports, and reconciliation tasks that should consume all available pages.

## Cancel safely

```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",
  },
);
```

Cancellation is available only in supported transfer states. If cancellation fails, inspect the typed SDK error and reconcile the transfer before retrying.

## Response shape

Create, retrieve, and cancel methods return `{ data, meta }`.

List methods return `{ data, meta }`, where `data` is a cursor envelope:

```json theme={null}
{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": [],
  "next_cursor": "cursor_next",
  "prev_cursor": null,
  "total": 80
}
```

## Common rule

Use `pix_key_type` and `pix_key_value` in SDK and API examples. Do not use undocumented input fields such as `pix_key` or `recipient_name`.