# Monetix Gateway – Card Payouts

This service now supports Monetix “payout by card”.

## Runtime entry points
- gRPC: `MntxGatewayService.CreateCardPayout` and `GetCardPayoutStatus`.
- Callback HTTP server (default): `:8080/monetix/callback` for Monetix payout status notifications.
- Metrics: Prometheus on `:9404/metrics`.

## Required config/env
`api/gateway/mntx/config.yml` shows defaults. Key values (usually injected via env):
- `MONETIX_BASE_URL` – e.g. `https://gate.monetix.com`
- `MONETIX_PROJECT_ID` – integer project ID
- `MONETIX_SECRET_KEY` – signature secret
- Optional: `allowed_currencies`, `require_customer_address`, `request_timeout_seconds`
- Callback server: `MNTX_GATEWAY_HTTP_PORT` (exposed as 8080), `http.callback.path`, optional `allowed_cidrs`

## Outbound request (CreateCardPayout)
Payload is built per Monetix spec:
```
{
  "general":  { "project_id": <int>, "payment_id": "<payout_id>", "signature": "<hmac>" },
  "customer": { id, first_name, last_name, middle_name?, ip_address, zip?, country?, state?, city?, address? },
  "payment":  { amount: <minor_units>, currency: "<ISO-4217>" },
  "card":     { pan, year?, month?, card_holder }
}
```
Signature: HMAC-SHA256 over the JSON body (without `signature`), using `MONETIX_SECRET_KEY`.

## Callback handling
- Endpoint only accepts POST with Monetix JSON body. Signature is verified with the same HMAC-SHA256 algorithm; invalid signatures return 403.
- Maps Monetix statuses:
  - `payment.status=success` AND `operation.status=success` AND `operation.code` empty/`0` → `PAYOUT_STATUS_PROCESSED`
  - `processing` → `PAYOUT_STATUS_PENDING`
  - otherwise → `PAYOUT_STATUS_FAILED`
- Emits `CardPayoutStatusChangedEvent` over messaging (event type: `mntx_gateway`, action: `updated`).

## Metrics
- `sendico_mntx_gateway_card_payout_requests_total{outcome}`
- `sendico_mntx_gateway_card_payout_request_latency_seconds{outcome}`
- `sendico_mntx_gateway_card_payout_callbacks_total{status}`
- Existing RPC/payout counters remain for compatibility.

## Notes / PCI
- PAN is only logged in masked form; do not persist raw PAN.
- Callback allows CIDR allow-listing; leave empty to accept all while testing.