sendico/api/gateway/mntx

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