Skip to main content

Optional Payload Encryption (Application-Level)

Overview​

All API communication with the eTranzact Switching Platform is conducted over HTTPS (TLS 1.2 or higher), which already provides strong encryption, integrity, and confidentiality at the transport layer.

However, your institutions may require additional application-level encryption` of request and response payloads to satisfy internal security policies, regulatory controls, or data protection standards.

To support this requirement, the platform provides an optional AES-256 payload encryption mechanism. This mechanism is not mandatory but may be enabled by bilateral agreement between the Switching Platform and the participating bank.

When enabled:

  • Request bodies must be encrypted before transmission
  • Response bodies will be encrypted before being returned
  • Encryption applies only to the HTTP body, not headers

Encrypted Request Flow​

Step 1 — Construct the plain request object​

Example:

{
  "requestId": "REQ-20260123-000003",
  "stan": "000301",
  "processingCode": "310000",
  "tranSubType": "INTRA",
  "tranDateTime": "2026-01-23T11:00:00",
  "valueDate": "2026-01-23",
  "tranAmt": "243021.00",
  "currency": "NGN",
  "countryCode": "NG",
  "sourceInstitution": "044",
  "channel": "Mobile",
  "debitAccount": {
    "accountNumber": "0000918480",
    "accountName": "Source Account name"
  },
  "creditAccount": {
    "accountNumber": "0000507082",
    "accountName": "TSS/Payable"
  },
  "directDebit": {
    "MandateCode": "15UYHF0f",
    "MerchantId": "TESTPY4UBANG"
  },
  "narration": "Outreach Support",
  "feeAmount": "0.00",
  "terminalLocation": "Ojodu Berger"
}

Step 2 — Serialize request body​

Convert the JSON object to a UTF-8 encoded string:

plainText = JSON.stringify(requestObject)

Step 3 — Encrypt using AES-256​

encryptedBytes = AES256_Encrypt(plainText, secretKey, IV)

encryptedBase64 = Base64Encode(encryptedBytes)

Step 4 — Construct encrypted payload wrapper​

The HTTP request body must be:

{
  "data": "Base64EncodedEncryptedPayload"
}

Step 5 — Send request normally over HTTPS​

All standard headers remain unchanged:

  • Authorization (Bearer token)
  • X-Signature
  • X-Timestamp
  • X-Nonce
  • Content-Type: application/json
  • Accept: application/json

Decryption Process (Receiving Institution / Switch)​

Step 1 — Extract encrypted payload​

encryptedPayload = request.body.data

Step 2 — Base64 decode​

encryptedBytes = Base64Decode(encryptedPayload)

Step 3 — Decrypt using AES-256​

plainText = AES256_Decrypt(encryptedBytes, secretKey, IV)

Step 4 — Parse JSON​

requestObject = JSON.parse(plainText)

Step 5 — Continue normal processing​

Proceed with:

  • Signature verification
  • Authentication
  • Business validation
  • Transaction processing