03 Processor Integration Lld

Processor Integration — Low Level Design

A payment gateway must integrate with multiple card processors (Visa/Mastercard networks via different acquirers, PayPal, Braintree, etc.) and adapt to different API formats. Three patterns work together: Strategy for swapping processor implementations, Adapter for wrapping legacy or incompatible processor APIs, and Facade for presenting a single simple interface to the transaction engine.

Problem Statement

Design the processor integration layer for a payment gateway. This layer must:

Route each transaction to the correct card processor (Visa network for Visa cards, Mastercard for Mastercard cards, PayPal for PayPal payments, ACH processor for bank transfers)
Adapt legacy or third-party processor APIs that are incompatible with the gateway’s internal interface — without modifying the gateway’s core logic
Expose a single, simple entry point to the transaction engine that hides all subsystem complexity (MLE decryption, fraud evaluation, duplicate checking, processor routing, event publishing)

The key design challenges:

Routing variety: different card types route to different processors. Adding a new acquirer partnership must not require changes to the transaction engine.
Legacy incompatibility: some processors have 10-year-old APIs with different method names, parameter types, and response formats. The transaction engine must never know about these differences.
Orchestration complexity: a single processPayment() call requires 9 coordinated steps across 7 subsystems. This complexity must be hidden from the API controller.

Clarifying Questions — Interview

1. Functional Scope

Q: How many processors must be supported? Can a single merchant use multiple processors for different card types?

A: 4-6 processors initially (VisaNet, Mastercard, Amex, PayPal, ACH, Legacy Bank). Yes — a merchant can be configured with VisaNet for Visa cards and a regional acquirer for Mastercard. The ProcessorRouter reads the merchant’s processor configuration per card type.

2. Scale & Performance Budget

Q: How many concurrent processor calls can the system handle? What is the timeout for a processor call?

A: Each processor has its own bulkhead thread pool (200 threads for VisaNet, 200 for Mastercard — sized for async I/O or ~200 concurrent blocking calls at 15s average timeout). Processor timeout is 15–30 seconds — this is the realistic range used by production payment gateways. Visa/Mastercard authorization typically responds in 1–3 seconds at the network level; a 30-second timeout catches legitimate slow responses without holding threads indefinitely. The gateway-to-merchant timeout is set slightly higher (e.g., 35 seconds) so the gateway always resolves the processor call before the merchant’s HTTP connection times out — preventing the merchant from giving up and retrying while the original processor call is still in flight.

3. Consistency & Correctness Invariants

Q: What happens if the processor call succeeds but the response is lost in transit?

A: The PENDING record written before the call identifies this gap. Recovery process queries the processor using the processorTransactionId to determine if the authorization succeeded. This is why the Facade must ensure write-before-call happens before any processor call.

4. Extensibility & Rate of Change

Q: How difficult is it to add a new processor (e.g., a new regional acquirer)?

A: With Strategy Pattern: implement PaymentProcessor interface (4 methods), register in ProcessorRouter. Zero changes to TransactionEngine, FraudEngine, or PaymentGatewayFacade. A new processor is a new file + a configuration change.

5. Concurrency & Thread Safety

Q: Is the ProcessorRouter and PaymentGatewayFacade shared across threads?

A: Both are stateless singletons — safely shared. The LegacyBankGatewayAdapter stores currentReferenceNumber as instance state, which IS a thread-safety issue — it should be request-scoped (see Disadvantages).

6. Failure & Recovery

Q: What happens when a processor is down? Does it affect all transactions or only that processor’s?

A: Circuit breaker per processor (stored in Redis). When VisaNet’s circuit opens, only VisaNet transactions fail fast. Mastercard, PayPal, and ACH are unaffected (bulkhead isolation). The Facade catches ProcessorUnavailableException and returns an error response — PENDING record already written, so no silent money loss.

7. Observability & Debuggability

Q: A merchant reports their transaction was declined by the processor with an opaque error code. How do we investigate?

A: The processorTransactionId and raw declineCode from the processor are stored on the transaction record. The TransactionInvoker audit log shows which ProcessorStrategy handled the request, the raw response, and timing. Cross-reference with the processor’s own logs using processorTransactionId.

