# Monetix Gateway – Card Payouts

This service now supports Monetix “payout by card”.

## Runtime entry points
- gRPC: `MntxGatewayService.CreateCardPayout`, `CreateCardTokenPayout`, `GetCardPayoutStatus`, `ListGatewayInstances`.
- Callback HTTP server (default): `:8084/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`
- Optional execution mode: `mcards.strict_operation_mode=true` to process only one unresolved payout operation at a time (strict isolated mode)
- Gateway descriptor: `gateway.id`, optional `gateway.currencies`, `gateway.limits` (for per-payout minimum use `gateway.limits.per_tx_min_amount`)
- Callback server: `MNTX_GATEWAY_HTTP_PORT` (exposed as 8084), `http.callback.path`, optional `allowed_cidrs`

## Outbound request (CreateCardPayout)
Payload is built per Monetix spec:
```
{
  "general":  { "project_id": <int>, "payment_id": "<operation_ref>", "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 }
}
```
Gateway request contract additionally requires `parent_payment_ref` as a first-class field
(separate from Monetix `payment_id`).

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}`
- `sendico_mntx_gateway_rpc_requests_total{method,status}`
- `sendico_mntx_gateway_rpc_latency_seconds{method}`

## 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.
