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
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": "<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}
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.

2.3 KiB Raw Blame History Unescape Escape