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
Sandbox & MOCK
Teste sem credenciais reais — simula 300ms, força erro com 99.99
Rate Limiting v0.6
Planejado — Bucket4j + Redis
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.

Integre Stripe, Mercado Pago e PayPal com um único endpoint. Roteamento, idempotência e fallback já inclusos.

Começar em 3 minutos Ver API Reference
curl -X POST localhost:8080/v1/payments · x-api-key: orquestraio-livre-123
Integra com
Stripe
MercadoPago
PayPal
MOCK
Redis
Resilience4j
Spring Boot

Escolha um gateway ou deixe o SmartRouter decidir — teste com MOCK sem credenciais reais

Plataforma

Tudo que você precisa para pagamentos

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

1 integração em vez de 3
1 formato de webhook
Fallback automático
Teste local com MOCK
Open source · MIT License
Processamento de Pagamentos
Uma única chamada para PIX, boleto e cartão em múltiplos gateways. Roteamento automático e fallback embutidos — sem configuração extra.
POST /v1/payments Smart Router APPROVED 201 Created pix boleto card_token
SmartRouter
O gateway certo é escolhido automaticamente. BRL + PIX → MercadoPago. USD + cartão → Stripe. Sem if/else no seu código.
Smart Router Stripe Mercado Pago PayPal
Idempotência
Evite pagamentos duplicados. Chave UUID v4 + Redis TTL 24h garantem que a mesma requisição nunca seja processada duas vezes.
idempotencyKey: order-abc idempotencyKey: order-abc duplicate
Circuit Breaker
Falhas de um gateway não derrubam sua integração. Resilience4j faz o fallback automático: CLOSED → OPEN → HALF_OPEN por gateway.
CLOSED OPEN HALF OPEN falhas > 50% em 10 req → OPEN
Webhooks Normalizados
Implemente uma vez, receba de qualquer gateway. Stripe, MercadoPago ou PayPal chegam no mesmo formato. Assinados com HMAC-SHA256 por tenant.
Orquestraio event emitter event: "payment.approved" status: "APPROVED" provider: "MERCADO_PAGO" X-Signature: sha256=... seu server
Segurança
Credenciais e chaves nunca expostas em texto puro. AES-256-GCM, SHA-256 e HMAC desde o primeiro deploy.
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
Melhor para cartão internacional
pix—
boleto—
card_token✓
moedasBRL/USD/EUR
MERCADO PAGO
Ideal para BRL · Melhor para PIX
pix✓
boleto✓
card_token✓
moedasBRL
PAYPAL Beta
Melhor para USD/EUR
pix—
boleto—
card_tokenBeta
moedasUSD/EUR
MOCK dev
Teste sem credenciais reais
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.

A chave bruta não fica exposta
API keys armazenadas apenas como hash SHA-256. Mesmo com acesso ao banco, o valor real da chave não é recuperável. Revogação instantânea sem downtime.
Credenciais não ficam em texto puro
Chaves de gateway criptografadas com AES-256-GCM em repouso. A chave mestre é injetada via variável de ambiente — nunca persistida no banco.
Assinatura evita webhook falsificado
Cada notificação é assinada com HMAC-SHA256 exclusivo por tenant. Verificação em tempo constante — sem risco de timing attack ou spoofing.

Pronto para começar?

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

Começar em 3 minutos Ver API Reference GitHub

MIT License · v0.4.0-alpha · @vitinh0z