8. Persistence & Durability

Q: If the PaymentGatewayFacade.processPayment() crashes halfway through, what’s the recovery path?

A: The PENDING write (step 4 in the Facade) ensures a recovery record exists before any external call. If the crash happens after the processor call but before updateResponse(), the PENDING record exists and ops can reconcile it against the processor. The Facade’s 9-step sequence is designed so every failure after step 4 is recoverable.

9. Fallback Processor

Q: If the primary processor for a card type is down (circuit open), is there a fallback?

A: Yes — ProcessorRouter supports a fallback routing rule per card type. If VisaNet’s circuit is open, route to the secondary acquirer configured for that merchant. The fallback adds ~50ms overhead (different network path, possibly different fee schedule). Fallback is merchant-configurable: some merchants accept a secondary acquirer with different settlement terms; others prefer to decline during primary outage rather than settle to an unexpected acquirer. The circuit breaker state is checked before routing: CLOSED → primary; OPEN → fallback (if configured) → decline (if no fallback).

10. Decline Code Normalization

Q: Each processor has different decline code schemes. How does the facade expose a consistent code to the merchant?

A: Each processor adapter translates its native codes to a NormalizedDeclineCode enum: INSUFFICIENT_FUNDS, CARD_EXPIRED, CVV_MISMATCH, DO_NOT_HONOR, LOST_STOLEN, INVALID_CARD, GENERIC_DECLINE. The translation lives inside the Strategy implementation — VisaNetProcessor.authorize() maps Visa’s “51” to INSUFFICIENT_FUNDS, Mastercard’s “N7” to CVV_MISMATCH. The PaymentGatewayFacade returns the normalized code to the merchant. The raw processor code is also stored on the transaction record for debugging and processor-specific analysis.

11. Partial Authorization

Q: Some issuers return partial approvals (e.g., authorize $80 on a$ 100 request for a prepaid card). How is this handled?

A: AuthorizationResponse includes an approvedAmount field alongside the requested amount. If approvedAmount < requestedAmount, the facade can: (a) accept the partial authorization and capture approvedAmount — common for prepaid/gift cards where the merchant ships what the card can cover; (b) void the partial authorization and decline — the merchant’s configured preference. The Transaction.amount is set to approvedAmount on the AUTHORIZED state transition, not the original requested amount. Partial authorizations are most common with debit cards, prepaid cards, and restaurant pre-authorizations.

12. Network-Mandated Retry Rules

Q: Are there card network rules about when and how often declined transactions can be retried?

A: Yes — Visa and Mastercard publish strict retry rules that carry financial penalties for violations: (1) Hard declines (stolen card, account closed, invalid card number) — must NOT be retried. Retrying these risks EXCESSIVE_RETRY fees ( $0.10–$ 0.25 per violation, thousands of them per day at scale). (2) Soft declines (insufficient funds “51”) — may retry, minimum 1 day between attempts. (3) “Do Not Honor” (05) — minimum 30 days before retry. The ProcessorRouter stores the last decline code per stored credential and enforces minimum retry intervals before allowing a retry. Violations of network retry rules can result in increased per-transaction fees and eventually losing processing rights.

13. PCI DSS Scope in Processor Integration

Q: Does the processor integration layer fall within PCI DSS scope? What must it never do?

A: Yes — any component that transmits cardholder data is in PCI scope (PCI DSS Requirement 4: encrypt transmission). The processor adapter transmits the PAN to the card network, so it is in scope. Requirements: (1) All transmission uses TLS 1.2+ with certificate validation. (2) The AuthorizationRequest passed to processor.authorize() must contain the PAN only transiently — it must not be logged, cached, or stored. (3) The processorTransactionId returned in AuthorizationResponse is safe to log; it’s the processor’s own reference, not cardholder data. (4) With network tokenization (Visa VTS / Mastercard MDES), the actual PAN is replaced with a network token before it reaches the processor adapter — this reduces PCI scope for the adapter significantly.

Section 1: Strategy Pattern — Processor Routing

plantuml

