Autenticação

Visão Geral

Todas as chamadas à API do Payment Gateway (exceto a tokenização, que usa sua chave pública) exigem um token Bearer obtido através do endpoint /oauth/token.

Características principais:

• Tipo de concessão (grant type): Client Credentials (máquina a máquina)
• Tempo de vida do token: Curta duração (normalmente 1 hora) — solicite um novo token quando expirar
• Transporte: Sempre use HTTPS; nunca envie credenciais por conexões não criptografadas
• Armazenamento: Os tokens devem ser armazenados com segurança no lado do servidor; nunca os exponha em código do lado do cliente

Obtendo um Token de Acesso

POST /oauth/token

Requisição

curl -X POST https://{FQDN}/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "secretId": "YOUR_CLIENT_SECRET"
  }'

Resposta (Sucesso — 200)

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Resposta (Não Autorizado — 401)

{
  "status": 401,
  "message": "Unauthorized request",
  "responseCode": "SE_001"
}

Usando o Token

Inclua o token de acesso no header Authorization de todas as requisições à API:

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Boas Práticas de Gerenciamento de Tokens

1. Faça cache dos tokens — Reutilize o mesmo token até que ele expire, em vez de solicitar um novo a cada chamada à API. O endpoint de autenticação tem um limite de taxa de 60 requisições/minuto.

2. Trate a expiração de forma adequada — Ao receber uma resposta 401 ou 403, solicite um novo token e repita a requisição original.

3. Nunca exponha credenciais no lado do cliente — O clientId e o secretId devem ser usados apenas a partir do seu servidor backend (padrão Backend-for-Frontend). A única credencial do lado do cliente é a publicKey usada para a tokenização de cartões.

4. Faça a rotação dos segredos periodicamente — Entre em contato com a equipe Inyo para rotacionar seu client secret se suspeitar que ele foi comprometido.

Autenticação vs. Tokenização

Limites de Taxa

Quando o limite de taxa é atingido, a API retorna HTTP 429. Implemente backoff exponencial com jitter na sua lógica de retentativa.