Autenticação

A plataforma Vexa Pay utiliza um sistema de autenticação OAuth proprietário para garantir a segurança das integrações. Esta seção explica detalhadamente como autenticar e obter um token de acesso para consumir os endpoints protegidos da API.

Visão Geral

Para acessar os endpoints protegidos da API Vexa Pay, você precisa:

  1. Ter credenciais válidas (ClientId, ClientSecret e API Key)
  2. Autenticar via endpoint POST /api/v1/oauth
  3. Obter um token de acesso (access_token)
  4. Utilizar o token nas requisições subsequentes

Ambiente de Sandbox

Ao aprovar sua solicitação de API, a Vexa Pay emite dois pares de credenciais: um de produção e um de sandbox. Os dois funcionam nos mesmos endpoints — a API identifica automaticamente qual ambiente usar pela credencial recebida no login OAuth. Não existe uma URL separada para testar: basta autenticar com a credencial de sandbox.

  • Cash-in gera um código Pix de exemplo e nunca move dinheiro real.
  • Cash-out debita apenas um saldo simulado, isolado do seu saldo de produção.
  • Boletos de sandbox têm nosso número e linha digitável fictícios, sem registro bancário.

Simulando pagamento (self-service): como não há banco real por trás do sandbox, você mesmo confirma o pagamento chamando um dos endpoints abaixo — isso dispara o webhook configurado na sua conta, permitindo testar o recebimento de ponta a ponta.

  • POST /api/v1/sandbox/cash-in/:externalId/confirmar — confirma um cash-in pendente (dispara cashin.paid)
  • POST /api/v1/sandbox/boleto/:nossoNumero/confirmar — confirma um boleto pendente (dispara boleto.paid)
  • POST /api/v1/sandbox/balance/creditar — credita saldo simulado livremente, para poder testar um cash-out (body: { "amount": 100 })

Chamar qualquer um desses três endpoints com a credencial de produção retorna403 Forbidden— eles só existem para a credencial de sandbox.

Endpoint de Autenticação Vexa Pay

Este endpoint é responsável por validar suas credenciais e retornar um token de acesso válido por 15 minutos (900 segundos).

Endpoint: /api/v1/oauth

Metado: POST

Base URL (Produção): https://api.vexapagamentos.com.br/api/v1

Headers Obrigatórios

1. Header Authorization (Basic Auth)

O header Authorization deve conter suas credenciais no formato Basic Auth, codificadas em Base64.

Header necessário:

Authorization: Basic {base64(clientId:clientSecret)}

Como montar o header Authorization:

  1. Combine ClientId e ClientSecret: Junte seu ClientId e ClientSecret separados por dois pontos (:)
    ClientId:ClientSecret
  2. Codifique em Base64: Converta a string combinada para Base64
    Base64(ClientId:ClientSecret)
  3. Adicione o prefixo "Basic ": Informe o prefixo "Basic " (com espaço) antes do valor Base64
    Basic {base64_encoded_credentials}

Exemplo Prático:

Dados de exemplo:

  • ClientId: abc123def456
  • ClientSecret: secret789xyz

Passo 1 - Combinar:

abc123def456:secret789xyz

Passo 2 - Codificar em Base64:

YWJjMTIzZGVmNDU2OnNlY3JldDc4OXh5eg==

Passo 3 - Header final:

Authorization: Basic YWJjMTIzZGVmNDU2OnNlY3JldDc4OXh5eg==

Nota: O header pode ser enviado com ou sem o prefixo "Basic ". O sistema aceita ambos os formatos, mas é recomendado usar o prefixo para seguir o padrão HTTP Basic Authentication.

2. Header x-api-key

O header x-api-key deve conter sua API Key fornecida ao gerar as credenciais.

Header necessário:

x-api-key: {sua_api_key}

Exemplo:

x-api-key: d7f9c3a1b4e8f2a5c6d9e1b3f4a7c8d9

Validação das Credenciais

O sistema valida as credenciais da seguinte forma:

  1. Decodifica o Base64 do header Authorization
  2. Extrai o ClientId e ClientSecret
  3. Verifica se o ClientId existe no banco de dados
  4. Valida se as credenciais estão ativas
  5. Compara o ClientSecret usando hash bcrypt
  6. Valida a API Key enviada no header x-api-key
  7. Atualiza o timestamp de último uso das credenciais

Resposta de Sucesso

Resposta de Sucesso (200)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

Campos da resposta:

  • access_token: Token JWT que deve ser usado nas requisições subsequentes
  • token_type: Tipo do token (sempre "Bearer")
  • expires_in: Tempo de expiração em segundos (900 = 15 minutos)

Utilizando o Token nas Requisições

Após obter o access_token, você deve incluí-lo em todas as requisições aos endpoints protegidos usando o header Authorization com o formato Bearer Token.

Header necessário:

Authorization: Bearer {access_token}

Exemplo completo de requisição:

GET /api/v1/balance
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Importante: O token expira em 15 minutos. Após a expiração, você precisará autenticar novamente para obter um novo token.

Possíveis Erros de Autenticação

Status 400 - Bad Request

Erros de validação ou formato incorreto:

{
    "message": [
        "valor must be a number conforming to the specified constraints"
    ],
    "error": "Bad Request",
    "statusCode": 400
}

Status 401 - Unauthorized

Erros de autenticação:

{
    "message": "Unauthorized",
    "statusCode": 401
}

Exemplo Completo de Requisição

Exemplo de Requisição (cURL)

curl -X POST https://api.vexapagamentos.com.br/api/v1/oauth \
  -H "Authorization: Basic YWJjMTIzZGVmNDU2OnNlY3JldDc4OXh5eg==" \
  -H "x-api-key: d7f9c3a1b4e8f2a5c6d9e1b3f4a7c8d9" \
  -H "Content-Type: application/json"

Exemplo usando JavaScript (fetch)

const clientId = 'abc123def456';
const clientSecret = 'secret789xyz';
const apiKey = 'd7f9c3a1b4e8f2a5c6d9e1b3f4a7c8d9';

// Codificar credenciais em Base64
const credentials = btoa(`${clientId}:${clientSecret}`);

const response = await fetch('https://api.vexapagamentos.com.br/api/v1/oauth', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
// Token armazenado em data.access_token

Resumo

  • ✓ Endpoint: POST /api/v1/oauth
  • ✓ Header Authorization: Basic Auth com ClientId:ClientSecret em Base64
  • ✓ Header x-api-key: Sua API Key
  • ✓ Token expira em: 15 minutos (900 segundos)
  • ✓ Use o token: Authorization: Bearer {access_token}