Payvala Security protects the connections, API requests, and information exchanged between Payvala and its partner financial institutions (FIs). It helps ensure that only trusted institutions can connect, make authorized requests, and access the data they are permitted to use.

Security works through multiple layers. Network controls determine which connection path can reach Payvala. Client certificates and access tokens help verify the institution, while request signatures help confirm that API requests are genuine and have not been changed. Payvala also checks permissions and validates requests before processing them.

Security also includes protecting sensitive information, managing certificates and keys safely, keeping each institution's data separate, and preparing for security incidents. Merchant-facing APIs and Soundbox devices use separate security methods from FI API connections.

This overview introduces the security model and summarizes each layer. Each topic is explained in full on one dedicated page. Every requirement is labeled Confirmed, Provisional, Proposed, or Open, and values marked † are provisional. Provisional, proposed, and open items must not be treated as final production commitments.

Payvala protects each financial institution (FI) connection through several checks. First, the FI connects through one approved network path: a private connection or the public path through Cloudflare. The network path controls which traffic can reach Payvala, but it does not verify the caller's identity. Each FI API request must then pass mutual TLS (mTLS), present a short-lived access token linked to the client certificate, and carry a valid request signature made with the method registered for its key. Payvala then checks the request format and the FI's API permissions before processing the request. The health and status endpoints are documented exceptions to the token and signature rules (see Security Rules for Each API). Optional message encryption (JWE) adds protection for the message body. It is off by default for normal FI API traffic and is always used to deliver a new HMAC secret. Merchant-facing APIs and Soundbox devices use separate security methods, and device connections never use the FI paths.

Payvala APIs do different jobs, so each API belongs to exactly one security class. The class sets the request-signing method, validation rules, and access controls that the API must meet, and how its caller must connect. Four classes apply to the current FI and merchant APIs: K, W, R, and M. Additional classes for people, staff, devices, outbound calls, and device commands (H, I, D, O, and C) are proposed for surfaces that are not yet built and await owner confirmation. This page gives a quick overview of the requirements for each class. Detailed procedures for creating, rotating, and revoking keys are covered on the separate Key Management page.

Financial institutions (FIs) can connect to Payvala through the approved public route using Cloudflare. Cloudflare acts as the entry point for incoming traffic and applies configured network protections before requests reach the Payvala FI API. The origin accepts traffic from Cloudflare only, helping prevent requests from reaching the service through an unapproved public route. This section explains how traffic reaches Payvala; certificate verification, access tokens, request signing, and API permissions are explained in their dedicated security sections.

All Financial Institution (FI) API connections must use TLS 1.3, and older TLS versions are not accepted. Mutual TLS (mTLS) requires both sides to prove their identity using certificates. Each FI generates its private key and certificate request inside its own hardware security module (HSM), and the private key never leaves the HSM. Software-only private-key storage is not permitted in production. Connections with missing, invalid, or unregistered certificates are refused before any data is read. Because mTLS does not support session resumption, FI clients should keep connections open using HTTP keep-alive and use a small connection pool rather than opening a new connection for every request.

Authentication checks which FI is making the request. Authorization checks what that FI is allowed to do. Payvala uses the client certificate and a token linked to that certificate to identify the FI, then checks the token and key permissions on every call. FI API access is system-to-system, so it does not use a browser sign-in or a client secret. Access is granted per key and per API; the detailed token scopes are listed on the Short-Lived Access Tokens section.

An access token is a short-lived credential that allows an FI to call approved APIs. Each token is linked to the client certificate used to request it and lasts 900 seconds (15 minutes). There is no refresh token. When a token expires, the FI requests a new one. The FI should cache the current token and reuse it until it expires instead of requesting a token for each call. Token permissions limit which APIs it can reach. On every call Payvala checks the token's signature, issuer, audience, expiry, scope, and certificate binding, and confirms that the certificate is still registered to an active institution. If the certificate is revoked or the FI is suspended, its tokens stop working at once, without waiting for expiry.

Each API key is registered to one request-signing method: HMAC or JWS. HMAC uses a shared secret, which must never be sent with a request. JWS uses a private key held by the FI to create a signed proof for each request, and Payvala checks that proof against the registered public key. Payvala checks the signature to help confirm that the request came from the expected key and was not changed. A key's method is fixed, so a key cannot switch methods, and a request signed with the wrong method is rejected with 400 invalid_signature. API 2 accepts JWS only. The older X-Api-Key header is no longer used. A third profile, RFC 9421 HTTP Message Signatures (http-sig), is planned with a target date of 30 June 2027. That date can move by mutual agreement, and it is not a commitment.

