# Core Banking Integration

Configuration for integrating Monetarie PIX with the Monetarie Core Banking platform via NATS JetStream and shared JWT authentication.

## Prerequisites

- Monetarie Core Banking deployed and accessible
- NATS JetStream cluster shared between Core and PIX
- Shared JWT secret configured in both systems
- Familiarity with [NATS JetStream](./nats.md) configuration

## Architecture

```mermaid
graph LR
    CORE[Core Banking] -->|NATS: monetarie.core.pix.*| PIX[Monetarie PIX]
    PIX -->|NATS: monetarie.spi.*| CORE
    PIX -->|NATS: monetarie.dict.*| CORE
    CORE -->|JWT iss:monetarie| PIX
```

## Authentication

### Shared JWT Secret

The JWT secret fallback chain ensures cross-service authentication:

```
JWT_SECRET  -->  GUARDIAN_SECRET_KEY  -->  SECRET_KEY_BASE
```

Core Banking Guardian tokens (HS256, `iss: "monetarie"`) are accepted by PIX without requiring the `target_system` field. SSO tokens (`iss: "monetarie-sso"`) still require `target_system: "pix"`.

### Kubernetes Secret

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: monetarie-shared-jwt-secret
  namespace: pix
type: Opaque
stringData:
  jwt-secret: "same-value-as-core-GUARDIAN_SECRET_KEY"
```

### Local Development

```bash
# Set PIX JWT_SECRET to Core's dev secret
export JWT_SECRET="dev-only-secret-key-not-for-production"
```

## NATS Event Contract

### Core -> PIX Events

| Subject | Event Field | Handler | Description |
|---------|------------|---------|-------------|
| `monetarie.core.pix.payment_request` | `payment_request` | `handle_payment_request/1` | Create outbound pacs.008 |
| `monetarie.core.pix.return_request` | `return_request` | `handle_return_request/1` | Create pacs.004 return |
| `monetarie.core.pix.key_create` | `key_create` | `handle_key_create/1` | Create PIX key via DICT |
| `monetarie.core.pix.key_delete` | `key_delete` | `handle_key_delete/1` | Delete PIX key via DICT |
| `monetarie.core.pix.dict_lookup` | `dict_lookup` | `handle_dict_lookup/1` | DICT key lookup, reply via NATS |
| `monetarie.core.pix.balance_inquiry` | `balance_inquiry` | `handle_balance_inquiry/1` | SPI balance query, reply via NATS |

::: warning EVENT FIELD ROUTING
The `"event"` field in NATS payloads is the routing key for CoreEventProcessor. Missing or misspelled event values result in silent acknowledgment with no processing.
:::

### PIX -> Core Events

Events published on `monetarie.spi.transaction.*` and `monetarie.dict.keys.*` include Core-compatible fields:

```json
{
  "type": "transaction.settled",
  "source": "pix",
  "published_at": "2026-02-09T14:30:00Z",
  "data": { ... }
}
```

### Request/Reply (Outside JetStream)

| Subject | Direction | Purpose |
|---------|-----------|---------|
| `dict.lookup.request` | Core <-> PIX | DICT key lookup (req/reply) |
| `dict.api.request` | Core <-> PIX | Claims/MED/infractions (req/reply) |

These subjects are intentionally outside JetStream stream scope to avoid message interception.

## CoreEventProcessor

The `CoreEventProcessor` worker consumes from the `MONETARIE_CORE` JetStream stream:

- **Batch size**: 50
- **Max concurrency**: 5
- **HTTP retry**: 3 attempts with exponential backoff (1s, 2s, 4s)
- **Finch timeout**: 10 seconds on all HTTP requests to DICT service
- **Trace propagation**: `x-trace-id` header forwarded to internal HTTP calls

## Dependencies on Core Team

1. Publish events to `monetarie.core.pix.*` subjects (not `ledger.transaction.pix*`)
2. Create K8s secret `monetarie-shared-jwt-secret` in `pix` namespace with matching value
3. Validate Core's PixHandler works with PIX event payload format (`type`, `source`, `published_at`)

## Expected Outcome

After configuring Core Banking integration:

- CoreEventProcessor consuming events from `MONETARIE_CORE` stream
- JWT tokens from Core accepted by PIX auth pipeline
- PIX events publishing with Core-compatible payload format
- Request/reply working for DICT lookups and balance inquiries