Quickstart

1. Obtenha suas credenciais

Acesse o Dashboard Thalpay 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:

API Key (recomendado)
JWT Token

Envie sua API Key no header de cada requisicao:

curl -X GET https://api.thalbank.com/transactions \
  -H "x-api-key: sua_api_key_aqui"

Faca login para obter um token Bearer:

curl -X POST https://api.thalbank.com/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "sua_senha"
  }'

Use o accessToken retornado:

curl -X GET https://api.thalbank.com/transactions \
  -H "Authorization: Bearer eyJhbGciOi..."

3. Crie sua primeira transacao PIX

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": "[email protected]",
      "phone": "11999999999",
      "documentType": "CPF",
      "document": "12345678901"
    },
    "items": [
      {
        "title": "Produto Exemplo",
        "amount": 1500,
        "quantity": 1,
        "tangible": true
      }
    ]
  }'

Resposta:

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

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:

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

curl -X GET https://api.thalbank.com/seller-wallet/gestao \
  -H "x-api-key: sua_api_key_aqui"

{
  "status": true,
  "data": {
    "availableBalance": 1350,
    "blockedBalance": 0,
    "totalBalance": 1350,
    "currency": "BRL"
  }
}

O saldo disponivel ja desconta as taxas do gateway. Todos os valores sao em centavos.

Proximos passos

Autenticacao

JWT vs API Key, refresh tokens e boas praticas.

Idempotencia

Como evitar cobracas duplicadas em caso de retry.

Webhooks

Configure e valide webhooks para seu sistema.

Erros

Codigos de erro e como trata-los.

Getting Started

Core Concepts

1. Obtenha suas credenciais

2. Autentique-se

3. Crie sua primeira transacao PIX

4. Receba notificacoes via Webhook

5. Consulte seu saldo

Proximos passos

Autenticacao

Idempotencia

Webhooks

Erros

​1. Obtenha suas credenciais

​2. Autentique-se

​3. Crie sua primeira transacao PIX

​4. Receba notificacoes via Webhook

​5. Consulte seu saldo

​Proximos passos

Autenticacao

Idempotencia

Webhooks

Erros

1. Obtenha suas credenciais

2. Autentique-se

3. Crie sua primeira transacao PIX

4. Receba notificacoes via Webhook

5. Consulte seu saldo

Proximos passos