Autenticação - UvviPay Public API

A API pública utiliza autenticação via dois headers obrigatórios em toda requisição. A criação de subconta exige ainda um header de idempotência.

Headers obrigatórios

Header	Obrigatoriedade	Descrição
`client-id`	Sempre	Identificador público da sua credencial
`client-secret`	Sempre	Secret da sua credencial. Nunca exponha em código client-side
`x-idempotency-key`	Obrigatório em `POST /v1/submerchants`, `POST /v2/submerchants/onboarding/pf` e `POST /v2/submerchants/onboarding/pj`; opcional em `POST /v1/payments`	Chave única por operação lógica (ex.: UUID v4) para evitar duplicação em retries

Exemplo

curl -X POST https://api.uvvipay.com.br/v1/submerchants \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "x-idempotency-key: 5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f" \
  -F "documentNumber=12345678000199" \
  -F "documentType=cnpj" \
  -F "phone=11999999999"

Idempotência

Subcontas (`POST /v1/submerchants` e onboarding v2)

Os endpoints POST /v1/submerchants, POST /v2/submerchants/onboarding/pf e POST /v2/submerchants/onboarding/pj exigem o header x-idempotency-key. Envie um UUID gerado pelo seu sistema; se a requisição for repetida com a mesma chave e mesmo payload, você receberá a mesma resposta da primeira execução, sem duplicidade. Se a chave for reutilizada com payload diferente, a API responde HTTP 409 Conflict.

Pagamentos (`POST /v1/payments`)

O header x-idempotency-key é opcional (até 255 caracteres; recomendamos um UUID v4 por operação de pagamento). Ele existe para evitar cobrança duplicada quando sua requisição sofre timeout e você precisa reenviar:

Envie o pagamento com uma chave nova.
Se receber timeout ou erro de rede, reenvie a mesma requisição com a mesma chave e o mesmo payload.
Se o pagamento original foi criado, a API devolve a transação existente com o estado atual, sem cobrar novamente. Caso contrário, o pagamento é processado normalmente.

Comportamentos de erro:

Situação	Resposta
Mesma chave com payload diferente	HTTP 422 com `code: IDEMPOTENCY_PAYLOAD_MISMATCH`
Mesma chave enquanto a primeira requisição ainda está em processamento	HTTP 409 com `code: PAYMENT_IN_PROGRESS`; aguarde e tente novamente

Quando a primeira tentativa termina em estado desconhecido (ex.: erro técnico na comunicação com a adquirente), a chave permanece protegida e novas tentativas recebem HTTP 409 até a operação ser vinculada a uma transação local (reconciliação) ou resolvida operacionalmente. Não há reprocessamento automático da cobrança após timeout ou 5xx. Sem o header, o comportamento do endpoint permanece o de sempre: cada requisição cria uma nova cobrança. No fluxo de upsell, o replay da origem retorna o mesmo upsell.token enquanto o token estiver válido. O replay da cobrança de upsell retorna a mesma transação de upsell, mesmo com o token já consumido.

Bearer token (OAuth2)

A API também emite bearer tokens pelo fluxo OAuth2 client_credentials, em POST /oauth/token. O token expira em 3600 segundos.

Crie o client_id e o client_secret no painel, em Configurações → API Clients. O client_secret aparece uma única vez.
Emita o token com as credenciais no body ou no header Authorization: Basic.
Envie o token no header Authorization: Bearer <access_token>.

curl -X POST https://api.uvvipay.com.br/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"SEU_CLIENT_ID","client_secret":"SEU_CLIENT_SECRET"}'

NOTA: os endpoints v1 continuam com autenticação por headers client-id e client-secret. A documentação de cada endpoint indicará quando ele aceitar o bearer token.

Rate limit

Os endpoints de subcontas (/v1/submerchants para criação, atualização cadastral, atualização de taxas e atualização de conta bancária; POST /v2/submerchants/onboarding/pf e POST /v2/submerchants/onboarding/pj) têm limite de 10 requisições por minuto por credencial. Se exceder, você recebe HTTP 429 Too Many Requests. O endpoint do Cofre (POST /v1/vault/tokenize) tem limite de 30 requisições por minuto por IP.

Nunca exponha client-secret no front-end ou em repositórios públicos. Faça a chamada sempre a partir do seu backend.

​Headers obrigatórios

​Exemplo

​Idempotência

​Subcontas (POST /v1/submerchants e onboarding v2)

​Pagamentos (POST /v1/payments)

​Bearer token (OAuth2)

​Rate limit

Headers obrigatórios

Exemplo

Idempotência

Subcontas (`POST /v1/submerchants` e onboarding v2)

Pagamentos (`POST /v1/payments`)

Bearer token (OAuth2)

Rate limit