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

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

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.

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

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

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

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:

{
  "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.

Choose an SDK

Server-side TypeScript

Resource methods

Create a transfer

Retrieve and reconcile

List transfers

Cancel safely

Response shape

Common rule

​Resource methods

​Create a transfer

​Retrieve and reconcile

​List transfers

​List with auto-pagination

​Cancel safely

​Response shape

​Common rule

Resource methods

Create a transfer

Retrieve and reconcile

List transfers

List with auto-pagination

Cancel safely

Response shape

Common rule