Referência da API

URL, autenticação, formato das respostas, limites e convenções da API REST da Valora.

A API da Valora é REST, recebe e devolve JSON e usa os status HTTP padrão. Todas as rotas ficam em /v1.

Início rápido

A primeira cobrança em poucos minutos.

Webhooks

Confirmação dos pagamentos no seu servidor.

URL base

https://api.valorapayments.com.br

A mesma URL atende teste e produção. O ambiente vem da chave usada. Veja Teste e produção.

Autenticação

Envie a chave no header Authorization, no formato Bearer:

curl https://api.valorapayments.com.br/v1/payments \
  -H "Authorization: Bearer sk_vl_..."

Situação	Resposta
Sem header ou com formato inválido	401 invalid_api_key
Chave revogada ou inexistente	401 invalid_api_key
Chave sem o escopo da rota	403 missing_scope
Chave de produção com a empresa ainda em análise	403 business_not_active

Use a chave só no servidor. Veja Chaves de API para escopos e revogação.

Convenções

Dinheiro

Onde	Formato	Exemplo
Entrada (corpo da requisição)	reais, texto ou número, até 2 casas, ponto decimal	"149.90"
Saída (respostas e webhooks)	centavos, inteiro	14990

A moeda é sempre BRL. O valor mínimo é 0.01.

Ids

Todo objeto tem um id com prefixo:

Prefixo	Objeto
pay_	pagamento
cs_	compra (sessão de checkout)
cus_	cliente
prod_	produto
ref_	devolução
we_	endpoint de webhook
whd_	entrega de webhook
evt_	evento

Datas

Datas vêm em ISO 8601, em UTC: 2026-11-14T15:02:11.000Z.

Campos opcionais

Campos sem valor vêm como null, nunca omitidos. Nas rotas PATCH, enviar null limpa o campo.

external_reference e metadata

• external_reference: o seu identificador (id do pedido, SKU), até 100 caracteres. Use para conciliar e para buscar.
• metadata: até 20 pares de chave e valor em texto (chave até 40, valor até 500 caracteres). Volta igual em todas as respostas e webhooks.

Não coloque dados sensíveis (senhas, números de cartão, documentos completos) em metadata.

Respostas

Sucesso: o objeto, ou uma lista.

{ "id": "pay_Xk2v9QeR7tLmN3bA", "object": "payment", "status": "succeeded" }

Erro: sempre no mesmo formato. Veja Erros.

{ "error": { "type": "not_found", "message": "Pagamento não encontrado." } }

Limites

Limite	Valor
Requisições por chave	300 por minuto
Requisições sem chave válida	60 por minuto por IP
Tamanho do corpo	256 KB

Passou do limite? A resposta é 429 rate_limited com o header Retry-After (em segundos).

Recursos

Pagamentos

Cobranças Pix, cancelamento e devolução.

Checkouts

Compras com página de pagamento pronta.

Clientes

Dados de quem compra.

Produtos

Catálogo e preços.

Saldo

Disponível e a liberar.

Webhooks

Endpoints, entregas e segredos.