1
public interface PaymentProcessor {
2
    AuthorizationResponse authorize(AuthorizationRequest request);
3
    CaptureResponse capture(CaptureRequest request);
4
    VoidResponse void_(VoidRequest request);
5
    RefundResponse refund(RefundRequest request);
6
    ProcessorType getProcessorType();
7
}

1
public class AuthorizationRequest {
2
    private final String transactionId;
3
    private final BigDecimal amount;
4
    private final String currency;
5
    private final PaymentMethod paymentMethod;
6
    private final BillingAddress billingAddress;
7
    private final String merchantId;
8
    private final String customerIp;
9
    // constructor + getters
10
}

1
public class AuthorizationResponse {
2
    private final boolean approved;
3
    private final String authCode;
4
    private final String processorTransactionId;
5
    private final String declineCode;
6
    private final String avsResult;
7
    private final String cvvResult;
8
    // constructor + getters
9
}


6 collapsed lines
1
public class VisaNetProcessor implements PaymentProcessor {
2
    private final VisaNetClient visaNetClient;
3
    private final MessageFormatter formatter;
4

5
    public VisaNetProcessor(VisaNetClient visaNetClient, MessageFormatter formatter) {
6
        this.visaNetClient = visaNetClient;
7
        this.formatter = formatter;
8
    }
9

10
    @Override
11
    public AuthorizationResponse authorize(AuthorizationRequest request) {
12
        // Build ISO 8583 message for Visa network
13
        Iso8583Message message = formatter.buildAuthorizationMessage(request);
14
        Iso8583Response response = visaNetClient.send(message);
15
        return formatter.parseAuthorizationResponse(response);
16
    }
17

18
    @Override
19
    public CaptureResponse capture(CaptureRequest request) {
20
        Iso8583Message message = formatter.buildCaptureMessage(request);
21
        Iso8583Response response = visaNetClient.send(message);
22
        return formatter.parseCaptureResponse(response);
23
    }
24

25
    @Override
26
    public ProcessorType getProcessorType() { return ProcessorType.VISA_NET; }
27

28
    // void_ and refund implementations omitted for brevity
29
}

1
public class ProcessorRouter {
2
    private final Map<ProcessorType, PaymentProcessor> processors;
3
    private final BinLookupService binLookupService;
4

5
    public ProcessorRouter(Map<ProcessorType, PaymentProcessor> processors,
6
                            BinLookupService binLookupService) {
7
        this.processors = processors;
8
        this.binLookupService = binLookupService;
9
    }
10

11
    public PaymentProcessor route(Transaction transaction) {
12
        ProcessorType type = determineProcessorType(transaction);
13
        PaymentProcessor processor = processors.get(type);
14
        if (processor == null) {
15
            throw new UnsupportedProcessorException("No processor registered for " + type);
16
        }
17
        return processor;
18
    }
19

20
    private ProcessorType determineProcessorType(Transaction transaction) {
21
        String bin = transaction.getPaymentMethod().getCardNumber().substring(0, 8);
22
        CardNetwork network = binLookupService.lookupNetwork(bin);
23

24
        return switch (network) {
25
            case VISA -> ProcessorType.VISA_NET;
26
            case MASTERCARD -> ProcessorType.MASTERCARD;
27
            case AMEX -> ProcessorType.AMEX;
28
            case PAYPAL -> ProcessorType.PAYPAL;
29
            default -> throw new UnsupportedCardNetworkException(network.name());
30
        };
31
    }
32
}

Isolated test surface: each processor can be unit tested with a mock without touching others
Zero-downtime processor swap: route 0% to old processor, 100% to new without code changes
Independent deployment: VisaNetProcessor changes deploy without touching MastercardProcessor

Response code normalization: each processor has unique decline codes; the router must normalize them into a common DeclineCode enum — ongoing maintenance as processors change their codes
Configuration complexity: routing rules must cover all card BIN ranges, edge cases, and fallbacks

Why Strategy Pattern and Not Alternatives

