Skip to content

A self-hosted UPI & COD payment gateway with zero per-transaction platform fees, universal JavaScript checkout integration, dynamic QR payments, WhatsApp OTP authentication, and automated payment verification.

JavaScript
8.2 KB
Raw Blame

Configuration & Secret Management Guide

1. Environment Parameters Reference

Variable Default Value Description
NODE_ENV development Runtime environment (development or production)
CONTROL_CENTER_PORT 8090 Host port for the Local Process Supervisor
PAYMENT_API_PORT 6100 Host port for the central Payment Core REST API
CHECKOUT_PORTAL_PORT 7000 Host port for the customer-facing Checkout page
MERCHANT_ADMIN_PORT 6001 Host port for the Merchant Admin Dashboard
HELP_PORTAL_PORT 3000 Host port for the Customer Payment Help Portal
GMAIL_OBSERVER_PORT 6003 Host port for the Gmail Polling Service & OAuth Callback
SMS_OBSERVER_PORT 6002 Host port for the Google Messages / SMS Web Automator
DATABASE_URL postgresql://... PostgreSQL connection URL
USE_SQLITE_FALLBACK true When true, uses embedded SQLite if PostgreSQL is unreachable
SQLITE_DB_PATH ./data/youpi_pg.sqlite Path to local SQLite database file
ENCRYPTION_MASTER_KEY 64-hex chars 256-bit key for encrypting OAuth credentials and device keys
JWT_SECRET 32+ chars Secret key for customer and admin session tokens
PAYMENT_ACTIVE_WINDOW_MS 300000 Duration of active payment slot (5 minutes = 300,000ms)
PAYMENT_PROCESSING_WINDOW_MS 30000 Duration of verification slot (30 seconds = 30,000ms)
LATE_OBSERVATION_WINDOW_MS 1800000 Safety window for matching late observations (30 minutes)
ANDROID_ENROLLMENT_SECRET auto-generated Secret used to authorize device QR pairing. If unset, a random value is created in data/.secrets/android_enrollment_secret
ADMIN_API_TOKEN auto-generated Bearer token required by /api/v1/admin/* (the Merchant Admin page asks for it once per tab). If unset, a random value is created in data/.secrets/admin_api_token
OBSERVER_API_TOKEN auto-generated Bearer token the local Gmail/SMS observers use to submit observations (data/.secrets/observer_api_token)
COIN_STORE_WEBHOOK_SECRET auto-generated Webhook secret seeded for the default merchant and used by the demo coin store (data/.secrets/coin_store_webhook_secret)
YOUPI_EXPOSE_DEV_OTP unset Set to true for local development to get the OTP in the send-otp response. Ignored when NODE_ENV=production
YOUPI_ALLOW_DEV_TOOLS unset Developer test-mode / simulator endpoints (/admin/dev/*, simulate-observation) are refused when NODE_ENV=production unless this is true
GMAIL_REDIRECT_URI derived Gmail OAuth redirect URI. Defaults to <gmail host from your configured domain>/oauth/callback
ANDROID_HEARTBEAT_TIMEOUT_MS 180000 Inactivity window before Android device is marked DISCONNECTED
CHECKOUT_FRAME_ANCESTORS unset (any origin in development, 'self' in production) Merchant origins (comma or space separated, e.g. https://shop.example.com) allowed to embed /checkout/:id. The youpi.js modal is an iframe, so a store on a different origin than the checkout portal must be listed here or the browser blocks the modal. When unset, any site may frame the checkout page in development, while a production deployment (either NODE_ENV=production or YOUPI_MODE=production) fences the page to its own origin. Only bare http(s) origins are accepted — a path, query, embedded credential or wildcard is ignored, so the value cannot widen the CSP or inject another directive
YOUPI_ALLOW_PRIVATE_WEBHOOKS unset Set to true to permit merchant webhook URLs on loopback/private networks. Required for self-hosted LAN targets; blocked by default as an SSRF guard
DEFAULT_APP_NAME YOUPI PG Gateway application name displayed in checkout, merchant admin, and transaction notifications
DEFAULT_PRIMARY_COLOR #2563eb Default primary brand color (hex) across customer checkout pages
DEFAULT_SUPPORT_EMAIL [email protected] Default support email rendered on customer help modal and receipts
DEFAULT_SUPPORT_PHONE 9876543210 Default customer helpline phone number
DEFAULT_LOGO_URL unset (monogram) Default brand logo image URL for customer checkout portal
DEFAULT_TRUST_BADGE_TEXT unset Custom trust badge label (e.g. ${DEFAULT_APP_NAME} Verified Business)
DEFAULT_FOOTER_GUARANTEE unset Custom customer protection guarantee text in checkout footer
DEFAULT_HIDE_POWERED_BY false When true, completely hides gateway branding from checkout page
WHATSAPP_SENDER_NAME unset Custom sender label prepended to WhatsApp login OTP messages
DEFAULT_MERCHANT_NAME YOUPI Demo Store Initial merchant business name seeded on first database boot
DEFAULT_MERCHANT_SLUG demo-store Initial merchant slug seeded on first database boot

1a. returnUrl requirements

POST /api/v1/payments accepts a returnUrl that is echoed back to the customer's browser as a redirect target after the payment completes, so the gateway stores only absolute http: / https: URLs. A relative value, a javascript: URL or any other scheme is rejected with 400.

The official SDK resolves a relative data-success-url (for example /success) against the storefront's own origin before sending it, so relative storefront paths keep working without any change to merchant code. If you call the API directly, send an absolute URL.


1b. Merchant API Authentication (X-Merchant-Key)

Endpoints that expose merchant-private or customer-contact data require the caller to prove which merchant it is. There are three accepted credentials:

Credential Header Grants
Merchant webhook secret X-Merchant-Key: <merchant webhook secret> Full merchant-private view of that merchant's own sessions: metadata, internalStatus, verificationLevel / verificationSources / verificationTag, returnUrl, and customer contact details
Admin bearer token Authorization: Bearer <ADMIN_API_TOKEN> Full access to every merchant's data (operator tooling)
Observer bearer token Authorization: Bearer <OBSERVER_API_TOKEN> Full access to every merchant's data (local observer processes)

Affected routes: GET /api/v1/payments/:id, GET /api/v1/payments/:id/cod, GET /api/v1/orders/:orderId/cod and GET /api/v1/checkout/:id/state.

On POST /api/v1/payments

X-Merchant-Key is optional here, and the request is refused with 401 MISSING_MERCHANT_KEY only when it names a merchant other than the gateway's default one. The public one-script integration (the browser SDK) cannot carry a merchant secret — a secret in browser JavaScript is public — so the default-merchant path has to stay open. Use X-Merchant-Key (or X-Order-Token) whenever a request targets a specific tenant, and reuse an orderId only with the same amount: a mismatch is rejected with 409 ORDER_AMOUNT_MISMATCH.

autoActivate: true is restricted to admin-authenticated requests or to NODE_ENV=test; elsewhere it is refused with 403 AUTOACTIVATE_FORBIDDEN.

Without a credential these routes return a redacted public view — status, amount, currency, method and order id only. Customer name, email and phone number are never disclosed to an anonymous caller that merely holds a payment id.

The official SDK sends X-Merchant-Key automatically when the merchant secret is configured, so existing integrations receive the full view with no code change:

const client = new YoupiPaymentClient({
  apiUrl: 'https://pay-api.example.com',
  merchantId: '00000000-0000-0000-0000-000000000001',
  webhookSecret: 'your-merchant-webhook-secret'   // enables the merchant-scoped view
});

A customer browsing the checkout page sees their own profile because the checkout client sends the customer session token (x-customer-token), not because the payment id is enough to unlock it.


2. Cryptographic Secret Generation

Generate strong 256-bit encryption and HMAC keys using Node.js native crypto:

# Generate 256-bit Master Key (64 hex characters)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Never commit production .env files to source code repositories.