49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
# 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.
|