Integração ValeRango

Uma API para conectar pagamento, restaurante e saldo de consumo.

O pagamento continua sendo realizado diretamente ao restaurante. A API ValeRango identifica o estabelecimento, consulta a condição comercial cadastrada e automatiza o registro do direito de consumo do cliente.

Testar Sandbox Ler Política da API

Quem pode integrar

Uma estrutura, vários parceiros.

💳

Maquininhas e adquirentes

Enviam confirmação de transação e Merchant ID para automatizar o fluxo.

🍱

Empresas de VR/VA

Podem integrar uma experiência complementar sem transformar o ValeRango em emissor do benefício.

🔗

Integradores

Conectam ERPs, POS, apps e plataformas parceiras à jornada do ValeRango.

Fluxo

Pagamento aprovado → Merchant ID → regra do restaurante → saldo.

Etapa	Responsável	O que acontece
1	Restaurante / parceiro	Pagamento é processado no meio aceito pelo restaurante.
2	Parceiro	Envia transação aprovada, valor, Merchant ID e identificador único.
3	ValeRango	Identifica o restaurante e consulta a condição comercial cadastrada.
4	ValeRango	Vincula a transação ao cliente por token seguro ou fluxo autenticado.
5	ValeRango	Registra o saldo de consumo futuro no restaurante correspondente.

Endpoints

Estrutura proposta da API v1.

Método	Endpoint	Função
POST	`/api/v1/transactions.php`	Registrar transação aprovada
GET	`/api/v1/merchant.php?merchant_id=...`	Consultar restaurante e oferta
POST	`/api/v1/link.php`	Vincular transação ao cliente/token
POST	`/api/v1/refund.php`	Registrar estorno
GET	`/api/v1/status.php?transaction_id=...`	Consultar status da transação

Exemplo de requisição

POST /api/v1/transactions.php Authorization: Bearer SUA_API_KEY Content-Type: application/json { "external_transaction_id": "TX-9283771", "merchant_id": "MID-RESTAURANTE-123", "amount": 100.00, "status": "approved" }

Exemplo de resposta

{ "ok": true, "status": "pending_link", "paid_amount": "100.00", "offer_percent": 20, "credited_amount": "120.00", "qr_token": "TOKEN_DE_USO_UNICO" }

Percentual flexível: 20%, 25%, 30% ou outra condição aprovada pelo restaurante. A regra não fica fixa no código.

Segurança e antifraude

O saldo nasce no servidor, nunca no front-end.

A integração deve comprovar a origem da transação e manter rastreabilidade completa da operação.

🔐

Confirmação servidor a servidor

Em produção, a transação integrada deve chegar por canal autenticado do parceiro, contendo identificador único, Merchant ID, valor e status.

🧮

Saldo calculado pelo ValeRango

O parceiro informa o valor pago. O ValeRango consulta a regra do restaurante e calcula o crédito. O saldo final não é aceito como parâmetro livre do front-end.

🧾

Ledger auditável

Crédito, débito, estorno e ajuste são eventos separados. O saldo não deve ser simplesmente sobrescrito.

⚠️

Limites e anomalias

Operações incompatíveis com o padrão do restaurante podem ser bloqueadas ou revisadas antes de gerar saldo.

🔄

Estorno conciliado

Cancelamentos comunicados pelo parceiro devem gerar reversão correspondente no ValeRango.

👤

Manual x integrado

Lançamentos manuais ficam marcados como informados pelo restaurante; créditos integrados ficam marcados como confirmados pelo parceiro de pagamento.

Produção: credenciais reais, assinatura de webhook, controles de acesso, idempotência, logs e regras antifraude não são expostos na documentação pública.