Introdução

A API pública da UvviPay permite que parceiros e integradores criem subcontas (submerchants), processem pagamentos, autentiquem transações 3DS e tokenizem cartões de forma programática.

​

O que você pode fazer

​

Subcontas

• Criar uma nova subconta enviando dados cadastrais e documentos
• Consultar e atualizar dados cadastrais
• Gerenciar taxas aplicadas a cada subconta
• Cadastrar e atualizar conta bancária ou chave PIX para repasse
• Acompanhar o status de aprovação

​

Pagamentos

• Criar transações com PIX, cartão de crédito ou boleto (valores em centavos)
• No PIX, configurar a validade do QR por cobrança com pix.expiration (segundos ou data ISO 8601); o padrão é 30 minutos — ver Criar pagamento
• No boleto, o customer.address é obrigatório e o vencimento opcional fica em boleto.expirationDate (padrão 30 dias) — ver Boleto
• Dividir o valor líquido entre subcontas com split de pagamento
• Cobrar uma oferta adicional no mesmo cartão em até 15 minutos com o token de upsell — ver Upsell com um clique
• Consultar o status e detalhes de uma transação pelo id

​

3DS

• Gerar token 3DS para iniciar a autenticação
• Iniciar autenticação 3DS com dados de cartão e dispositivo
• Obter resultados pós-challenge (ECI, CAVV/UCAF, transactionIds)
• Embarcar o fluxo no front-end via script oficial: GET https://js.uvvipay.com.br/3ds.js

​

Cofre

• Tokenizar cartão de crédito e obter um cardTokenId
• Reutilizar o mesmo token quando customer e cartão já possuem token ativo
• Ver o guia: Cofre

​

URL base

​

Prefixos

​

Conceitos importantes

• Valores em centavos: todo amount é inteiro em centavos (R$ 75,00 = 7500).
• Autenticação: a maioria dos endpoints exige client-id + client-secret em cabeçalhos. Algumas rotas de 3DS exigem apenas client-id (ver detalhes na referência).
• Idempotência: POST /v1/submerchants exige x-idempotency-key (UUID v4) por operação lógica. Em POST /v1/payments o header é opcional e recomendado para retry seguro após timeout (ver Autenticação).
• Rate limit: 10 requisições/minuto por credencial nos endpoints de subcontas (/v1/submerchants); 30 requisições/minuto por IP em POST /v1/vault/tokenize.

​

Formato

• Requests JSON: Content-Type: application/json
• Upload de documentos (criação e onboarding de subconta): Content-Type: multipart/form-data
• Respostas sempre em application/json

​

Próximos passos