Visão Geral & Arquitetura

Documentação Oficial da API Valence

A API pública da Valence permite que plataformas de e-commerce, aggregadores de pagamentos e parceiros institucionais (como a Rampmoney) criem cobranças fiat em Reais (BRL) via PIX e cartões com liquidação instantânea em USDC na Solana em menos de 10 segundos, com taxa de apenas 1.75%.

Liquidação < 10s

Conversão automática de PIX BRL para USDC nativo na rede Solana através de Circle Wallets programáveis.

Compliance Bacen Estrito

Validação algorítmica de CNPJ e trava de mesma titularidade (estorno automático contra triangulação fraudulenta).

Fee Splitting & Markup

Divisão programável de comissões e margem de tesouraria direto no payload de criação da cobrança.

Ambientes & Base URLs

Produção (Live):https://valence.rendey.store/api/v1

Sandbox (Testes):https://valence.rendey.store/api/v1/charges/sandbox

Segurança & Chaves

Autenticação via Bearer Token

Todas as requisições para a API pública devem conter o cabeçalho Authorization: Bearer <sua_chave_api>. Suas chaves de produção iniciam com o prefixo val_live_ e as de teste com val_sandbox_ (ou val_test_). O gateway detecta automaticamente o ambiente a partir do prefixo da chave.

Armazenamento em Hash SHA-256

A chave em texto puro é exibida UMA única vez durante a geração no Dashboard. A plataforma armazena estritamente o hash criptográfico SHA-256.

Rate Limiting

Limite padrão de 1.000 requisições por minuto por chave e 200 requisições por minuto por IP. O status é informado no header X-RateLimit-Remaining.

Exemplo de Autenticação

curl -X GET https://valence.rendey.store/api/v1/charges?id=chg_98a72b14e   -H "Authorization: Bearer val_live_89a7fbc201489e21789cda01"   -H "Content-Type: application/json"

Charges API

Criar e Consultar Cobranças

Crie ordens de cobrança omnichannel com geração automática de QR Code PIX Copia e Cola nativo, link de checkout hospedado e liquidação on-chain para a carteira do lojista.

POST/api/v1/charges— Criação Omnichannel de Cobrança

Parâmetro	Tipo	Obrigatório	Descrição
amountBRL	number	Sim	Valor em Reais (R$ 1.00 a R$ 50,000.00, máx 2 decimais).
externalReference	string	Opcional	Identificador único do pedido no ERP, Shopify ou WooCommerce.
customerDetails	object	Opcional	Objeto com `name`, `email` e `document` (CPF/CNPJ).
feeSplit	object	Opcional	Divisão de receita/markup para parceiros (ex.: Rampmoney).
expiresInMinutes	number	Opcional (30)	Tempo de validade do QR Code PIX em minutos (5 a 1440).

Criar Cobrança (POST /api/v1/charges)

curl -X POST https://valence.rendey.store/api/v1/charges   -H "Authorization: Bearer val_live_89a7fbc201489e21789cda01"   -H "Content-Type: application/json"   -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"   -d '{
    "amountBRL": 250.00,
    "externalReference": "ORDER-98214",
    "currency": "BRL",
    "expiresInMinutes": 30,
    "customerDetails": {
      "name": "Mariana Souza",
      "email": "mariana@exemplo.com",
      "document": "12345678900"
    },
    "feeSplit": {
      "markupBRL": 5.00,
      "percentage": 2.0,
      "treasuryWallet": "RampTreasuryPubkey1111111111111111111111111111",
      "recipientLabel": "Rampmoney Treasury"
    },
    "metadata": {
      "storeId": "loja-matriz-sp",
      "affiliateId": "aff_partner_491"
    }
  }'

GET/api/v1/charges/:id— Consulta de Status e Hash Solana

Retorna o status consolidado da cobrança. Se um pagamento PIX for efetuado com um CPF divergente do titular cadastrado, o motor de segurança da Valence detecta a divergência e retorna o status REFUNDED_FRAUD acompanhado do protocolo de estorno regulatório Bacen.

PAID

Liquidado com sucesso. Hash Solana e USDC transferidos para o lojista.

PENDING / OPEN

Aguardando leitura do QR Code PIX pelo cliente pagador.

