feat(payment): PI-5431 [SPIKE] [FE] Surcharging (Bluesnap, Adyen) - PoC [do not merge]

[bc-ania]

What/Why?

Adds in-flight card surcharging for AdyenV3 and Bluesnap Direct. Once the shopper fills and validates their card (before Place Order), the strategy asks backend whether a surcharge applies for that card and, if so, applies it as a checkout fee so it can be shown in the order summary.

The FE stays provider-agnostic: it forwards a card handle to the backend, which proxies it to the provider (Adyen /cardDetails, Bluesnap /surcharge/calculate), applies compliance rules, and returns a normalized surcharge value.

Rollout/Rollback

This is just PoC, do not merge

Testing

video_1280.mp4

---

Note

High Risk
Changes checkout totals and payment strategy behavior during card entry; relies on unimplemented BE endpoints and leaves stale surcharge fees when cards change.

Overview
Adds in-flight card surcharging so shoppers can see a surcharge in the order summary before Place Order, wired for Adyen V3 and Bluesnap Direct credit card flows.

Introduces a shared SurchargeActionHandler that POSTs provider-agnostic card handles to /api/storefront/checkouts/{id}/surcharge-check, and when eligible applies a custom_fee via new applyFees on the payment integration service. Core gains FeeActionCreator / FeeRequestSender and checkout state updates on ApplyFeesSucceeded (fees, totals), mirroring store credit / coupons.

Adyen tracks BIN via onBinValue and runs the check when the card component is valid. Bluesnap captures card metadata on onType and triggers the handler when the card number field validates. Handler dedupes by BIN and serializes concurrent checks; failures are logged without blocking checkout.

PoC notes: storefront fees and surcharge-check proxies are not implemented on BE yet; removing or replacing an existing surcharge when the card changes is explicitly TODO (no remove endpoint).

^{Reviewed by Cursor Bugbot for commit c2285b3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Duplicate surcharge detection name mismatch

Medium Severity

_hasSurcharge looks for a fee named corporate_card_surcharge, but applied fees use body.name from the surcharge API. If the backend returns a different name, duplicate surcharges can be applied and duplicate prevention never triggers.

 

^{Reviewed by Cursor Bugbot for commit 30940ab. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

There are 4 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c2285b3. Configure here.}

[cursor]

Dropped checks while surcharge in flight

Medium Severity

When a surcharge check is already running, applyInFlight returns immediately without queueing or retrying. A newer card change during that window is ignored, so the checkout can keep a surcharge from the previous card or never evaluate the latest card.

 

^{Reviewed by Cursor Bugbot for commit c2285b3. Configure here.}

[cursor]

Ineligible card keeps surcharge fee

High Severity

When checkSurcharge reports the current card is not eligible (or amount ≤ 0), applyInFlight returns without clearing an existing surcharge fee on the checkout, so totals can still include a fee for a card that no longer qualifies.

 

^{Reviewed by Cursor Bugbot for commit c2285b3. Configure here.}

[cursor]

Stale Adyen BIN on re-entry

Medium Severity

this._bin is only updated in onBinValue and is not cleared when the card becomes invalid or the PAN changes. A later valid onChange can reuse the previous BIN for deduplication and surcharge payloads before Adyen emits a new BIN.

Additional Locations (1)

• packages/adyen-integration/src/adyenv3/adyenv3-payment-strategy.ts#L482-L485

 

^{Reviewed by Cursor Bugbot for commit c2285b3. Configure here.}