Overview#
The Utility Payment Gateway module enables customers to make bill payments directly through the platform, including during voice AI-assisted service calls, without being redirected to a separate payment portal. The gateway abstracts over multiple payment processors, supporting Stripe for card-based payments and JMMB (Jamaica Money Market Broker) for regional payment processing, with a mock gateway available for safe development and testing. Payments are validated, processed with idempotency guarantees, and recorded in the utility payment audit table, giving finance teams a complete reconciliation record alongside the service call history.
Key Features#
- Multi-Gateway Abstraction: A common payment interface sits in front of Stripe, JMMB, and a mock processor, allowing the organisation to switch or add payment providers through configuration without changing application code
- Stripe Card Processing: Creates payment intents via the official Stripe API with full metadata attachment (account number, tenant ID, transaction reference), supporting the full range of card types and currencies accepted by Stripe
- JMMB Regional Payments: Integrates with the JMMB payment gateway for Jamaican and Caribbean market deployments, using HMAC-SHA256 request signing and sandbox URL for pre-production testing
- Payment Idempotency: Every payment request carries a unique idempotency key combining the account number, amount, currency, and timestamp, preventing duplicate charges if a payment is submitted more than once due to network retries
- Amount and Currency Validation: Payments are validated before submission: the amount must be greater than zero and no greater than $100,000, and the currency must be on the configured allowlist, preventing invalid or accidental large charges
- Live Mode Gating: Real charges against Stripe or JMMB require explicit environment-level opt-in; all payment requests in environments without this flag enabled are processed by the mock gateway regardless of configuration, preventing accidental live charges in development or staging
- Exponential Backoff Retry: Transient network errors and gateway timeouts are retried up to three times with increasing delays, improving payment success rates without duplicating charges
- Payment Audit Record: Every successful payment is recorded in the utility payments table with the transaction identifier, receipt number, gateway used, amount, currency, account reference, and tenant scope, supporting billing reconciliation and customer dispute resolution
Use Cases#
In-Call Bill Payment#
During an AI-assisted utility service call, a customer asks to pay their outstanding balance. The AI collects confirmation, and the payment gateway processes the charge against the customer's account on file. The customer receives a verbal receipt reference without being transferred to another system or putting the call on hold.
Outstanding Balance Clearance#
An accounts management team member processes a payment on behalf of a customer whose account is at risk of service disconnection. The gateway records the payment with the staff member's session context, providing an auditable record of the manual payment event.
Regional Payment Processing#
A utility operating in the Caribbean configures JMMB as its payment gateway. Customers making payments through the service portal use the JMMB flow with HMAC-signed requests, while the application layer remains identical to a Stripe-configured deployment.
Development and Testing#
A development team tests the full payment workflow, including voice AI payment tools, account lookup, and receipt generation, using the mock gateway, which processes all requests as successful without making any real charges and without requiring live API credentials.
How It Works#
Integration#
The Utility Payment Gateway is invoked as a callable tool within the Voice AI session and is also available as a direct API operation from the Utility Customer Management module. Gateway selection is controlled by the PAYMENT_GATEWAY environment variable set at the organisation level. Payment records are linked to the utility account by account_id and to the organisation by tenant_id, ensuring all reconciliation queries are properly scoped. The receipt number returned by the gateway is surfaced in the AI transcript and recorded on the account's payment history for customer-facing display.
Open Standards#
- HMAC-SHA256 (FIPS 198-1 / RFC 2104): Gateway requests to JMMB are authenticated using an HMAC-SHA256 signature computed over the JSON payload and a per-request timestamp, ensuring message integrity and authenticity.
- ISO 4217: All payment amounts are validated against a named allowlist of three-letter ISO 4217 currency codes (USD, JMD, EUR, GBP, CAD, TTD, BBD, XCD), preventing submission of unrecognised or unsupported currencies.
- ISO 8601: Request timestamps sent to the JMMB gateway and all audit record timestamps are formatted as ISO 8601 UTC datetime strings, ensuring unambiguous, interoperable time representation.
- RFC 4122 (UUID): Every payment request carries a v4 UUID as its idempotency key and each audit record is assigned a UUID primary key, preventing duplicate charges on network retry and providing globally unique record identifiers.
- TLS 1.2/1.3 (RFC 8446): All outbound connections to the Stripe API and JMMB sandbox endpoint are made over HTTPS, ensuring payment credentials and transaction data are encrypted in transit.
- JSON (RFC 8259): JMMB charge requests and Stripe PaymentIntent metadata are serialised as JSON, and gateway responses are parsed from JSON, providing a standard, language-neutral data interchange format.
- GraphQL (June 2018 Specification): The payment mutation is exposed to the platform through a GraphQL schema layer, allowing callers to request precisely the payment result fields they require within a single API operation.
Availability#
Stripe and JMMB gateways are available on deployments with the Utility Customer Management module enabled. Gateway credentials and live mode activation are configured through the deployment environment and administration console.
Last Reviewed: 2026-04-14 Last Updated: 2026-04-14