Abraham GuerraSoftware Architect / Tech Lead

Payment Extension Architecture for Adobe Commerce

A reusable payment extension for Adobe Commerce, built to be distributed across merchants.

Status
Advanced implementation, certification and marketplace-readiness phase.
Stack
PHP 8.4 · Magento 2.4.8 / Adobe Commerce · MySQL · 3-D Secure · Tokenization

Client and partner names are withheld. Implementation detail is limited to what can be shared publicly; more is available during an interview.

At a glance

01Problem
Adobe Commerce merchants need one payment extension that coordinates fraud screening, 3-D Secure authentication, authorization and post-payment operations, packaged as a reusable extension rather than custom code for a single store.
02My responsibility
Contributed architectural decisions and implemented safeguards across the payment lifecycle, from sequencing and token validation to idempotency, concurrency and SDK compatibility, and contributed to the design of the certification and evidence process.
03Architectural challenge
A payment can be repeated in many ways: browser retries, duplicate submissions, concurrent requests. None of them may turn into a second call to the processor or a second financial operation.
04Key decision
Persistent payment-attempt state with forward-only transitions and concurrency control, so a payment token can progress through exactly one attempt.
05Outcome
Advanced implementation, certification and marketplace-readiness phase.

Architecture

Keeping one payment from becoming two

  1. 01CheckoutStorefront collects a tokenized card
  2. 02Payment extensionOrchestrates the lifecycle
  3. 03Fraud screeningDecision before authentication
  4. 043-D SecureCardholder authentication, with a challenge when required
  5. 05AuthorizationFunds reserved
  6. 06Post-paymentCapture, refund, incremental authorization
Persistent attempt stateGuards the progression of each payment token. It can only move forward.
Conceptual payment lifecycle, simplified. Highlighted steps involve the payment processor.

Key decision

Persistent payment-attempt state

Each payment token is tied to a persistent attempt whose state can only move forward. Once an attempt reaches a terminal outcome it cannot be processed again, and advancing it is a concurrency-controlled transition, so two processes cannot independently move the same token forward. Tested with concurrent processes competing for the same token: only one advanced. Contributed to the design of this safeguard and implemented it.

Guarantee 1 · Forward only

  1. Attempt created
  2. Processing stages advance
  3. Terminal outcome

Replaying a terminal attempt is refused.

The attempt is persistent and only moves forward. Once it reaches a terminal outcome, the same token cannot be processed again.

Guarantee 2 · One winner

Same token

  • Request A advances
  • Request B refused
  • Request C refused
When concurrent requests try to advance the same token, exactly one can advance it.

Supporting decisions

Other decisions

  1. Explicit lifecycle sequencing

    Fraud screening, 3-D Secure and authorization run in a fixed order: the fraud decision first, then cardholder authentication, then payment.

  2. Duplicate capture and refund protection

    Post-payment operations are guarded so a repeated request cannot produce a second capture or refund.

  3. Configurable isolation of capabilities

    Fraud screening and 3-D Secure are each controlled by their own configuration, so one capability's settings do not alter the other's flow.

  4. SDK compatibility containment

    Warnings and deprecations from the vendor SDK on PHP 8.4 are contained so they cannot leak into security-sensitive responses, without modifying how the SDK itself behaves.

For technical readers

Technical detail

Context

A payment extension for Magento 2.4.8 / Adobe Commerce, built to be distributed across merchants rather than written for a single store. It coordinates fraud screening, 3-D Secure authentication, authorization and capture, tokenized card data and post-payment operations, and has to keep that lifecycle consistent when requests are retried, repeated or run concurrently.

Scale

  • Designed for multi-merchant deployment as a distributable Adobe Commerce extension.
  • Multiple card brands and several authentication, fraud and payment flows.

Responsibility

  • Contributed decisions and implemented corrections for the sequencing of fraud screening, 3-D Secure and payment.
  • Implemented safeguards for payment-attempt replay prevention, idempotency, concurrency and duplicate capture/refund protection.
  • Worked on short-lived token validation, card-type resolution, incremental authorization and 3-D Secure challenge stability.
  • Worked on configuration isolation between payment capabilities and on PHP 8.4 compatibility of the vendor SDK.
  • Contributed to the design of the certification and technical evidence process.

Complexity

  • Sequencing fraud screening, 3-D Secure authentication and payment as one explicit lifecycle.
  • Validation of short-lived tokens issued to the browser, and card-type resolution.
  • Post-payment operations, including capture, refund and incremental authorization.
  • Idempotency and concurrency guarantees around payment attempts.
  • Running a vendor PHP SDK on PHP 8.4 without altering its behavior.

Architecture

  • An explicit order of steps: fraud screening, then 3-D Secure, then authorization.
  • Payment capabilities isolated by configuration.
  • Persistent, forward-only attempt state guarding the progression of each payment token.

Evidence

Extensive automated test suites, including concurrency tests. Not public.