Alternative	Why it fails for processor routing
`if-else` by card type in `TransactionEngine`	Transaction engine knows about every processor. Adding a new processor means modifying the engine. Testing the engine requires mocking all processors.
Abstract base class per processor	Inheritance creates hidden dependencies. `VisaNetProcessor` and `MastercardProcessor` share no actual implementation — there’s nothing to inherit. Prefer composition.
Service locator / registry lookup	Works but is implicit — the routing logic is hidden in a registry lookup instead of in explicit, readable routing code. Harder to trace and test.
Strategy ✓	`ProcessorRouter` selects the correct `PaymentProcessor` at runtime. Transaction engine calls `processor.authorize(request)` — completely decoupled from which network handles it. New processor = new class + routing rule.

Section 2: Adapter Pattern — Legacy Processor Integration

Problem: the gateway uses PaymentProcessor interface everywhere. But LegacyBankGateway has a completely different API — different method names, different request format, different response format:

1
public class LegacyBankGateway {
2
    private long lastReferenceNumber;
3

4
    public void submitTransaction(double totalAmount, String currencyCode, String cardData) {
5
        System.out.println("LegacyGateway: submitting " + currencyCode + " " + totalAmount);
6
        this.lastReferenceNumber = System.currentTimeMillis(); // simulated reference
7
    }
8

9
    public boolean verifyTransactionStatus(long referenceNumber) {
10
        System.out.println("LegacyGateway: checking status for ref " + referenceNumber);
11
        return true; // simulated approval
12
    }
13

14
    public long getLastReferenceNumber() {
15
        return lastReferenceNumber;
16
    }
17

18
    public void reverseTransaction(long referenceNumber) {
19
        System.out.println("LegacyGateway: reversing ref " + referenceNumber);
20
    }
21
}

plantuml

1
public class LegacyBankGatewayAdapter implements PaymentProcessor {
2
    private final LegacyBankGateway legacyGateway;  // holds instance of adaptee
3
    private long currentReferenceNumber;
4

5
    public LegacyBankGatewayAdapter(LegacyBankGateway legacyGateway) {
6
        this.legacyGateway = legacyGateway;
7
    }
8

9
    @Override
10
    public AuthorizationResponse authorize(AuthorizationRequest request) {
11
        // Translate: BigDecimal → double, PaymentMethod → cardData string
12
        String cardData = formatCardData(request.getPaymentMethod());
13
        double amount = request.getAmount().doubleValue();
14

15
        legacyGateway.submitTransaction(amount, request.getCurrency(), cardData);
16
        currentReferenceNumber = legacyGateway.getLastReferenceNumber();
17

18
        boolean approved = legacyGateway.verifyTransactionStatus(currentReferenceNumber);
19

20
        return AuthorizationResponse.builder()
21
                .approved(approved)
22
                .processorTransactionId("LEGACY_" + currentReferenceNumber)
23
                .authCode(approved ? String.valueOf(currentReferenceNumber) : null)
24
                .declineCode(approved ? null : "LEGACY_DECLINED")
25
                .build();
26
    }
27

28
    @Override
29
    public VoidResponse void_(VoidRequest request) {
30
        long ref = Long.parseLong(request.getProcessorTransactionId().replace("LEGACY_", ""));
31
        legacyGateway.reverseTransaction(ref);
32
        return new VoidResponse(true, "LEGACY_" + ref + "_REVERSED");
33
    }
34

35
    @Override
36
    public CaptureResponse capture(CaptureRequest request) {
37
        // Legacy gateway uses auto-capture — capture is a no-op
38
        return new CaptureResponse(true, request.getTransactionId(), request.getAmount());
39
    }
40

41
    @Override
42
    public RefundResponse refund(RefundRequest request) {
43
        long ref = Long.parseLong(request.getProcessorTransactionId().replace("LEGACY_", ""));
44
        legacyGateway.reverseTransaction(ref);
45
        return new RefundResponse(true, "LEGACY_REFUND_" + ref);
46
    }
47

48
    @Override
49
    public ProcessorType getProcessorType() { return ProcessorType.LEGACY_BANK; }
50

51
    private String formatCardData(PaymentMethod pm) {
52
        return pm.getCardNumber() + "|" + pm.getExpiryMonth() + "/" + pm.getExpiryYear();
53
    }
54
}

Usage — the transaction engine never knows it’s talking to a legacy gateway:

