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

# Quickstart

> Integre o Thalpay ao seu sistema em minutos

## 1. Obtenha suas credenciais

Acesse o [Dashboard Thalpay](https://dashboard.thalbank.com) e crie sua conta. Apos aprovacao do cadastro, voce tera acesso ao painel para gerar suas API Keys.

## 2. Autentique-se

Existem duas formas de autenticacao:

<Tabs>
  <Tab title="API Key (recomendado)">
    Envie sua API Key no header de cada requisicao:

    ```bash theme={null}
    curl -X GET https://api.thalbank.com/transactions \
      -H "x-api-key: sua_api_key_aqui"
    ```
  </Tab>

  <Tab title="JWT Token">
    Faca login para obter um token Bearer:

    ```bash theme={null}
    curl -X POST https://api.thalbank.com/login \
      -H "Content-Type: application/json" \
      -d '{
        "email": "seu@email.com",
        "password": "sua_senha"
      }'
    ```

    Use o `accessToken` retornado:

    ```bash theme={null}
    curl -X GET https://api.thalbank.com/transactions \
      -H "Authorization: Bearer eyJhbGciOi..."
    ```
  </Tab>
</Tabs>

## 3. Crie sua primeira transacao PIX

```bash theme={null}
curl -X POST https://api.thalbank.com/transactions \
  -H "x-api-key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "amount": 1500,
    "method": "PIX",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "phone": "11999999999",
      "documentType": "CPF",
      "document": "12345678901"
    },
    "items": [
      {
        "title": "Produto Exemplo",
        "amount": 1500,
        "quantity": 1,
        "tangible": true
      }
    ]
  }'
```

**Resposta:**

```json theme={null}
{
  "status": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 1500,
    "method": "PIX",
    "status": "PENDING",
    "pixQrCode": "00020126580014br.gov.bcb.pix...",
    "pixQrCodeBase64": "data:image/png;base64,...",
    "expiresAt": "2026-03-10T01:00:00.000Z",
    "createdAt": "2026-03-10T00:00:00.000Z"
  }
}
```

## 4. Receba notificacoes via Webhook

Registre uma URL para receber notificacoes quando o pagamento for confirmado:

```bash theme={null}
curl -X POST https://api.thalbank.com/webhooks \
  -H "x-api-key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhooks/thalpay",
    "eventType": "TRANSACTION"
  }'
```

Quando o comprador pagar, seu endpoint recebera:

```json theme={null}
{
  "event": "TRANSACTION_UPDATED",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PAID",
    "amount": 1500,
    "method": "PIX",
    "paidAt": "2026-03-10T00:05:00.000Z"
  }
}
```

## 5. Consulte seu saldo

```bash theme={null}
curl -X GET https://api.thalbank.com/seller-wallet/gestao \
  -H "x-api-key: sua_api_key_aqui"
```

```json theme={null}
{
  "status": true,
  "data": {
    "availableBalance": 1350,
    "blockedBalance": 0,
    "totalBalance": 1350,
    "currency": "BRL"
  }
}
```

<Note>
  O saldo disponivel ja desconta as taxas do gateway. Todos os valores sao em **centavos**.
</Note>

## Proximos passos

<CardGroup cols={2}>
  <Card title="Autenticacao" icon="lock" href="/guides/authentication">
    JWT vs API Key, refresh tokens e boas praticas.
  </Card>

  <Card title="Idempotencia" icon="shield" href="/guides/idempotency">
    Como evitar cobracas duplicadas em caso de retry.
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Configure e valide webhooks para seu sistema.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/guides/errors">
    Codigos de erro e como trata-los.
  </Card>
</CardGroup>