A autenticação é o primeiro passo para integrar com a FastPay API. Este guia irá mostrar como obter e usar suas credenciais de forma segura.
Visão Geral
Nossa API utiliza autenticação Basic Auth com API keys seguras. Todas as requisições devem incluir o header de autorização para serem processadas.
Características de Segurança
- API keys únicas por merchant
- HTTPS obrigatório em todas as requisições
- Autenticação baseada em padrões da indústria
Obtendo suas Credenciais
Passo 1: Acesse o Painel
- Navegue até o painel da FastPay
- Faça login em sua conta
- Acesse Configurações
- Selecione Chave de API
Passo 2: Gere sua API Key
Guarde sua API key em um local seguro! Por motivos de segurança, ela será exibida apenas uma vez.
# Exemplo de API key
sk_9a8s7d6f5g4h3j2k1l0z9x8c7v6b5n4m3
Como Usar
# Formato: SUA_API_KEY: convertido para Base64
Authorization: Basic <token_base64>
# Se sua API key for: sk_abc123
# Combine: sk_abc123:
# Resultado em Base64: c2tfYWJjMTIzOg==
# Header: Authorization: Basic c2tfYWJjMTIzOg==
Exemplos de Implementação
JavaScript (Node.js)
const axios = require('axios');
const apiKey = 'sk_9a8s7d6f5g4h3j2k1l0z9x8c7v6b5n4m3';
const credentials = Buffer.from(`${apiKey}:`).toString('base64');
axios.get('https://api-global.fastpaybrasil.com/v1/payment-methods', {
headers: {
Authorization: `Basic ${credentials}`,
}
});
cURL
curl -X GET "https://api-global.fastpaybrasil.com/v1/payment-methods" \
-H "Authorization: Basic $(echo -n 'sua_api_key:' | base64)"
PHP
<?php
$apiKey = 'sk_9a8s7d6f5g4h3j2k1l0z9x8c7v6b5n4m3';
$credentials = base64_encode("$apiKey:");
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api-global.fastpaybrasil.com/v1/payment-methods',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Basic ' . $credentials,
'Content-Type: application/json'
]
]);
$response = curl_exec($curl);
curl_close($curl);
?>
Python
import requests
import base64
api_key = 'sk_9a8s7d6f5g4h3j2k1l0z9x8c7v6b5n4m3'
credentials = base64.b64encode(f'{api_key}:'.encode()).decode()
headers = {
'Authorization': f'Basic {credentials}',
'Content-Type': 'application/json'
}
response = requests.get(
'https://api-global.fastpaybrasil.com/v1/payment-methods',
headers=headers
)
Boas Práticas de Segurança
1. Armazenamento Seguro
Nunca faça isso:
// INSEGURO - API key exposta no código
const apiKey = 'sk_9a8s7d6f5g4h3j2k1l0z9x8c7v6b5n4m3';
// SEGURO - API key em variável de ambiente
const apiKey = process.env.FASTPAY_API_KEY;
2. Variáveis de Ambiente
Configure suas variáveis de ambiente:
# Configure sua variável de ambiente
export FASTPAY_API_URL="https://api-global.fastpaybrasil.com"
export FASTPAY_API_KEY="sua_api_key_aqui"
3. Diretrizes Gerais
- Nunca exponha sua API key em código client-side
- Use variáveis de ambiente para armazenar chaves
- Rotacione chaves periodicamente
- Use HTTPS sempre para comunicação
- Monitore logs de acesso para atividades suspeitas
Tratamento de Erros
Erro 401 - Não Autorizado
{
"message": "Unauthorized",
"statusCode": 401
}
- API key inválida ou expirada
- Header de autorização ausente
- Formato incorreto do header
Erro 403 - Proibido
{
"message": "Forbidden",
"statusCode": 403
}
- API key sem permissões para o recurso
- Acesso negado para a operação solicitada
Próximos Passos
Agora que você está autenticado, explore:
Para dúvidas sobre autenticação, consulte nosso site oficial.
Ambientes
A FastPay usa a mesma URL base para sandbox e produção. O ambiente é determinado apenas pela chave de API utilizada — não pela URL. Use a chave de teste para o sandbox e a chave live para produção; o endpoint é exatamente o mesmo.
| Ambiente | URL Base | Descrição |
|---|
| Produção | https://api-global.fastpaybrasil.com | Ambiente de produção com transações reais |
| Sandbox | https://api-global.fastpaybrasil.com | Ambiente de testes — mesma URL, alterando apenas a chave de API |
Gerando a chave de teste
Para gerar a chave de API de teste e operar no sandbox:
- Acesse o painel da FastPay e faça login.
- No canto superior direito (onde aparecem seu nome e e-mail), abra o menu e ative o Modo Teste.
- Com o Modo Teste ativo, você verá todas as movimentações de teste e poderá gerar a chave de API de teste.
Use essa chave de teste nas requisições para operar no sandbox, sem transações reais. Para produção, utilize a chave live (com o Modo Teste desativado).
Nunca compartilhe sua chave live em código client-side, repositórios públicos ou mensagens. Rotacione imediatamente se suspeitar de comprometimento.
Idempotência
A API FastPay não suporta o header Idempotency-Key.
Para evitar cobranças duplicadas em caso de timeout ou retry, consulte o status do charge antes de reenviar a requisição:
curl -X GET "https://api-global.fastpaybrasil.com/v1/charges/<chargeId>" \
-H "Authorization: Basic $(echo -n 'sua_api_key:' | base64)"
pending, paid, etc.), não crie um novo.
Paginação
Os endpoints de listagem utilizam os parâmetros page e size (não limit):
| Parâmetro | Tipo | Padrão | Descrição |
|---|
page | integer | 1 | Número da página (base 1) |
size | integer | varia | Quantidade de itens por página |
GET /v1/charges?page=2&size=20
Ordenação
Use o parâmetro orderBy para controlar a ordem dos resultados:
| Formato | Direção | Exemplo |
|---|
campo | Ascendente (A→Z / mais antigo→mais novo) | orderBy=createdAt |
-campo | Descendente (Z→A / mais novo→mais antigo) | orderBy=-createdAt |
| Múltiplos campos | Separados por vírgula | orderBy=-createdAt,amount |
GET /v1/charges?page=1&size=20&orderBy=-createdAt
