The Payvala platform is organized into distinct layers that work together to handle external integrations, security, business operations and downstream communication.

External requests enter through Cloudflare and the API Gateway, followed by mutual TLS (mTLS), before reaching the Payvala API. The Payvala API applies authentication, authorization and request validation before forwarding requests to the required business service.

The Core Business Services layer provides capabilities such as Transaction, Merchant, Institution and Configuration Services. Based on the operation, Payvala can communicate with downstream components through API responses, Webhooks or MQTT-based Physical and Virtual Soundbox delivery.

Staging and Production environments are maintained separately with their own endpoints, certificates, credentials, keys and network configurations.

The Payvala platform follows a layered architecture that defines how Financial Institutions communicate with Payvala and how requests are securely processed across the platform.

External communication follows a common path: Partner or FI → Cloudflare → API Gateway → mTLS → Payvala API. This provides the controlled entry boundary for all supported Payvala integrations.

After reaching the Payvala API, every request passes through authentication, authorization and request validation before it can access the platform's internal services. This ensures that only authenticated, authorized and valid requests are processed.

The platform then routes the request to the required business capability, such as Transaction, Merchant, Institution or Configuration Services. These services operate behind the common API and security layers, so individual services do not require separate external integration paths.

Depending on the requested operation, Payvala can communicate with downstream components through appropriate mechanisms such as API responses, Webhooks or MQTT-based Physical and Virtual Soundbox delivery.

This architecture creates a clear separation between external systems, security controls, business services and downstream components, while Staging and Production remain independently configured environments.

The Payvala architecture is organized into logical layers so that integration responsibilities, security boundaries and operational ownership remain clear.

The Payvala API layer provides the REST-based interface through which Financial Institutions integrate with the Payvala platform.

The FI-facing APIs are available in separate Staging and Production environments. Each environment uses its own configuration and credentials, and the environments are not interchangeable.

The API layer supports authentication and authorization, partner and credential management, transaction notification and security-related key exchange required for FI integration.

The Event & Messaging Architecture defines how events and messages move between Payvala services and supported downstream consumers.

Business services generate or process events based on the required operation. The platform then applies the required processing and routing before forwarding the message to the configured delivery mechanism.

For Soundbox delivery, the documented architecture uses an MQTT Broker as the messaging boundary between Payvala processing services and Soundbox consumers.

Physical and Virtual Soundbox devices are downstream consumers of the Payvala transaction notification flow.

Physical Soundbox devices use supported IoT mobile connectivity. The specification states that the device supports 2G and 4G data and that the FI must coordinate the required IoT SIM provisioning and testing with the selected mobile operator.

The Virtual Soundbox is an Android-based application and does not require an IoT SIM. Both device types provide the merchant with payment confirmation after MQTT delivery.

FI onboarding starts with organization registration and access configuration in POEMS, followed by FI-side network, mTLS, OAuth, signing/encryption, time synchronization, retry, logging and monitoring configuration.

During a transaction, the FI CBS generates the payment event and the FI integration gateway prepares the secured Payvala request. Payvala validates the request, checks transaction idempotency and processes only accepted notifications for downstream delivery.

A repeated txnId is handled as an idempotent retry and must not cause a second Soundbox broadcast.

Payvala applies defense in depth so that an FI request must pass network, transport, authorization, request-integrity, replay and idempotency controls before transaction processing.

The documented security model follows strong mutual authentication, least privilege, end-to-end non-repudiation, defense in depth and a zero-trust network approach.

Production FI egress IPs are pre-registered and whitelisted. Each FI uses a Payvala-issued client certificate for mutual TLS. OAuth 2.0 follows the documented FAPI 2.0 Advanced profile with mandatory PAR and short-lived sender-constrained mTLS-bound access tokens.

Request security uses JAR for signed request objects and the configured JWS/JWE and HMAC-SHA256 controls. Timestamp and nonce validation provide replay protection, while txnId provides transaction-level idempotency.

The architecture separates FI-owned payer identity information from the transaction reference exchanged with Payvala.

payerRef is an opaque, bank-generated reference token that replaces direct payer Personally Identifiable Information (PII). The FI owns and protects the mapping between payerRef and the underlying payer identity.

Payvala treats payerRef as an opaque identifier and does not perform reverse lookup, enrichment or identity interpretation. Sensitive private keys and shared secrets must remain protected in HSM or hardware-backed secret management and must not be hardcoded, exposed in URLs or written to logs.

Payvala uses synchronous REST API communication for authentication, partner-management operations and FI transaction notification requests that require an API response.

After transaction acceptance, Soundbox notification delivery becomes asynchronous through MQTT. This separates transaction processing from downstream device consumption.

Communication boundaries are protected by the applicable IP, transport, authorization, cryptographic integrity, replay and idempotency controls.

requestId and txnId provide end-to-end correlation for request processing, transaction handling and delivery tracking.

Operational monitoring covers API failures, throttling, security events, credential and certificate status, request tracing, delivery status and transaction anomalies.

Security-relevant activity is audited, including authentication attempts, token issuance, request validation, key usage and rotation, RBAC actions and security events. The specification requires minimum log retention of 12 months.

The FI integration must use controlled retry and exponential backoff for recoverable API failures rather than uncontrolled repeated traffic.

Payvala applies TPS, burst and time-window limits. Consecutive HMAC validation failures can activate the documented security circuit breaker, after which further requests are rejected until manual operational investigation and clearance.

Duplicate txnId submissions are handled idempotently. A duplicate request can return HTTP 200 with an idempotent outcome without causing a second Soundbox broadcast.

The integration specification defines separate Staging and Production environments. They are fully isolated and use environment-specific endpoints, certificates, keys, tokens, credentials and configuration.

Staging credentials must not be used against Production endpoints, and Production credentials must not be used against Staging endpoints. IP allowlisting is configured separately for each environment.

The same security model applies to both environments, while Production adds live operational controls, production allowlisting, production credential lifecycle and go-live governance.

The architecture separates responsibilities between the Financial Institution and Payvala so that ownership of integration components, sensitive information, security controls and notification delivery remains clear.

The FI owns its CBS, outbound integration gateway, payer identity mapping, protected private credentials, NTP synchronization, monitoring, retry/backoff and FI-side logging. Payvala owns POEMS provisioning, platform-side security enforcement, certificate lifecycle, authorization services, request validation, transaction processing, MQTT delivery and platform operational monitoring.

The payerRef mapping remains within the FI environment. Payvala receives only the opaque payerRef and does not perform reverse identity lookup or enrichment.