monetix gateway

api/gateway/mntx/README.md

@@ -0,0 +1,46 @@
+# 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.