Autenticação

A API da Vellus Payments aceita só o cabeçalho Authorization: Bearer. O token é obtido pelo fluxo de credenciais de cliente do OAuth 2.0 (RFC 6749, seção 4.4), usado por sistemas integradores: não há usuário envolvido, e o seu sistema se identifica com o client_id e o client_secret de uma credencial.

Em implantação

Esta página descreve o contrato de autenticação que a Vellus Payments publica para integradores. O endpoint POST /connect/token ainda não está disponível no sandbox. Integre pelo endpoint descrito aqui somente quando o changelog anunciar a disponibilidade.

Pedir um token

Envie um POST para /connect/token com o corpo application/x-www-form-urlencoded e grant_type=client_credentials. O cliente se autentica por client_secret_basic, com o cabeçalho Authorization: Basic, ou por client_secret_post, com client_id e client_secret no corpo.

curl -X POST https://api-payments.sand-fintech.com/connect/token \
  -u "<seu client_id>:<seu client_secret>" \
  -d "grant_type=client_credentials" \
  -d "scope=payment.write"

O parâmetro scope é opcional. Quando enviado, lista os escopos desejados, separados por espaço, dentro do que a sua credencial recebeu.

O token

A resposta traz access_token, token_type (sempre Bearer) e expires_in, em segundos. O token é um JWT assinado com ES256. Para validar a assinatura, use a chave pública do endereço jwks_uri que está no discovery em /.well-known/openid-configuration.

Tokens de sistema valem no máximo 15 minutos. Reutilize o token até perto do vencimento e só então peça outro. Pedir um token a cada chamada sobrecarrega o endpoint e consome o limite de taxa da sua credencial.

Escopos e audiência

Os escopos seguem o formato recurso.ação, por exemplo payment.write para criar pagamentos e payment.read para consultá-los. Cada cliente recebe só os escopos que a sua integração precisa, e a lista é fixada no cadastro.

A audiência (aud) identifica o serviço que vai aceitar o token. Ela vem do cadastro do seu cliente. Se o seu cadastro tiver mais de uma audiência, informe o parâmetro resource com o valor desejado.

O tenant vem da claim do token. Você não informa o tenant em nenhum cabeçalho ou parâmetro. Uma chamada a um recurso fora do tenant da credencial recebe 403 com o código TENANT_SCOPE_MISMATCH.

Erros do endpoint de token

O endpoint devolve os erros no formato da seção 5.2 do RFC 6749, em application/json, com os campos error e error_description. O campo correlationId identifica a chamada nos registros da Vellus Payments.

Status	error	Quando acontece
401	invalid_client	Cliente inexistente, inativo ou segredo errado. A resposta é a mesma nos três casos.
400	invalid_request	Corpo ou cabeçalho malformado.
400	unsupported_grant_type	grant_type diferente de client_credentials.
400	invalid_scope	Escopo que a sua credencial não recebeu.
400	invalid_target	resource fora da lista de audiências da sua credencial.

O limite de taxa responde 429 com o cabeçalho Retry-After. Espere o tempo indicado antes de tentar de novo.

Endpoints anteriores

Os endpoints de autenticação anteriores ao /connect/token serão removidos antes da entrada em produção. Integrações novas devem usar só o /connect/token.