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

# SDK JavaScript

> Use o pacote oficial @troqpay/sdk no seu backend Node.js.

# SDK JavaScript

O SDK JavaScript encapsula a API pública da TroqPay para backends Node.js e TypeScript.

<Warning>
  Use o SDK somente no backend. Nunca exponha chaves `trq_test_` ou `trq_live_`
  em código de front-end, app mobile, logs públicos ou repositórios.
</Warning>

## Instalação

```bash theme={null}
npm install @troqpay/sdk
```

## Cliente

```ts theme={null}
import { Troqpay } from "@troqpay/sdk";

const troqpay = new Troqpay({
  apiKey: process.env.TROQPAY_API_KEY!,
});
```

Para staging ou ambiente local:

```ts theme={null}
const troqpay = new Troqpay({
  apiKey: process.env.TROQPAY_API_KEY!,
  baseUrl: "https://api.staging.troqpay.com",
});
```

## Criar checkout Pix

```ts theme={null}
const checkout = await troqpay.checkouts.create(
  {
    amount: 12990,
    description: "Plano Pro",
    externalId: "order_1001",
    customer: {
      name: "Maria Silva",
      email: "maria@example.com",
    },
    metadata: {
      plan: "pro",
    },
  },
  {
    idempotencyKey: "order_1001",
  }
);

console.log(checkout.pix.copyPaste);
console.log(checkout.checkoutUrl);
```

## Consultar checkout

```ts theme={null}
const checkout = await troqpay.checkouts.retrieve("chk_4a8b3c1d5e6f2a9b0c1d");
```

## Consultar saldo

```ts theme={null}
const balance = await troqpay.balance.retrieve();

console.log(balance.availableAmount);
```

## Criar saque

Saques pela API exigem chave `trq_live_`, conta aprovada, destino aprovado,
saldo disponível, permissão de saque e `Idempotency-Key`.

```ts theme={null}
const withdrawal = await troqpay.withdrawals.create(
  {
    rail: "BRL_PIX",
    amount: "100.00",
  },
  {
    idempotencyKey: "withdrawal_1001",
  }
);
```

## Tratar erros

Falhas da API lançam `TroqpayAPIError`.

```ts theme={null}
import { TroqpayAPIError } from "@troqpay/sdk";

try {
  await troqpay.balance.retrieve();
} catch (error) {
  if (error instanceof TroqpayAPIError) {
    console.log(error.status);
    console.log(error.code);
    console.log(error.requestId);
  }
}
```

## Recursos disponíveis

| SDK                              | API                                  |
| -------------------------------- | ------------------------------------ |
| `troqpay.checkouts.create()`     | `POST /v1/checkouts`                 |
| `troqpay.checkouts.retrieve()`   | `GET /v1/checkouts/{checkoutId}`     |
| `troqpay.balance.retrieve()`     | `GET /v1/balance`                    |
| `troqpay.health.retrieve()`      | `GET /health`                        |
| `troqpay.withdrawals.create()`   | `POST /v1/withdrawals`               |
| `troqpay.withdrawals.retrieve()` | `GET /v1/withdrawals/{withdrawalId}` |

## Próximos passos

<CardGroup cols={3}>
  <Card title="Quickstart" href="/quickstart">
    Crie seu primeiro checkout Pix.
  </Card>

  <Card title="Autenticação" href="/authentication">
    Revise chaves, permissões e idempotência.
  </Card>

  <Card title="Plugin para agentes" href="/agents/claude-codex">
    Use Codex ou Claude com ferramentas MCP da TroqPay.
  </Card>
</CardGroup>