COMECE AQUI

Autenticação e Scopes OAuth2

A API ValidaPay usa OAuth2 com o fluxo client_credentials. Você troca suas credenciais por um Bearer Token e usa esse token em todas as chamadas.

Como obter o token

POST https://oauth2-sandbox.validapay.com.br/auth/token
# Sandbox
curl -X POST "https://oauth2-sandbox.validapay.com.br/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "scope=pix.cob/write"

# Produção
curl -X POST "https://oauth2.validapay.com.br/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "scope=pix.cob/write"
Response 200 OK
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use o access_token no header Authorization: Bearer <token> em todas as requisições.

Solicite apenas os scopes necessários

Incluir qualquer scope que suas credenciais não têm permissão retorna 403 Unauthorized scope imediatamente — mesmo que os outros scopes estejam corretos. Use sempre o conjunto mínimo de scopes para a operação desejada.

Scopes por operação

Use a tabela abaixo para saber exatamente qual scope incluir no campo scope ao gerar o token.

OperaçãoEndpointScope necessário
Criar cobrança PixPOST /v1/chargespix.cob/write
Criar cobrança BoletoPOST /v1/charges/singlecheckouts/write
Criar cobrança CartãoPOST /v1/charges/singlecheckouts/write
Buscar / listar cobrançasGET /v1/charges{/:id}pix.cob/read
Cancelar cobrançaDELETE /v1/charges/:idpix.cob/write
Tokenizar cartãoPOST /v1/payment-methods/tokenizepayment.methods/write(token separado)

Tokenização usa um token M2M separado

O scope payment.methods/write é usado exclusivamente para tokenizar cartões. Gere um token separado com esse scope para chamar o SDK de tokenização. Não misture esse scope no mesmo token utilizado para criar cobranças, a menos que suas credenciais tenham permissão para ambos.

Todos os scopes disponíveis

pix.cob/read
pix.cob/write
wallet/read
wallet/write
products/read
products/write
proposals/read
proposals/write
subscriptions/read
subscriptions/write
checkouts/read
checkouts/write
customers/read
customers/write
subaccounts/read
coupons/read
coupons/write
payment.methods/write

Próximos Passos