1
// No changes to TransactionEngine — it uses PaymentProcessor interface
2
PaymentProcessor legacyProcessor = new LegacyBankGatewayAdapter(new LegacyBankGateway());
3
processorRouter.register(ProcessorType.LEGACY_BANK, legacyProcessor);
4

5
// ProcessorRouter selects it when a merchant is configured to use LEGACY_BANK

Zero changes to existing code: TransactionEngine and ProcessorRouter are unchanged
Incremental migration: run legacy and new processors in parallel; migrate merchants one at a time
Clean isolation: all the ugly translation code is in one class — easy to find and update

State leakage risk: currentReferenceNumber is instance state — adapter must be request-scoped or thread-safe
Partial translation: if the legacy API doesn’t support partial refunds, the adapter must simulate it or throw UnsupportedOperationException

Why Adapter Pattern and Not Alternatives

Alternative	Why it fails for legacy processor integration
Modify `LegacyBankGateway` directly	Cannot — it’s a third-party library or a system owned by another team. Modifying it creates a maintenance fork.
Add `if (isLegacy)` branches in `ProcessorRouter`	Router becomes coupled to legacy API specifics. Every legacy quirk pollutes the core routing logic.
Rewrite the legacy processor from scratch	Too expensive. The adapter wraps the existing battle-tested implementation.
Adapter ✓	`LegacyBankGatewayAdapter` is the only place that knows about `LegacyBankGateway`. All translation in one class. `ProcessorRouter` uses it via `PaymentProcessor` interface — zero knowledge of legacy internals.

Section 3: Facade Pattern — Payment Processing API

Without a Facade, the API controller would need to:

Decrypt the MLE-encrypted card data → calls MleDecryptionService
Look up merchant config → calls MerchantConfigService
Write PENDING transaction → calls TransactionRepository
Check for duplicates → calls DuplicateDetectionService
Run fraud evaluation → calls FraudPipeline
Route to processor → calls ProcessorRouter
Call the processor → calls PaymentProcessor
Update transaction with result → calls TransactionRepository
Publish events → calls FraudEventPublisher

This couples the controller to 7+ subsystems.

plantuml

1
public class PaymentGatewayFacade {
2
    private final MleDecryptionService mleDecryptionService;
3
    private final MerchantConfigService merchantConfigService;
4
    private final DuplicateDetectionService duplicateDetector;
5
    private final FraudPipeline fraudPipeline;
6
    private final ProcessorRouter processorRouter;
7
    private final TransactionRepository transactionRepository;  // write-before-call
8
    private final FraudEventPublisher eventPublisher;
9

10
    // Constructor injection (Spring @Autowired or manual)
11
    public PaymentGatewayFacade(MleDecryptionService mle, MerchantConfigService config,
12
                                  DuplicateDetectionService dedup, FraudPipeline fraud,
13
                                  ProcessorRouter router, TransactionRepository repo,
14
                                  FraudEventPublisher publisher) {
15
        this.mleDecryptionService = mle;
16
        this.merchantConfigService = config;
17
        this.duplicateDetector = dedup;
18
        this.fraudPipeline = fraud;
19
        this.processorRouter = router;
20
        this.transactionRepository = repo;
21
        this.eventPublisher = publisher;
22
    }
23

24
    public PaymentResult processPayment(PaymentRequest request) {
25
        // Step 1: Decrypt MLE-encrypted card data
26
        PaymentMethod decryptedMethod = mleDecryptionService.decrypt(request.getEncryptedPayload());
27

28
        // Step 2: Load merchant config (from cache)
29
        MerchantConfig config = merchantConfigService.load(request.getMerchantId());
30

31
        // Step 3: Idempotency / duplicate check
32
        Optional<Transaction> existing = duplicateDetector.findDuplicate(request);
33
        if (existing.isPresent()) {
34
            return PaymentResult.fromExisting(existing.get());
35
        }
36

37
        // Step 4: Write PENDING record (write-before-call)
38
        Transaction transaction = transactionRepository.insertPending(request, config);
39

40
        // Step 5: Fraud evaluation
41
        FraudContext fraudContext = new FraudContext(transaction, config, request.getCustomerIp());
42
        FilterResult fraudResult = fraudPipeline.evaluate(fraudContext);
43

44
        if (fraudResult.getAction() == FraudAction.DECLINE) {
45
            transactionRepository.updateDeclined(transaction.getId(), fraudResult.getReason());
46
            return PaymentResult.declined(transaction.getId(), fraudResult.getReason());
47
        }
48

49
        // Step 6: Route to processor and authorize
50
        PaymentProcessor processor = processorRouter.route(transaction);
51
        AuthorizationRequest authRequest = buildAuthRequest(transaction, decryptedMethod);
52
        AuthorizationResponse authResponse = processor.authorize(authRequest);
53

54
        // Step 7: Update transaction record with result
55
        transactionRepository.updateResponse(transaction.getId(), authResponse);
56

57
        // Step 8: Publish fraud event if held
58
        if (fraudResult.getAction() == FraudAction.AUTH_AND_HOLD) {
59
            eventPublisher.publish(new FraudEvent(FraudEventType.TRANSACTION_HELD,
60
                    transaction.getId(), request.getMerchantId(), fraudResult.getTriggeredBy(),
61
                    FraudAction.AUTH_AND_HOLD, Instant.now()));
62
        }
63

64
        return PaymentResult.from(transaction, authResponse);
65
    }
66
}


