Autenticação

OAuth2 + mTLS

A API Versell utiliza o protocolo OAuth2 com o fluxo client_credentials combinado com certificados mTLS (Mutual TLS) para autenticação. Isso garante dois níveis de segurança: a identidade do cliente é verificada tanto pelo certificado digital quanto pelas credenciais OAuth2.

Certificado mTLS

O mTLS (Mutual TLS) exige que tanto o cliente quanto o servidor apresentem certificados digitais durante o handshake TLS. Você receberá da Versell os seguintes arquivos:

Fica a critério do desenvolvedor qual formato utilizar. Os exemplos abaixo usam .crt + .key, mas você pode adaptar para .pfx conforme sua stack:

curl -X POST https://api.pix.basspago.com.br/oauth/token \
  --cert ./client.crt \
  --key ./client.key \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET"

Esses arquivos devem ser enviados em todas as requisições HTTP à API, incluindo a obtenção do token.

Obtendo um Token

O corpo da requisição deve ser URL-encoded com os seguintes parâmetros:

Token Cash In

curl -X POST https://api.pix.basspago.com.br/oauth/token \
  --cert ./client.crt \
  --key ./client.key \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials"

Token Cash Out

curl -X POST https://pagamentos.basspago.com.br/oauth/token \
  --cert ./client.crt \
  --key ./client.key \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials"

Resposta do Token

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 300
}

Usando o Token

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

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Estratégia de Renovação de Token

Recomendamos as seguintes práticas para gerenciar tokens:

• Armazene o token em cache junto com o timestamp de expiração
• Renove o token com 30-60 segundos de antecedência antes da expiração
• Em caso de erro 401, solicite um novo token e repita a requisição
• Nunca solicite um novo token para cada requisição individual

Erros Comuns