SP
Payments Reliability & Card-on-File Enablement
ShurjoPay × BRAC Bank Integration Case Study
Fintech • 2022
● Fintech • Encryption Compatibility • Card-on-File (CoF)

Fixing BRAC Bank Token Encryption in PHP 8 — and Re-enabling Card-on-File

Resolved BRAC Bank transaction failures caused by a PHP 7 bank-provided encryption library running inside a PHP 8 system. Eliminated the PHP 7 subdomain workaround by aligning the salt mechanism, restored correct token generation in PHP 8, and unlocked Card-on-File as a product milestone.

Role Senior Software Engineer
Org ShurjoPay Ltd. (Payment Gateway), Dhaka
Scope Payment token encryption, gateway integration, CoF

A subset of payments (BRAC Bank cards/accounts) failed because the bank’s PHP 7 wire-transfer/token library produced incompatible encryption output when required from PHP 8. The “keep it working” workaround added a PHP 7 REST endpoint on a separate subdomain — which, in turn, blocked ShurjoPay’s Card-on-File flow. I took ownership, identified the salt mismatch, made the encryption deterministic in PHP 8, removed the subdomain dependency, and restored both reliability and product capability.

Problem → Solution → Impact

Problem

  • BRAC Bank encryption library (PHP 7) produced bad tokens in PHP 8.
  • Workaround via PHP 7 subdomain kept payments alive but blocked CoF.
  • Extra surface area increased operational and security risk.

Solution

  • Identified salt and OpenSSL differences between runtimes.
  • Made encryption deterministic in PHP 8; aligned token generation.
  • Removed PHP 7 subdomain dependency; unified the payment flow.

Impact

  • BRAC Bank payments restored under PHP 8.
  • Card-on-File re-enabled as a key product milestone.
  • Simpler architecture with fewer operational failure points.
Payment success
Before: failures on BRAC tokens After: stable under PHP 8
Architecture complexity
Before: dual runtime + subdomain After: single runtime flow
Card-on-File
Before: blocked by workaround After: restored and launchable
Trace mismatch

Compare PHP 7 vs. PHP 8 encryption outputs; isolate salt handling differences.

Fix token generation

Update library usage for PHP 8 to produce identical tokens.

Simplify runtime

Remove the PHP 7 subdomain; keep payments and CoF in one flow.

Impact spotlight
  • Merchants regain confidence in BRAC Bank transactions.
  • Card-on-File becomes launch-ready after long downtime.
  • Ops surface area shrinks, reducing risk and maintenance load.
Overview

What Happened

ShurjoPay’s BRAC Bank integration depended on a bank-provided library (from BRAC Bank’s IT team) that generated an encrypted token required for transaction requests. The library was authored for PHP 7, while ShurjoPay’s main system ran on PHP 8. When we require-ed the library directly in the PHP 8 runtime, the encrypted token was produced incorrectly, and BRAC Bank transactions failed.

A prior team mitigated the incident by creating a small PHP 7 REST endpoint (hosted on a subdomain) that wrapped the bank library and returned the encrypted token to the main app. This restored payment success — but introduced a domain boundary that blocked the Card-on-File (CoF) confirmation workflow. As a result, CoF remained disabled for a long time.

Context

Why This Was High-Stakes

  • Reliability: issuer-specific failures erode trust quickly (users perceive the gateway as unstable).
  • Security & compliance: token/encryption steps must remain correct, deterministic, and auditable.
  • Product growth: Card-on-File is a conversion and convenience driver for repeat payments.
  • Operational burden: a “side-service” adds extra deployment, monitoring, and incident surface area.
In payments, the integration layer is part of the product. If token-generation is brittle, both revenue and reputation suffer.
Challenge

Problem Statement

  • BRAC Bank transaction requests were rejected because tokens were not encrypted appropriately under PHP 8.
  • The workaround PHP 7 token service required a subdomain, which restricted Card-on-File saving after user confirmation.
  • CoF was unavailable for a long time, creating a persistent feature gap and merchant/user friction.
Investigation

Root Cause

After taking charge, I reproduced the token-generation flow in controlled environments and compared outputs across runtimes. The core issue was not only “PHP 7 vs PHP 8” — the failure came from a salt mechanism mismatch that changed the derived/encrypted output when executed in our PHP 8 environment.

  • Validated token parity (same inputs must yield bank-accepted outputs).
  • Isolated where the encrypted output diverged.
  • Confirmed the divergence originated in the salt-handling step affecting the final encrypted token.
Solution

What I Implemented

1) Align the salt mechanism for PHP 8 execution

  • Updated integration logic so salt generation/handling matched the bank library’s expectations.
  • Ensured the encryption output became deterministic and valid when the bank library is used from PHP 8.

2) Remove the PHP 7 subdomain dependency

  • Eliminated the need for the separate PHP 7 REST endpoint that wrapped the bank library.
  • Unified the BRAC token-generation inside the primary app runtime and domain.

3) Restore Card-on-File end-to-end flow

  • Re-enabled card saving on user confirmation (CoF) without cross-domain limitations.
  • Stabilized the confirmation → token persistence pathway as a first-class feature.
This was a “fix the root, not the workaround” change: remove runtime drift and unblock a major product capability.
Reliability

How It Improved Reliability

  • Higher success rate for BRAC Bank flows by generating bank-accepted encrypted tokens under PHP 8.
  • Fewer moving parts by removing a network hop and a separately deployed subdomain service.
  • Lower latency & variance by avoiding extra HTTP calls and reducing external dependency failure modes.
  • Faster debugging with a single runtime path and consistent logs/traceability.
Security

How It Improved Security

  • Reduced attack surface by removing a publicly reachable PHP 7 token sub-service.
  • Improved workflow integrity for Card-on-File by keeping confirmation and token handling within one domain.
  • Lower config/secret sprawl by avoiding duplicated credentials/configs across services.
  • More consistent controls (auth, rate limiting, logging hygiene) by consolidating into the primary platform boundary.

Note: This change focused on correctness and operational security posture. It did not alter the bank’s algorithm choice; it made the integration deterministic and safer to run at scale.

Verification

Validation Approach

  • Parity checks: confirm PHP 8 output matches bank-accepted token generation.
  • Regression testing: BRAC flows succeed without affecting other issuers.
  • CoF scenarios: confirm card save after user consent; confirm repeat payments using stored tokens.
  • Operational monitoring: track issuer-specific errors and ensure sustained stability.
Reflection

Key Takeaways

  • Runtime compatibility problems are often symptoms; the real root can be subtle (salt/derivation differences).
  • Workarounds keep the lights on — but can silently block core product capabilities (like Card-on-File).
  • Consolidating critical payment flows reduces both operational risk and security exposure.