Zurich.Financeiro

API para processamento de pagamentos com cartão de crédito utilizando Saga Pattern com WorkflowCore.

🏗️ Arquitetura

Este projeto implementa um fluxo de pagamento distribuído com as seguintes características:

• .NET 8 - Framework moderno
• WorkflowCore - Orquestração de saga pattern
• OpenTelemetry - Observabilidade completa (traces, metrics, logs)
• Scrutor - Injeção de dependências por convenção
• FastEndpoints - Endpoints performáticos e tipados
• Serilog - Logging estruturado integrado com OpenTelemetry

🔄 Fluxo de Pagamento (Saga Pattern)

O workflow de pagamento segue estas etapas:

1. AuthorizeCreditCardStep - Autoriza o cartão no gateway
2. WaitFor("payment-confirmed") - ⏸️ PAUSA aguardando webhook
3. CaptureCreditCardStep - Captura o valor após confirmação
4. NotifyCustomerStep - Notifica o cliente

Compensações (Rollback)

Cada etapa possui sua compensação em caso de falha:

• AuthorizeCreditCardCompensationStep
• CaptureCreditCardCompensationStep
• NotifyCustomerCompensationStep

📡 Endpoints

POST /api/payments/credit-card/initiate

Inicia o fluxo de pagamento.

Request:

{
  "cardNumber": "4111111111111111",
  "cardHolderName": "João Silva",
  "expiryDate": "12/25",
  "cvv": "123",
  "amount": 100.50,
  "currency": "BRL",
  "description": "Pagamento teste",
  "customerName": "João Silva",
  "customerEmail": "joao@example.com",
  "customerDocument": "12345678900"
}

Response:

{
  "workflowId": "abc-123-def-456",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Payment authorization initiated. Waiting for webhook confirmation."
}

POST /api/payments/webhook/confirm

Recebe confirmação do gateway e continua o workflow.

Request:

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "eventId": "evt_123456",
  "status": "confirmed",
  "additionalData": null
}

Response:

{
  "success": true,
  "message": "Webhook received successfully. Payment workflow will continue."
}

📊 Observabilidade com OpenTelemetry

O projeto implementa observabilidade completa seguindo o padrão OpenTelemetry:

Traces (Rastreamento Distribuído)

• Activity Source: Zurich.Financeiro
• Instrumentação automática: ASP.NET Core, HttpClient, EF Core, SQL Client
• Spans customizados: Cada step do workflow gera seu próprio span

Metrics (Métricas)

Métricas customizadas de pagamento:

• payment.metrics.initiated - Total de pagamentos iniciados
• payment.metrics.success - Total de pagamentos bem-sucedidos
• payment.metrics.error - Total de pagamentos com erro
• payment.metrics.amount - Histograma de valores processados

Logs (Logs Estruturados)

Logs enriquecidos com contexto OpenTelemetry via Serilog:

• TraceId e SpanId em todos os logs
• Correlação automática com traces
• Exportação via OTLP para o collector

Tags Customizadas

• payment.id, payment.order.reference
• payment.amount, payment.currency
• payment.card.number (mascarado)
• payment.gateway, payment.gateway.transaction.id
• payment.status, payment.workflow.instance.id

Visualização

Configure backends de observabilidade (Jaeger, Grafana, Honeycomb, etc.) apontando para o OpenTelemetry Collector.

📦 Estrutura do Projeto

Zurich.Financeiro/
├── src/
│   └── Zurich.Financeiro/
│       ├── Bootstrap/
│       │   └── ServiceExtensions.cs         # Scrutor + OpenTelemetry config
│       ├── Domain/
│       │   └── Payment/
│       │       ├── Features/
│       │       │   └── CreditCardPaymentFlow/
│       │       │       ├── Steps/            # Workflow steps
│       │       │       ├── CreditCardPaymentWorkflow.cs
│       │       │       ├── CreditCardPaymentData.cs
│       │       │       ├── InitiatePaymentEndpoint.cs
│       │       │       └── WebhookConfirmationEndpoint.cs
│       │       └── Telemetry/
│       │           ├── CreditCardPaymentTelemetry.cs
│       │           └── PaymentOtelMetrics.cs
│       ├── SeedWork/
│       │   └── Telemetry/               # OpenTelemetry infrastructure
│       │       ├── ITelemetryService.cs
│       │       ├── TelemetryService.cs
│       │       ├── TelemetryFactory.cs
│       │       ├── OtelTracingService.cs
│       │       ├── OtelVariables.cs
│       │       └── TelemetrySettings.cs
│       ├── Program.cs
│       ├── appsettings.json
│       └── Zurich.Financeiro.csproj
└── Zurich.Financeiro.sln