Autenticação

A API Xfin usa autenticação por API Key via header HTTP. Toda requisição a endpoints protegidos deve incluir o header X-Api-Key com a chave do parceiro.

Como funciona

Cada parceiro recebe uma API Key exclusiva no momento do onboarding. A chave:

• É emitida por parceiro — cada integração possui credencial própria.
• É comparada de forma timing-safe no servidor (usando ConstantTimeCompare), o que elimina ataques de timing por canal lateral.
• É hashed com SHA-256 antes de ser persistida — nunca armazenada em texto plano. O valor raw é retornado apenas uma vez, no momento da criação.

Fazendo uma requisição autenticada

Inclua o header X-Api-Key em toda requisição a endpoints protegidos:

curl

curl -s -X POST "https://xfin-payouts-ys3int7llq-rj.a.run.app/v1/payouts" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sua-api-key-aqui" \
  -d '{
    "amount_brl": 100.00,
    "receiver_wallet": "0xEnderecoCarteira",
    "pix_key": "pagador@email.com",
    "pix_key_type": "EMAIL"
  }'

JavaScript (fetch)

const response = await fetch(
  'https://xfin-payouts-ys3int7llq-rj.a.run.app/v1/payouts',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': process.env.XFIN_API_KEY,
    },
    body: JSON.stringify({
      amount_brl: 100.00,
      receiver_wallet: '0xEnderecoCarteira',
      pix_key: 'pagador@email.com',
      pix_key_type: 'EMAIL',
    }),
  }
);

Python (requests)

import os, requests

resp = requests.post(
    "https://xfin-payouts-ys3int7llq-rj.a.run.app/v1/payouts",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": os.environ["XFIN_API_KEY"],
    },
    json={
        "amount_brl": 100.00,
        "receiver_wallet": "0xEnderecoCarteira",
        "pix_key": "pagador@email.com",
        "pix_key_type": "EMAIL",
    },
)

Note

Nomes de headers HTTP são case-insensitive pela especificação HTTP/1.1. X-Api-Key, X-API-Key e x-api-key são tratados de forma idêntica pelo servidor. Use o casing que preferir na sua integração.

Endpoints protegidos

Método	Endpoint	Header obrigatório
POST	/v1/payouts	X-Api-Key
GET	/v1/payouts/{id}	X-Api-Key
GET	/v1/payouts	X-Api-Key

Os endpoints /health, /metrics e /webhooks/4pay são públicos e não requerem autenticação.

Isolamento por parceiro

A API Key identifica o parceiro em todas as operações:

• Payouts criados ficam escopados ao parceiro — a GET /v1/payouts/{id} retorna 404 se o payout existir, mas pertencer a outro parceiro.
• A listagem GET /v1/payouts retorna apenas os payouts do parceiro autenticado.
• A idempotência (header Idempotency-Key) também é escopada por parceiro — a mesma chave usada por dois parceiros distintos não gera conflito.

Erros de autenticação

Requisições sem header ou com chave inválida recebem 401 Unauthorized:

{ "error": "unauthorized" }

Situação	Status
Header X-Api-Key ausente	401
Chave inválida ou revogada	401
Chave válida, mas payout de outro parceiro	404

Boas práticas de segurança

Caution

Nunca exponha sua API Key em código client-side (JavaScript de browser, apps mobile) ou em repositórios públicos. Ela dá acesso completo à sua conta.

• Variáveis de ambiente: injete a chave via variável de ambiente (XFIN_API_KEY) e nunca a escreva no código-fonte.
• Secrets manager: em produção, use um serviço de gestão de segredos (AWS Secrets Manager, Google Secret Manager, HashiCorp Vault).
• Rotação: se suspeitar de comprometimento, entre em contato com o suporte para revogar e emitir uma nova chave.
• Rate limiting: a API aplica limite de 100 requisições por minuto por chave. Requisições além desse limite recebem 429 Too Many Requests com o header Retry-After indicando quando tentar novamente.