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`	Somente em `POST /v1/submerchants`	UUID v4 único por operação lógica 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

Apenas o endpoint POST /v1/submerchants exige 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 — evitando duplicidade. Se a chave for reutilizada com payload diferente, a API responde HTTP 409 Conflict.

Rate limit

Os endpoints de subcontas (/v1/submerchants — criação, atualização cadastral, atualização de taxas e atualização de conta bancária) têm limite de 5 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

​Rate limit

Headers obrigatórios

Exemplo

Idempotência

Rate limit