Autenticação

Nossa API utiliza chaves de autenticação via Header Authorization. Existem dois tipos principais de chaves, cada uma com escopos de permissão diferentes e casos de uso específicos.

Tipos de Chave

Chave de Cash-In

A Chave de Cash-In permite realizar operações relacionadas a transações e pagamentos:

✅ Criar e consultar pedidos (PIX, Cartão, Boleto)
✅ Tokenizar cartões de crédito
✅ Consultar status de transações
✅ Listar pedidos com filtros

A chave de cash-in pode ser usado no client-side (aplicações web, mobile), pois permite apenas criar e consultar pedidos. Ele não permite realizar saques ou acessar informações sensíveis.

Formato de uso:

Authorization: Basic SUA_CHAVE_DE_CASH_IN

Chave de Cash-Out

A Chave de Cash-Out é uma chave com permissões sensíveis, utilizada exclusivamente para operações financeiras críticas:

✅ Consultar saldo disponível e pendente
✅ Realizar saques para chaves PIX
✅ Consultar histórico de saques

NUNCA compartilhe sua Chave de Cash-Out em ambientes client-side. Esta chave deve ser mantida exclusivamente no backend e nunca exposta em código JavaScript, aplicações mobile ou qualquer ambiente acessível ao cliente.

Formato de uso:

Authorization: Bearer SUA_CHAVE_DE_CASH_OUT

Comparação das Chaves

Funcionalidade	Chave de Cash-In	Chave de Cash-Out
Criar pedidos	✅	❌
Consultar pedidos	✅	❌
Tokenizar cartão	✅	❌
Consultar saldo	❌	✅
Realizar saque	❌	✅
Uso no client-side	✅	❌
Uso no backend	✅	✅

Como Obter as Chaves

Acesse sua conta na plataforma

Navegue até a página Desenvolvedores

Copie a Chave de Cash-In para operações de transação

Copie a Chave de Cash-Out para operações financeiras (mantenha-a segura!)

Autenticação de Webhook

Configure um token de autenticação na plataforma que será enviado no header Authorization de todas as requisições de webhook:

Authorization: Bearer SEU_TOKEN_WEBHOOK

Valide o token no seu servidor:

const webhookToken = request.headers.authorization?.replace('Bearer ', '');
if (webhookToken !== 'SEU_TOKEN_WEBHOOK') {
  return res.status(401).json({ error: 'Unauthorized' });
}

Recomendamos sempre validar a origem dos webhooks para garantir a segurança da sua integração. Nunca processe webhooks sem validação adequada.

Exemplos de Uso

Criar um Pedido (Chave de Cash-In)

curl -X POST https://api.exemplo.com/v1/orders \
  -H "Authorization: Basic SUA_CHAVE_DE_CASH_IN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "payment_method": "pix"
  }'

Consultar Saldo (Chave de Cash-Out)

curl -X GET https://api.exemplo.com/v1/balance \
  -H "Authorization: Bearer SUA_CHAVE_DE_CASH_OUT"

Realizar Saque (Chave de Cash-Out)

curl -X POST https://api.exemplo.com/v1/withdrawals \
  -H "Authorization: Bearer SUA_CHAVE_DE_CASH_OUT" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "pix_key": "usuario@exemplo.com"
  }'

Boas Práticas de Segurança

Nunca exponha a Chave de Cash-Out em código client-side
Use variáveis de ambiente para armazenar chaves no backend
Valide sempre os webhooks antes de processá-los
Rotacione as chaves periodicamente para maior segurança
Use HTTPS para todas as requisições

Se você suspeitar que alguma chave foi comprometida, revogue-a imediatamente na plataforma e gere uma nova.

Autenticação

On this page