Keys and credentials must be managed safely from creation to retirement. A new key waits for an activation delay before it becomes usable. The delay is provisionally 30 minutes (allowed range 15 to 60), and the key can be cancelled during that time. During planned rotation, the new key is added before the old one is retired, with a 24-hour overlap, so integrations can switch without an avoidable outage. HMAC secrets rotate every 90 days, with 14 days' notice. If the master key is lost or suspected to be compromised, a controlled out-of-band recovery applies. It involves two FI officers, two Payvala approvers, registered contacts, and a cooling-off period. Retired and expired keys cannot be reactivated.

JSON Web Key Sets (JWKS) publish the public keys used for encryption and signature verification between Payvala and FIs. Payvala publishes its public encryption keys at /.well-known/jwks.json. Signing keys (master, approver, and request-proof keys) use ES256 with an EC P-256 key (preferred) or PS256 with an RSA key of 2048 bits or more. Encryption keys are RSA keys of 2048 bits or more. Private keys are generated by their owner and never leave the owner's hardware security module. Each new public key is confirmed by a fingerprint call-back (RFC 7638 thumbprint) and checked for uniqueness across all FIs and both environments before it is registered.

FIs obtain Payvala's public encryption keys with a GET request to /.well-known/jwks.json. An FI may register the address of its own key set, but only for its encryption key. Never for its master, approver, or request-proof keys, and never for certificates. That address must be HTTPS on a domain the FI registered at onboarding. Payvala caches the last good set and keeps it if a fetch fails. It uses a new key only 24 hours after the key first appears (Proposed), alerts the FI's security contacts on every change, and runs the uniqueness check on each new key. Key identifiers allow the correct key to be selected during planned rotation. Exact endpoint details are documented in Developer → API.

TLS protects data while it travels between systems. Request signatures add a separate check that a request is genuine and has not been changed. Optional JWE encryption adds protection to the message body itself. It is off by default, except when used to deliver a new HMAC secret. Encryption does not prove who sent a message; certificates, tokens, and signatures do that. Requests must follow the published size and format rules. FIs must not send account numbers, BVN, NIN, phone numbers, or card numbers in requests. The rules for handling personal data are covered in Protecting Personal and Sensitive Data.

JWE (JSON Web Encryption) is an optional way to encrypt the message body inside the TLS connection. It is off by default for normal API traffic and is always used when Payvala delivers a new HMAC secret. An FI whose policy does not allow a processor to see transaction data in clear, typically on the public path, can switch it on for API 3, API 5, and API 6. Those APIs carry amounts, payer references, device serial numbers, and device location. JWE encrypts the body but does not authenticate the sender; the certificate, token, and signature do that. When it is enabled, both sides decrypt every body, and the edge can check sizes but not content.

When response encryption is enabled for an FI, the response body is returned as a compact JWE with Content-Type application/jose, encrypted to the FI's registered encryption key. Every authenticated response carries Cache-Control: no-store and X-Content-Type-Options: nosniff, whether or not its body is encrypted. Exact response structure is documented in Developer → API.

FI integrations exchange only what each operation needs, typically a transaction reference, amount, device serial number, and txnId. The payerRef field is personal data and is treated as a direct or pseudonymous identifier. Payvala stores the value as sent, encrypts it at field level at rest, masks it in logs to its last four characters, never places it in an error response, and shows it only to the merchant of that device. It is kept no longer than the transaction record. Credentials, access tokens, secrets, and private keys must never appear in application logs, source repositories, or unsecured configuration.

Merchant-facing APIs (1 and 4) and the planned administrator portal run in a browser, so the browser must be told how to protect the user. FI APIs are machine-to-machine and are not meant to be called from browsers. Their hosts send no cross-origin (CORS) headers and refuse cross-origin preflight requests, which is itself a control.

Each FI can access only its own permitted data. Payvala identifies the institution from its client certificate, not from a value supplied in the request. Important key-management and request-check outcomes are recorded for later review. Detailed platform-wide log collection and threat detection are covered in a separate plan and are not specified in this section.

Keeping the integration secure is a shared responsibility. Payvala manages the platform-side controls, while each FI manages its own systems, network settings, keys, certificates, and monitoring. Each side must complete the security steps it controls.