Configuration
1. Environment Variables
Source:
EnvironmentKeysin@nx/core/src/common/environments.ts+@nx/mq-pay/src/common/environments.ts.
Core runtime
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
APP_ENV_PORT | number | 3000 | HTTP listen port | |
APP_ENV_HOST | string | 0.0.0.0 | Bind address | |
APP_ENV_BASE_PATH | string | /v1/api/payment | Route prefix | |
APP_ENV_NODE_ID | number | - | ✓ | Snowflake worker ID - 8 (FULL/API) / 91+ (WORKER) |
APP_ENV_LOG_LEVEL | info|debug|warn|error | info | - | |
APP_ENV_NODE_ENV | string | development | dotenv-flow loader | |
RUN_MODE | migrate|startup | startup triggers MQ-Pay component setup; non-startup skips MQ-Pay (e.g., during migrations) |
Mode-based deployment
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
APP_ENV_MQ_PAY_MODE | FULL|API|WORKER | FULL | Controls controller + worker registration. See Architecture §3 |
Database
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
APP_ENV_DB_URL | string | - | ✓ | PostgreSQL connection URL |
APP_ENV_DB_POOL_MAX | number | 10 | - |
Redis (BullMQ + cache)
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
APP_ENV_REDIS_HOST | string | - | ✓ | BullMQ requires Redis (when MQ-Pay is active) |
APP_ENV_REDIS_PORT | number | 6379 | - | |
APP_ENV_REDIS_PASSWORD | string | - | - | |
APP_ENV_REDIS_DB | number | 0 | - | |
APP_ENV_WEBSOCKET_REDIS_MODE | SINGLE|CLUSTER | SINGLE | WS emitter Redis mode |
Encryption
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
APP_ENV_APPLICATION_SECRET | string | - | ✓ | AES-256-GCM key for CryptoUtility; must match across all pods |
Authentication
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
APP_ENV_JWKS_URL | url | - | ✓ | Identity service JWKS endpoint |
2. Feature Flags
| Flag | Storage | Default | Description |
|---|---|---|---|
Provider enable | Configuration.tValue | true | Per-provider enable flag (in encrypted JSON config) |
Provider enableController | Configuration.tValue | true | Whether to register provider's HTTP controllers |
Provider isProduction | Configuration.tValue | false | Toggles VN Pay sandbox vs prod URL |
3. Seeded Data
3 migration processes in
src/migrations/processes/. Run on bootstrap.
| File | Scope | Notes |
|---|---|---|
payment-0001-seed-vnpay-qr-mms-configuration.ts | VNPAY QR MMS provider config | Encrypts { enable, isDefault, enableController, appId: 'MERCHANT', masterMerchantCode: 'A000000775', isProduction: false } and stores in Configuration (code: VNPAY_QR_MMS, group: INTEGRATION, environment: DEVELOPMENT) |
payment-0002-seed-vnpay-phone-pos-configuration.ts | VNPAY PhonePOS provider config | Encrypts { enable, isDefault: false, enableController, isProduction: false } and stores similarly |
payment-0003-seed-permissions.ts | All PaymentPermissions | alwaysRun: true - re-runs on every migration. Aggregates WebhookConfigPermissions (8 CRUD codes) + 5 sets from @nx/mq-pay (Transaction, TransactionItem, PaymentAttempt, PaymentResult, PaymentOperation) |
Per-merchant credentials are NOT seeded - they're created by merchants at onboarding via the Configuration API or admin UI.
4. Configuration Table Usage by Payment
| Configuration kind | Code | Group | Encryption | Source |
|---|---|---|---|---|
| VNPAY QR MMS provider | VNPAY_QR_MMS | INTEGRATION | tValue (AES-256-GCM) | seed payment-0001 |
| VNPAY PhonePOS provider | VNPAY_PHONE_POS | INTEGRATION | tValue (AES-256-GCM) | seed payment-0002 |
| Per-merchant payment credentials | per-merchant code | INTEGRATION, principalType=MERCHANT, principalId=<merchantId> | credential (AES-256-GCM) | runtime via getPaymentCredential |
getPaymentCredential queries the table directly (bypasses CRUD repo) because the credential column is hidden from standard CRUD reads.