API
Processar Pagamento
POST /v1/payments — PIX, boleto e cartão em um endpoint
Métodos de Pagamento
pix, boleto e card_token — compatibilidade por gateway
Webhooks
Eventos normalizados com HMAC-SHA256 por tenant
Erros & Status
400, 401, 403, 409, 429 — formato StandardError
Funcionalidades
SmartRouter
Roteamento automático por moeda, método e valor
Idempotência
Redis TTL 24h — nunca processa duas vezes
Circuit Breaker
Resilience4j — CLOSED, OPEN, HALF_OPEN por gateway
Segurança
AES-256-GCM, SHA-256, HMAC — checklist de produção
Mais
Rate Limiting v0.6
Bucket4j + Redis — planejado para a próxima versão
Sandbox & MOCK
Gateway fake — simula 300ms, força erro com amount 99.99
Glossário
Tenant, SmartRouter, Circuit Breaker, MOCK e mais
Desenvolvedores
Documentação
Referência completa da API e guias de integração
Primeiros Passos
Do zero ao primeiro pagamento em 3 minutos com Docker
Autenticação
x-api-key, prefixos Oz_live_ / Oz_test_, revogação
Changelog
Novidades do v0.4.0 — idempotencyKey fix, Webhooks
Recursos
Open Source
Código aberto no GitHub — MIT License
Sandbox & MOCK
Teste sem credenciais reais de gateway
Checklist de Produção
TLS, rotação de chaves, HMAC em webhooks e mais
Changelog
v0.4.0-alpha — Webhooks & idempotencyKey fix
Seção de Webhooks com normalização cross-gateway. Typo crítico corrigido: idempotecyKey → idempotencyKey. Gateway MOCK: cenário de erro via amount 99.99.
v0.3.2 — PayPal Beta & Circuit Breaker
Suporte a PayPal (beta) para USD/EUR ≥ $50. Circuit Breaker configurável por gateway via Resilience4j. AES-256 para credenciais.
v0.4.0-alpha — agora com Webhooks e Circuit Breaker

Múltiplos gateways.
Uma única API.

Processe PIX, boleto e cartão em Stripe, MercadoPago e PayPal com roteamento inteligente, idempotência e resiliência embutidos. Do zero ao primeiro pagamento em 3 minutos.

Primeiros Passos Ver Documentação
curl -X POST localhost:8080/v1/payments · x-api-key: orquestraio-livre-123
Integra com
Stripe
MercadoPago
PayPal
MOCK
Redis
Resilience4j
Spring Boot

Plataforma

Tudo que você precisa para pagamentos

Use um ou todos. Produtos best-of-breed, integrados como plataforma.

Processamento de Pagamentos
Processe PIX, boleto e cartão em múltiplos gateways com uma única chamada. Roteamento automático e fallback embutido sem nenhuma configuração extra.
POST /v1/payments Smart Router APPROVED 201 Created pix boleto card_token
SmartRouter
Roteamento inteligente por moeda, método e valor. BRL + PIX → MercadoPago. USD + card → Stripe.
Smart Router Stripe Mercado Pago PayPal
Idempotência
Chave UUID v4 + Redis TTL 24h. A mesma requisição nunca é processada duas vezes, mesmo com falhas de rede.
idempotencyKey: order-abc idempotencyKey: order-abc duplicate
Circuit Breaker
Resilience4j por gateway. CLOSED → OPEN → HALF_OPEN automático. Fallback para gateway alternativo sem intervenção.
CLOSED OPEN HALF OPEN falhas > 50% em 10 req → OPEN
Webhooks Normalizados
Todos os eventos chegam no mesmo formato, independente do gateway. Stripe, MercadoPago ou PayPal — você implementa uma vez. Assinados com HMAC-SHA256 por tenant.
Orquestraio event emitter event: "payment.approved" status: "APPROVED" provider: "MERCADO_PAGO" X-Signature: sha256=... seu server
Segurança
AES-256-GCM para credenciais, SHA-256 para API keys, HMAC em webhooks e dados de cartão nunca armazenados.
AES-256 · SHA-256 · HMAC
3+
gateways suportados
24h
TTL idempotência
300ms
latência MOCK
<3min
do zero ao primeiro pagamento
Quickstart

Do zero ao primeiro pagamento em 3 passos

Sem configurar credenciais de gateways. Use o gateway MOCK e Docker para começar imediatamente.

1
Suba o servidor com docker-compose up -d. API disponível em localhost:8080.
2
Faça o POST com x-api-key: orquestraio-livre-123 e metadata.gateway: MOCK.
3
Receba status: "APPROVED" e configure seu webhook para atualizações assíncronas.
Ver guia completo →
curl 
curl -X POST http://localhost:8080/v1/payments \
  -H "x-api-key: orquestraio-livre-123" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "order-001",
    "amount": 50.00,
    "currency": "BRL",
    "paymentMethodRequest": {
      "type": "pix",
      "token": null
    },
    "customer": {
      "id": "usr_1",
      "email": "[email protected]",
      "document": "000.000.000-00"
    },
    "metadata": { "gateway": "MOCK" }
  }'

// Resposta 201 Created
{
  "paymentId": "550e8400-e29b-41d4...",
  "status":    "APPROVED",
  "amount":    50.00,
  "details":   { "provider": "MOCK" }
}

Compatibilidade

Métodos por gateway

O SmartRouter seleciona automaticamente. Ou force um gateway via metadata.gateway.

STRIPE
pix—
boleto—
card_token✓
moedasBRL/USD/EUR
MERCADO PAGO
pix✓
boleto✓
card_token✓
moedasBRL
PAYPAL Beta
pix—
boleto—
card_tokenBeta
moedasUSD/EUR
MOCK dev
pix✓
boleto✓
card_token✓
forçar erro99.99

Segurança

Segurança de produção desde o primeiro dia

Não é um addon. Criptografia, autenticação e proteção estão no core do Orquestraio.

API Key via SHA-256
O valor bruto da sua API key nunca é armazenado — apenas o hash SHA-256. Revogação instantânea sem downtime.
AES-256-GCM
Credenciais de gateway criptografadas em repouso. Chave mestre injetada via variável de ambiente — nunca persistida no banco.
HMAC-SHA256 em Webhooks
Cada notificação é assinada com secret exclusivo por tenant. Verificação em tempo constante evita timing attacks.

Pronto para começar?

Configure em minutos com Docker. Nenhuma credencial de gateway necessária para os primeiros testes.

Primeiros Passos Documentação completa GitHub

MIT License · v0.4.0-alpha · @vitinh0z