4 collapsed lines
1
@RestController
2
public class PaymentApiController {
3
    private final PaymentGatewayFacade gateway;
4

5
    public PaymentApiController(PaymentGatewayFacade gateway) {
6
        this.gateway = gateway;
7
    }
8

9
    @PostMapping("/v1/transactions")
10
    public ResponseEntity<PaymentResult> createTransaction(@RequestBody PaymentRequest request) {
11
        PaymentResult result = gateway.processPayment(request);
12
        int status = result.isApproved() ? 201 : 402;
13
        return ResponseEntity.status(status).body(result);
14
    }
15
}

Simple controller: the API controller has ONE dependency and ONE method call — easy to read, test, and maintain
Centralized orchestration: the 9-step sequence is in one place — when a step changes, one file changes
Testable facade: the facade can be tested by mocking its 7 dependencies independently

God object risk: the facade can grow to handle every edge case — resist adding business logic into it; it should only orchestrate
Hidden complexity: subsystems CAN still be used directly; the facade doesn’t prevent bypassing it

Why Facade Pattern and Not Alternatives

Alternative	Why it fails for payment orchestration
Put all 9 steps in the API controller	Controller handles HTTP AND payment logic. 500-line controller. Cannot reuse the logic in the recurring billing engine or test it without HTTP context.
Service mesh / orchestration engine	Overkill for a deterministic 9-step sequence. Adds infrastructure dependency. The sequence never changes at runtime.
Direct coupling between each service	`FraudEngine` calls `ProcessorRouter` which calls `TransactionRepository`. Circular dependencies, impossible to test in isolation.
Facade ✓	Single `PaymentGatewayFacade.processPayment()`. Controller has ONE dependency. Recurring billing engine calls the same facade. Unit test the facade by mocking 7 dependencies. Subsystems stay decoupled from each other.

Final wiring example showing how all three patterns compose:

1
// Application startup wiring
2
LegacyBankGateway legacyGateway = new LegacyBankGateway();
3
LegacyBankGatewayAdapter legacyAdapter = new LegacyBankGatewayAdapter(legacyGateway); // Adapter
4

5
Map<ProcessorType, PaymentProcessor> processors = Map.of(           // Strategy
6
    ProcessorType.VISA_NET, new VisaNetProcessor(visaNetClient, formatter),
7
    ProcessorType.MASTERCARD, new MastercardProcessor(mcClient, formatter),
8
    ProcessorType.LEGACY_BANK, legacyAdapter                        // Adapter plugs into Strategy
9
);
10
ProcessorRouter router = new ProcessorRouter(processors, binLookupService);
11

12
PaymentGatewayFacade facade = new PaymentGatewayFacade(             // Facade
13
    mleService, merchantConfigService, duplicateDetector,
14
    fraudPipeline, router, transactionRepository, eventPublisher
15
);

← Payment Gateway LLD