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.

v1BRL · PixLive e sandbox

01 · Integração

O fluxo em poucas etapas

  1. 01

    Credenciais

    Use uma chave de API associada à conta comercial e ao ambiente correto.

  2. 02

    Criar

    Envie uma cobrança em BRL para POST /charges.

  3. 03

    Apresentar

    Use o Pix Copia e Cola devolvido pela API no checkout do comerciante.

  4. 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.

Cabeçalho HTTP
Authorization: Bearer $VALENCE_API_KEY
Content-Type: application/json

03 · Cobranças

Criar uma cobrança

POST/chargeshttps://valence.rendey.store/api/v1/charges

Campos 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 · criar cobrança
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" }
  }'
Resposta · exemplo
{
  "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 · consultar por ID
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.

PENDING

A cobrança aguarda a confirmação do pagamento.

PAID

O pagamento consta como confirmado.

EXPIRED / CANCELLED

A cobrança expirou ou foi encerrada, quando aplicável.

REFUNDED_FRAUD

A 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 · simulaçã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

HTTPUso
400JSON inválido ou parâmetro obrigatório ausente.
401Chave ausente, inválida, revogada ou de outro ambiente.
404Cobrança não encontrada para a conta/ambiente.
409Conflito durante o processamento da mesma chave de idempotência.
422Campo fora dos limites ou formato não aceito.
500Falha 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.

Links do produto