REFUNDED_FRAUD

Estorno automático imediato devido a divergência de titularidade CPF.

Consultar Cobrança (GET /api/v1/charges/:id)

curl -X GET https://valence.rendey.store/api/v1/charges/chg_7d891b2c4e   -H "Authorization: Bearer val_live_89a7fbc201489e21789cda01"

Eventos em Tempo Real

Webhooks e Validação Criptográfica

A Valence dispara notificações HTTP POST assinadas para as URLs configuradas no Dashboard sempre que o status de uma cobrança é alterado.

Evento	Quando é disparado	Ação Recomendada
charge.paid	PIX confirmado e USDC liquidado na carteira Solana.	Liberar pedido / liberar saldo ao cliente.
charge.refunded	Estorno efetuado (manual ou anti-fraude Bacen).	Atualizar status do pedido para Cancelado/Estornado.
charge.expired	Janela de expiração do QR Code PIX atingida sem pagamento.	Fechar checkout ou permitir reabertura de carrinho.

Validação de Assinatura HMAC-SHA256

Todas as requisições contêm o header X-Valence-Signature: sha256=<hex_digest>. O integrador deve calcular o HMAC-SHA256 do corpo bruto (raw body) utilizando o Webhook Secret cadastrado e efetuar comparação em tempo constante.

Validação de Assinatura do Webhook

import crypto from "crypto";

export function verifyValenceWebhook(rawBody: string, signatureHeader: string, secret: string): boolean {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  const receivedSignature = signatureHeader.replace(/^sha256=/, "");

  // Comparação em tempo constante contra timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, "hex"),
    Buffer.from(receivedSignature, "hex")
  );
}

Divisão de Tesouraria

Fee Splitting & Markup para Parceiros (ex.: Rampmoney)

Plataformas parceiras, integradores B2B e aggregadores podem adicionar sua própria margem de lucro (markup fixo ou percentual) diretamente na criação da cobrança. O valor líquido é repassado ao lojista e o markup é direcionado para a carteira de tesouraria do parceiro.

Estrutura do Parâmetro feeSplit

"feeSplit": {
  "markupBRL": 5.00,        // Valor fixo em Reais retido para o parceiro
  "percentage": 2.0,        // Comissão percentual sobre o valor bruto
  "treasuryWallet": "...",  // Carteira Solana de destino do repasse
  "recipientLabel": "Rampmoney Treasury"
}

Exemplo Prático: Em uma cobrança de R$ 250,00 com markup fixo de R$ 5,00 + 2% de split (R$ 5,00):

Total pago pelo cliente: R$ 250,00
Comissão do Parceiro (Rampmoney): R$ 10,00
Líquido creditado ao lojista: R$ 240,00 (em USDC)

Console de Testes

Sandbox Interativo & Teste de Chaves

Experimente os endpoints da Valence diretamente pelo navegador. Edite os parâmetros, configure seu token e observe as respostas em tempo real.

Interactive API PlaygroundDevnet / Sandbox Mode

Valence Sandbox & Teste de Chaves em Tempo Real

Gere requisições simuladas, valide seu Bearer Token e inspecione os payloads de retorno da API.

Modo Demonstração Ativo

1. Selecione a Operação da API

2. Chave de API (Bearer Token)

3. Parâmetros da CobrançaMoeda: BRL

Valor (amountBRL)

Ref. Externa (externalReference)

Nome do Pagador

CPF Pagador (Bacen Titularidade)

Fee Splitting / Divisão de Tesouraria

Markup Fixo (R$)

Comissão Parceiro (%)

Resposta HTTP em Tempo Real

application/json

Nenhuma requisição disparada ainda.

Selecione os parâmetros e clique em "Executar Requisição" para visualizar a resposta.

Integrações & SDKs

Bibliotecas e Plugins Oficiais

Kits prontos para acelerar o desenvolvimento da sua integração em qualquer stack de tecnologia.

@valence/sdk-node

SDK TypeScript / JavaScript com tipagens completas e validação de webhooks.

npm i @valence/sdk

valence-python

Biblioteca Python com clientes assíncronos (asyncio) e síncronos.

pip install valence

WooCommerce & Shopify

Plugins de checkout transparente para e-commerces com split nativo.

Configurar no Dashboard