Skip to main content
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

MethodAPI operationUse
client.transfers.create(params, opts?)POST /v2/transfersCreate 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/transfersList transfers with cursor pagination.
client.transfers.cancel(id, params?, opts?)POST /v2/transfers/{id}/cancelCancel a pending transfer when supported.
client.transfers.listAutoPagingIterator(params?, opts?)Cursor helperIterate 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);
amount is in cents. 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("po_1001", {
  requestId: "reconcile_po_1001",
  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(
  "po_1001",
  { reason: "wrong recipient" },
  {
    idempotencyKey: "cancel_po_1001_wrong_recipient",
    requestId: "cancel_po_1001",
  },
);
Cancellation depends on the current transfer state and provider support. 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": "req_3003",
  "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.