API pública · REST · JSON
Cobranças Pix para o checkout da sua empresa.
Crie uma cobrança em reais, receba um link de checkout e instruções Pix, e consulte o status pelo identificador da cobrança. Esta referência descreve os endpoints implementados para comerciantes.
01 · Integração
O fluxo em poucas etapas
- 01
Credenciais
Use uma chave de API associada à conta comercial e ao ambiente correto.
- 02
Criar
Envie uma cobrança em BRL para POST /charges.
- 03
Apresentar
Use o Pix Copia e Cola devolvido pela API no checkout do comerciante.
- 04
Confirmar
Consulte GET /charges/{id}; só libere o pedido quando o status indicar confirmação.
02 · Segurança
Autenticação
Envie a chave no cabeçalho Authorization: Bearer. As chaves de teste e produção pertencem a ambientes diferentes. Armazene-as em segredo do servidor e não as inclua no JavaScript do navegador, em aplicativos públicos ou em repositórios.
Authorization: Bearer $VALENCE_API_KEY
Content-Type: application/json03 · Cobranças
Criar uma cobrança
/chargeshttps://valence.rendey.store/api/v1/chargesCampos aceitos: amountBRL (obrigatório, de R$ 1 a R$ 50.000, até duas casas decimais), currency (BRL), externalReference, customerDetails, expiresInMinutes (5 a 1440, padrão 30) e metadata.
curl -X POST 'https://valence.rendey.store/api/v1/charges' -H 'Authorization: Bearer $VALENCE_API_KEY' -H 'Idempotency-Key: pedido-10052' -H 'Content-Type: application/json' -d '{
"amountBRL": 149.90,
"currency": "BRL",
"externalReference": "pedido-10052",
"expiresInMinutes": 30,
"customerDetails": {
"name": "Cliente de demonstração",
"email": "cliente@example.com"
},
"metadata": { "pedido": "10052" }
}'{
"success": true,
"environment": "SANDBOX",
"isSandbox": true,
"chargeId": "chg_exemplo",
"paymentUrl": "https://valence.rendey.store/pay/chg_exemplo",
"checkoutUrl": "https://valence.rendey.store/pay/chg_exemplo",
"pixPayload": "000201...",
"status": "OPEN",
"amountBRL": 149.9,
"amountUSDC": 26.21,
"currency": "BRL",
"externalReference": "pedido-10052",
"expiresAt": "2026-10-27T15:30:00.000Z"
}O cabeçalho opcional Idempotency-Key permite repetir a mesma solicitação sem criar uma nova cobrança quando a requisição anterior ficou sem resposta. Reutilize a mesma chave apenas para a mesma operação.
04 · Acompanhamento
Consultar uma cobrança
Consulte pelo identificador da cobrança. A chave deve pertencer ao mesmo comerciante e ambiente usados na criação.
curl 'https://valence.rendey.store/api/v1/charges/chg_exemplo' -H 'Authorization: Bearer $VALENCE_API_KEY'Também é possível consultar a rota de cobranças com ?id=... ou ?external_reference=.... A resposta inclui status, valores em reais, validade e os dados disponíveis para conciliação.
PENDINGA cobrança aguarda a confirmação do pagamento.
PAIDO pagamento consta como confirmado.
EXPIRED / CANCELLEDA cobrança expirou ou foi encerrada, quando aplicável.
REFUNDED_FRAUDA cobrança foi marcada para devolução após uma divergência analisada.
05 · Testes
Sandbox: simulação sem fundos reais
Use a rota de sandbox para validar o tratamento da resposta e a interface do seu checkout. Ela devolve dados simulados; não inicia um Pix real, não movimenta saldo e não comprova liquidação.
curl -X POST 'https://valence.rendey.store/api/v1/charges/sandbox' -H 'Authorization: Bearer val_sandbox_SUBSTITUA' -H 'Content-Type: application/json' -d '{ "amountBRL": 149.90, "externalReference": "teste-10052" }'O status inicial da resposta simulada é OPEN. Não trate a simulação como pagamento de produção nem use os dados demonstrativos em conciliação.
06 · Diagnóstico
Erros e boas práticas
| HTTP | Uso |
|---|---|
| 400 | JSON inválido ou parâmetro obrigatório ausente. |
| 401 | Chave ausente, inválida, revogada ou de outro ambiente. |
| 404 | Cobrança não encontrada para a conta/ambiente. |
| 409 | Conflito durante o processamento da mesma chave de idempotência. |
| 422 | Campo fora dos limites ou formato não aceito. |
| 500 | Falha interna; registre o identificador da requisição e tente novamente com segurança. |
Não envie dados de cartão, senhas, chave privada de carteira ou documentos além dos campos previstos. Tarifas, limites e condições de liquidação são definidos pela conta e pelo contrato comercial.