Replace Helcim integration with WooCommerce Stripe
This commit is contained in:
twooey committed
1 parent
197938f482
commit
21038d68ca
23 files changed
+172
-1199
No files matched your search
@@ -1,182 +0,0 @@
|
||||
/**
|
||||
* Blocks/Store API payment method for Payments\HelcimGateway (id
|
||||
* bsc_helcim). Registered via wc.wcBlocksRegistry.registerPaymentMethod
|
||||
* since this store only serves Cart/Checkout blocks — see
|
||||
* Payments\HelcimBlocksIntegration's docblock.
|
||||
*
|
||||
* Flow: customer clicks "Enter card details" -> POST /init (server talks
|
||||
* to Helcim, returns checkoutToken+secretToken) -> load HelcimPay.js,
|
||||
* render its iframe -> customer completes card entry -> HelcimPay.js
|
||||
* postMessages the result to window -> POST /confirm (server validates
|
||||
* the hash and stashes the preauth server-side, keyed to this session —
|
||||
* see Payments\CheckoutSession) -> only then does onPaymentSetup allow
|
||||
* WooCommerce to actually submit the order, which is what triggers
|
||||
* HelcimGateway::process_payment() to pick up that stashed preauth.
|
||||
*
|
||||
* Fake mode (no real Helcim token configured yet — see HelcimClient's
|
||||
* docblock): skips loading the real HelcimPay.js iframe entirely in
|
||||
* favor of a "Simulate card entry" button that drives the exact same
|
||||
* /init + /confirm calls, so this whole flow is testable today.
|
||||
*/
|
||||
(function () {
|
||||
var registerPaymentMethod = window.wc.wcBlocksRegistry.registerPaymentMethod;
|
||||
var el = window.wp.element.createElement;
|
||||
var useState = window.wp.element.useState;
|
||||
var useEffect = window.wp.element.useEffect;
|
||||
var settings = window.bscHelcimData || {};
|
||||
var label = settings.title || 'Credit Card';
|
||||
|
||||
function restPost(path, body) {
|
||||
return fetch(settings.restUrl + path, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'X-WP-Nonce': settings.nonce,
|
||||
},
|
||||
body: JSON.stringify(body || {}),
|
||||
credentials: 'same-origin',
|
||||
}).then(function (response) {
|
||||
return response.json().then(function (data) {
|
||||
if (!response.ok) {
|
||||
throw new Error(data.error || 'Payment request failed.');
|
||||
}
|
||||
return data;
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function loadHelcimPayScript() {
|
||||
return new Promise(function (resolve, reject) {
|
||||
if (window.appendHelcimPayIframe) {
|
||||
resolve();
|
||||
return;
|
||||
}
|
||||
var script = document.createElement('script');
|
||||
script.src = 'https://secure.helcim.app/helcim-pay/services/start.js';
|
||||
script.onload = resolve;
|
||||
script.onerror = function () {
|
||||
reject(new Error('Could not load HelcimPay.js.'));
|
||||
};
|
||||
document.body.appendChild(script);
|
||||
});
|
||||
}
|
||||
|
||||
/** Exact event shape per Helcim's own documented example: event.data = {eventName, eventStatus, eventMessage}. */
|
||||
function waitForHelcimResult(checkoutToken) {
|
||||
return new Promise(function (resolve, reject) {
|
||||
var identifierKey = 'helcim-pay-js-' + checkoutToken;
|
||||
function handleMessage(event) {
|
||||
if (!event.data || event.data.eventName !== identifierKey) {
|
||||
return;
|
||||
}
|
||||
if (event.data.eventStatus === 'SUCCESS') {
|
||||
window.removeEventListener('message', handleMessage);
|
||||
resolve(event.data.eventMessage);
|
||||
} else if (event.data.eventStatus === 'ABORTED') {
|
||||
window.removeEventListener('message', handleMessage);
|
||||
reject(new Error('Card entry failed or was cancelled.'));
|
||||
}
|
||||
// 'HIDE' (modal closed without ABORTED/SUCCESS) is ignored here deliberately.
|
||||
}
|
||||
window.addEventListener('message', handleMessage);
|
||||
});
|
||||
}
|
||||
|
||||
function runRealFlow() {
|
||||
var checkoutToken, secretToken;
|
||||
return restPost('/init', {})
|
||||
.then(function (init) {
|
||||
checkoutToken = init.checkoutToken;
|
||||
secretToken = init.secretToken;
|
||||
return loadHelcimPayScript();
|
||||
})
|
||||
.then(function () {
|
||||
window.appendHelcimPayIframe(checkoutToken);
|
||||
return waitForHelcimResult(checkoutToken);
|
||||
})
|
||||
.then(function (eventMessage) {
|
||||
return restPost('/confirm', {
|
||||
rawDataResponse: eventMessage.data || eventMessage,
|
||||
checkoutToken: checkoutToken,
|
||||
secretToken: secretToken,
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function runFakeFlow() {
|
||||
return restPost('/init', {}).then(function () {
|
||||
return restPost('/confirm', {});
|
||||
});
|
||||
}
|
||||
|
||||
function Content(props) {
|
||||
var stateHook = useState('idle'); // idle | working | ready | error
|
||||
var status = stateHook[0];
|
||||
var setStatus = stateHook[1];
|
||||
var errorHook = useState('');
|
||||
var error = errorHook[0];
|
||||
var setError = errorHook[1];
|
||||
|
||||
useEffect(
|
||||
function () {
|
||||
var unsubscribe = props.eventRegistration.onPaymentSetup(function () {
|
||||
if (status !== 'ready') {
|
||||
return {
|
||||
type: props.emitResponse.responseTypes.ERROR,
|
||||
message: 'Please complete card entry before placing your order.',
|
||||
};
|
||||
}
|
||||
return { type: props.emitResponse.responseTypes.SUCCESS };
|
||||
});
|
||||
return unsubscribe;
|
||||
},
|
||||
[status, props.eventRegistration, props.emitResponse]
|
||||
);
|
||||
|
||||
function handleClick() {
|
||||
setStatus('working');
|
||||
setError('');
|
||||
var flow = settings.fakeMode ? runFakeFlow() : runRealFlow();
|
||||
flow
|
||||
.then(function () {
|
||||
setStatus('ready');
|
||||
})
|
||||
.catch(function (e) {
|
||||
setStatus('error');
|
||||
setError(e.message);
|
||||
});
|
||||
}
|
||||
|
||||
return el(
|
||||
'div',
|
||||
{ className: 'bsc-helcim-payment-method' },
|
||||
settings.description ? el('p', {}, settings.description) : null,
|
||||
status === 'ready'
|
||||
? el('p', {}, '✓ Card authorized — ready to place order.')
|
||||
: el(
|
||||
'button',
|
||||
{ type: 'button', onClick: handleClick, disabled: status === 'working' },
|
||||
status === 'working'
|
||||
? 'Verifying card…'
|
||||
: settings.fakeMode
|
||||
? 'Simulate card entry (dev/fake mode)'
|
||||
: 'Enter card details'
|
||||
),
|
||||
error ? el('p', { style: { color: 'red' } }, error) : null
|
||||
);
|
||||
}
|
||||
|
||||
registerPaymentMethod({
|
||||
name: 'bsc_helcim',
|
||||
label: label,
|
||||
content: el(Content),
|
||||
edit: el(Content),
|
||||
canMakePayment: function () {
|
||||
return true;
|
||||
},
|
||||
ariaLabel: label,
|
||||
supports: {
|
||||
features: ['products'],
|
||||
},
|
||||
});
|
||||
})();
|
||||
@@ -4,7 +4,7 @@
|
||||
* Description: Owns catalog, pricing, supplier routing, and order-state business logic for the bookstore. See docs/ for the technical design document.
|
||||
* Version: 0.2.0
|
||||
* Requires PHP: 8.1
|
||||
* Requires Plugins: woocommerce
|
||||
* Requires Plugins: woocommerce, woocommerce-gateway-stripe
|
||||
* Author: Bookstore
|
||||
*/
|
||||
|
||||
@@ -51,7 +51,6 @@ register_activation_hook(__FILE__, function () {
|
||||
|
||||
add_action('plugins_loaded', function () {
|
||||
\Bookstore\Core\Schema::maybe_upgrade();
|
||||
\Bookstore\Core\Payments\HelcimGatewayConfig::ensure_configured_from_env();
|
||||
});
|
||||
|
||||
add_filter('woocommerce_shipping_methods', function (array $methods) {
|
||||
@@ -59,22 +58,6 @@ add_filter('woocommerce_shipping_methods', function (array $methods) {
|
||||
return $methods;
|
||||
});
|
||||
|
||||
// Preauth-then-capture payment flow against HelcimPay.js directly —
|
||||
// design doc Appendix B's revised decision (see includes/Payments/).
|
||||
// Replaces the off-the-shelf helcim-commerce-for-woocommerce plugin's
|
||||
// immediate-charge gateway, not just adds to it — see deploy.sh, which
|
||||
// no longer installs that plugin.
|
||||
add_filter('woocommerce_payment_gateways', function (array $gateways) {
|
||||
$gateways[] = \Bookstore\Core\Payments\HelcimGateway::class;
|
||||
return $gateways;
|
||||
});
|
||||
|
||||
add_action('woocommerce_blocks_payment_method_type_registration', function ($registry) {
|
||||
$registry->register(new \Bookstore\Core\Payments\HelcimBlocksIntegration());
|
||||
});
|
||||
|
||||
\Bookstore\Core\Payments\CheckoutController::register();
|
||||
|
||||
// Membership tiers/benefits: design doc §07 extension (see includes/Membership/).
|
||||
\Bookstore\Core\Membership\MemberDiscount::register();
|
||||
\Bookstore\Core\Membership\Registration::register();
|
||||
|
||||
@@ -198,7 +198,7 @@ class Tier
|
||||
* Seeds guest/free_member with today's real defaults — only if
|
||||
* missing by slug, so a human's later edits via the CLI/settings
|
||||
* screen are never clobbered on a later plugins_loaded (same
|
||||
* never-overwrite convention as Payments\HelcimGatewayConfig).
|
||||
* never-overwrite convention used by other environment-seeded settings).
|
||||
*/
|
||||
public static function seed_defaults(): void
|
||||
{
|
||||
|
||||
@@ -2,10 +2,6 @@
|
||||
|
||||
namespace Bookstore\Core\Order;
|
||||
|
||||
use Bookstore\Core\Payments\CheckoutSession;
|
||||
use Bookstore\Core\Payments\HelcimApiException;
|
||||
use Bookstore\Core\Payments\HelcimClient;
|
||||
use Bookstore\Core\Payments\HelcimGateway;
|
||||
use Bookstore\Core\Pricing\PricingEngine;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
@@ -13,14 +9,9 @@ defined('ABSPATH') || exit;
|
||||
/**
|
||||
* Appendix B (revised for the preauth-then-capture rework): "Supplier
|
||||
* stock, price, and margin are rechecked live, synchronously,
|
||||
* immediately before the customer's card is authorized (held)." The
|
||||
* fraud check moved out of run_checks() and into
|
||||
* Payments\HelcimGateway::process_payment() — it now runs *after* the
|
||||
* preauth exists rather than before, per the new checkout -> preauth ->
|
||||
* fraud review -> supplier order -> capture sequence. This class still
|
||||
* owns price/margin only, and (new) reversing any preauth that's
|
||||
* already been taken if that recheck fails here — see the "wrinkle"
|
||||
* note on validate_order_before_payment() below.
|
||||
* immediately before the customer's card is authorized (held)." Fraud
|
||||
* review runs after Stripe places the order on hold. This class owns the
|
||||
* pre-payment price and margin validation only.
|
||||
*
|
||||
* Two checkout implementations, two different hook sets — confirmed by
|
||||
* reading wp-content/plugins/woocommerce/src/StoreApi/Routes/V1/Checkout.php
|
||||
@@ -144,12 +135,6 @@ class CheckoutRecheck
|
||||
* guards — see that class), which is what the design doc's "duplicate
|
||||
* webhook/job... do not double-order" requirement is actually about.
|
||||
*
|
||||
* New wrinkle from the preauth rework: by the time this hook fires,
|
||||
* the customer has already completed a preauth via the Blocks
|
||||
* checkout JS (Payments\HelcimGateway isn't invoked yet — that only
|
||||
* happens after this hook passes). If the recheck fails here, that
|
||||
* hold is real and live but process_payment() will never run to
|
||||
* clean it up — so run_checks()'s failure path reverses it directly.
|
||||
*/
|
||||
public static function validate_order_before_payment(\WC_Order $order, \WP_Error $validation_errors): void
|
||||
{
|
||||
@@ -174,8 +159,8 @@ class CheckoutRecheck
|
||||
/**
|
||||
* Shared by both checkout implementations. Returns null on success
|
||||
* (audit rows already written) or a customer-facing failure message
|
||||
* (order already routed to the exception status, any preauth already
|
||||
* reversed) on failure. Audit rows are only ever inserted after every
|
||||
* (order already routed to the exception status) on failure. Audit rows
|
||||
* are only ever inserted after every
|
||||
* item has passed — never partially, which matters because a failed
|
||||
* attempt can be resubmitted against the same draft order under
|
||||
* Blocks checkout.
|
||||
@@ -195,14 +180,13 @@ class CheckoutRecheck
|
||||
$quoted_unit = (float) $item->get_total() / $quantity;
|
||||
|
||||
if (!$recheck || $recheck->price > $quoted_unit + self::PRICE_CUSHION) {
|
||||
self::reverse_pending_preauth();
|
||||
self::route_to_exception($order, sprintf(
|
||||
'Supplier/margin recheck failed for "%s" at order-finalize (was quoted $%.2f, fresh price $%.2f).',
|
||||
$item->get_name(),
|
||||
$quoted_unit,
|
||||
$recheck->price ?? 0.0
|
||||
));
|
||||
return 'Sorry, part of your order is no longer available at its listed price. Any card hold has been released — please try again.';
|
||||
return 'Sorry, part of your order is no longer available at its listed price. Please try again.';
|
||||
}
|
||||
|
||||
$offer = $recheck->offer;
|
||||
@@ -232,28 +216,6 @@ class CheckoutRecheck
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fraud check already ran (Payments\HelcimGateway::process_payment(),
|
||||
* after the preauth) by the time price/margin ever gets a chance to
|
||||
* fail here — this only fires when the preauth exists but the recheck
|
||||
* itself fails first. Best-effort: nothing was ever charged either
|
||||
* way, and an unreversed hold just expires on its own within Helcim's
|
||||
* 7-day window if this call fails.
|
||||
*/
|
||||
private static function reverse_pending_preauth(): void
|
||||
{
|
||||
$pending = CheckoutSession::pending_preauth();
|
||||
if (!$pending) {
|
||||
return;
|
||||
}
|
||||
CheckoutSession::clear_pending_preauth();
|
||||
try {
|
||||
HelcimClient::reverse($pending['preauth_transaction_id'], HelcimGateway::client_ip());
|
||||
} catch (HelcimApiException $e) {
|
||||
error_log('bsc_helcim: reverse failed after a failed price/margin recheck: ' . $e->getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
private static function route_to_exception(\WC_Order $order, string $reason): void
|
||||
{
|
||||
$order->update_status(OrderStatuses::EXCEPTION, $reason);
|
||||
|
||||
@@ -3,9 +3,7 @@
|
||||
namespace Bookstore\Core\Order;
|
||||
|
||||
use Bookstore\Core\Catalog\SupplierOffer;
|
||||
use Bookstore\Core\Payments\HelcimApiException;
|
||||
use Bookstore\Core\Payments\HelcimClient;
|
||||
use Bookstore\Core\Payments\HelcimGateway;
|
||||
use Bookstore\Core\Payments\FraudCheck;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
@@ -20,24 +18,42 @@ defined('ABSPATH') || exit;
|
||||
* safely via queue; do not double-order" idempotency requirement actually
|
||||
* lives, ahead of Week 4 needing it for real.
|
||||
*
|
||||
* Preauth-then-capture rework: this class now runs BEFORE the card is
|
||||
* actually charged, not after. It triggers on the order reaching
|
||||
* Order\OrderStatuses::AUTHORIZED (preauth held, fraud check already
|
||||
* passed — Payments\HelcimGateway) rather than woocommerce_payment_complete.
|
||||
* A successful supplier submission captures the held funds for the first
|
||||
* time (payment_complete() only fires here now, at capture); a failed one
|
||||
* reverses the hold instead of refunding a charge that was never made —
|
||||
* the whole point of this rework, replacing Appendix B's accepted
|
||||
* "refund, lose the processing fee" risk with a genuinely zero-cost void.
|
||||
* The official WooCommerce Stripe gateway creates an On hold order when
|
||||
* manual capture is enabled. We fraud-check that authorized order, move it
|
||||
* into the bookstore's Authorized state, and submit it to the supplier.
|
||||
* Moving a successful order to Processing asks the Stripe plugin to capture
|
||||
* the authorization; cancelling a failed one asks Stripe to release it.
|
||||
*/
|
||||
class SupplierOrderJob
|
||||
{
|
||||
public static function register(): void
|
||||
{
|
||||
add_action('woocommerce_order_status_on-hold', [self::class, 'accept_stripe_authorization']);
|
||||
add_action('woocommerce_order_status_' . OrderStatuses::AUTHORIZED, [self::class, 'schedule_for_order']);
|
||||
add_action('bsc_submit_supplier_order', [self::class, 'run']);
|
||||
}
|
||||
|
||||
/** Promote only manually authorized orders from the official Stripe gateway. */
|
||||
public static function accept_stripe_authorization(int $order_id): void
|
||||
{
|
||||
$order = wc_get_order($order_id);
|
||||
if (
|
||||
!$order
|
||||
|| !self::is_stripe_order($order)
|
||||
|| $order->get_meta('_stripe_charge_captured') !== 'no'
|
||||
) {
|
||||
return;
|
||||
}
|
||||
|
||||
$fraud = FraudCheck::run($order);
|
||||
if (!$fraud['pass']) {
|
||||
self::fail_and_release($order, 'Fraud check failed: ' . $fraud['reason']);
|
||||
return;
|
||||
}
|
||||
|
||||
$order->update_status(OrderStatuses::AUTHORIZED, 'Stripe authorized the payment; awaiting supplier confirmation.');
|
||||
}
|
||||
|
||||
/**
|
||||
* WooCommerce's per-status transition hooks can fire more than once
|
||||
* for the same order (e.g. a status re-saved without actually
|
||||
@@ -105,11 +121,9 @@ class SupplierOrderJob
|
||||
}
|
||||
|
||||
/**
|
||||
* The supplier order just succeeded — this is the first point the
|
||||
* card is actually charged. Captures the preauth held since checkout,
|
||||
* then calls WC's own payment_complete() (which now fires
|
||||
* woocommerce_payment_complete for real, restoring that hook's
|
||||
* original meaning) before moving to Supplier Ordered.
|
||||
* The supplier order just succeeded — this is the first point the card
|
||||
* is actually charged. The official Stripe plugin captures when an
|
||||
* on-hold/manual-capture order transitions to Processing.
|
||||
*
|
||||
* Capture failing here (card expired/declined during the hold window
|
||||
* — rare, but real) is its own distinct failure mode from a supplier-
|
||||
@@ -122,42 +136,38 @@ class SupplierOrderJob
|
||||
*/
|
||||
private static function capture_and_complete(\WC_Order $order): void
|
||||
{
|
||||
$preauth_id = (int) $order->get_meta('_bsc_preauth_transaction_id');
|
||||
$amount = (float) $order->get_total();
|
||||
$order->update_status('processing', 'Supplier confirmed; requesting Stripe capture.');
|
||||
|
||||
try {
|
||||
$capture = HelcimClient::capture($preauth_id, $amount, HelcimGateway::client_ip());
|
||||
} catch (HelcimApiException $e) {
|
||||
$order->update_status(
|
||||
OrderStatuses::EXCEPTION,
|
||||
"Supplier order succeeded but capture failed ({$e->getMessage()}) — needs manual follow-up, do not resubmit to the supplier."
|
||||
);
|
||||
// Stripe's capture hook is synchronous and persists this flag. Reload
|
||||
// so a failed capture cannot be mistaken for a successful transition.
|
||||
$order = wc_get_order($order->get_id());
|
||||
if (!$order || $order->get_meta('_stripe_charge_captured') !== 'yes') {
|
||||
if ($order) {
|
||||
$order->update_status(
|
||||
OrderStatuses::EXCEPTION,
|
||||
'Supplier order succeeded but Stripe capture was not confirmed — needs manual follow-up; do not resubmit to the supplier.'
|
||||
);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
$order->payment_complete((string) ($capture['transactionId'] ?? $preauth_id));
|
||||
$order->update_status(OrderStatuses::SUPPLIER_ORDERED);
|
||||
$order->update_status(OrderStatuses::SUPPLIER_ORDERED, 'Stripe payment captured.');
|
||||
}
|
||||
|
||||
/**
|
||||
* Appendix B's residual risk ("a charge that later needs to be
|
||||
* undone becomes a refund... the store loses only the processing
|
||||
* fee") is exactly what this rework was for: nothing has been
|
||||
* charged yet at this point, so a failed supplier order releases the
|
||||
* hold instead — genuinely zero cost, not "only the processing fee."
|
||||
* Nothing has been charged yet. The Stripe extension releases an
|
||||
* uncaptured authorization when the order becomes Cancelled.
|
||||
*/
|
||||
private static function fail_and_release(\WC_Order $order, string $reason): void
|
||||
{
|
||||
$order->update_status(OrderStatuses::EXCEPTION, $reason);
|
||||
$order->update_status('cancelled', $reason . ' Releasing the Stripe authorization.');
|
||||
AuditTrail::record_void($order->get_id());
|
||||
$order->update_status(OrderStatuses::EXCEPTION, 'Stripe authorization release requested; order requires review.');
|
||||
}
|
||||
|
||||
$preauth_id = (int) $order->get_meta('_bsc_preauth_transaction_id');
|
||||
try {
|
||||
HelcimClient::reverse($preauth_id, HelcimGateway::client_ip());
|
||||
AuditTrail::record_void($order->get_id());
|
||||
} catch (HelcimApiException $e) {
|
||||
$order->add_order_note(
|
||||
'Could not release the card hold (' . $e->getMessage() . ') — it will expire on its own within 7 days; no manual refund needed.'
|
||||
);
|
||||
}
|
||||
private static function is_stripe_order(\WC_Order $order): bool
|
||||
{
|
||||
$method = $order->get_payment_method();
|
||||
return $method === 'stripe' || str_starts_with($method, 'stripe_');
|
||||
}
|
||||
}
|
||||
@@ -1,152 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Payments;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
/**
|
||||
* The two REST endpoints the Blocks checkout JS (assets/js/helcim-checkout-block.js)
|
||||
* calls to get a validated preauth before the WooCommerce order is even
|
||||
* submitted — see Payments\CheckoutSession's docblock for why this has
|
||||
* to happen before order creation rather than inside process_payment().
|
||||
*
|
||||
* init: server-side call to HelcimClient::initialize_checkout() (keeps
|
||||
* the API token off the client entirely) for the current cart total;
|
||||
* returns checkoutToken + secretToken to the client — this matches
|
||||
* Helcim's own documented HelcimPay.js pattern (their reference
|
||||
* validateResponse() example sends secretToken back to your endpoint
|
||||
* alongside the raw transaction response, rather than keeping it purely
|
||||
* server-side), not a deviation from it.
|
||||
* confirm: the client forwards {rawDataResponse, checkoutToken,
|
||||
* secretToken} here after HelcimPay.js's iframe completes (or, in fake
|
||||
* mode, after clicking "Simulate card entry"). Hash validation per
|
||||
* Helcim's documented algorithm: sha256(json_encode(rawDataResponse) .
|
||||
* secretToken), compared against the response's own hash field — the
|
||||
* exact field Helcim compares it to wasn't shown verbatim in what's
|
||||
* accessible without a real sandbox account, so this is a best-effort
|
||||
* implementation of their documented algorithm, not independently
|
||||
* confirmed against a real transaction yet.
|
||||
*/
|
||||
class CheckoutController
|
||||
{
|
||||
public static function register(): void
|
||||
{
|
||||
add_action('rest_api_init', [self::class, 'register_routes']);
|
||||
}
|
||||
|
||||
public static function register_routes(): void
|
||||
{
|
||||
register_rest_route('bsc/v1', '/helcim/init', [
|
||||
'methods' => 'POST',
|
||||
'callback' => [self::class, 'init'],
|
||||
'permission_callback' => '__return_true',
|
||||
]);
|
||||
|
||||
register_rest_route('bsc/v1', '/helcim/confirm', [
|
||||
'methods' => 'POST',
|
||||
'callback' => [self::class, 'confirm'],
|
||||
'permission_callback' => '__return_true',
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Confirmed directly (live testing): a plain register_rest_route()
|
||||
* callback does NOT get WC()->cart/WC()->session populated from the
|
||||
* customer's session cookie the way WooCommerce's own Store API
|
||||
* routes do (their cart endpoint saw the item; this one reported
|
||||
* "Cart is empty" for the identical session/cookie). wc_load_cart()
|
||||
* is WooCommerce's own documented fix for exactly this — background/
|
||||
* REST/AJAX contexts outside the normal front-end bootstrap that
|
||||
* still need the real session-backed cart.
|
||||
*/
|
||||
private static function ensure_cart_loaded(): void
|
||||
{
|
||||
if (function_exists('wc_load_cart')) {
|
||||
wc_load_cart();
|
||||
}
|
||||
// Confirmed directly (live testing): a freshly wc_load_cart()'d
|
||||
// cart's ->get_total('edit') reads 0 until something triggers its
|
||||
// lazy total calculation — is_empty()/get_cart() happen to do
|
||||
// this as a side effect, which is why init() (checks is_empty()
|
||||
// first) got the right amount but confirm() (reads the total as
|
||||
// its first cart touch) silently got 0. Calculating explicitly
|
||||
// here removes the dependency on that incidental ordering.
|
||||
if (WC()->cart) {
|
||||
WC()->cart->calculate_totals();
|
||||
}
|
||||
}
|
||||
|
||||
public static function init(\WP_REST_Request $request): \WP_REST_Response
|
||||
{
|
||||
self::ensure_cart_loaded();
|
||||
|
||||
if (!WC()->cart || WC()->cart->is_empty()) {
|
||||
return new \WP_REST_Response(['error' => 'Cart is empty.'], 400);
|
||||
}
|
||||
|
||||
$amount = (float) WC()->cart->get_total('edit');
|
||||
|
||||
try {
|
||||
$result = HelcimClient::initialize_checkout($amount, get_woocommerce_currency(), 'preauth');
|
||||
} catch (HelcimApiException $e) {
|
||||
return new \WP_REST_Response(['error' => $e->getMessage()], 502);
|
||||
}
|
||||
|
||||
return new \WP_REST_Response([
|
||||
'checkoutToken' => $result['checkoutToken'],
|
||||
'secretToken' => $result['secretToken'] ?? null,
|
||||
'amount' => $amount,
|
||||
'fakeMode' => !empty($result['fake']),
|
||||
]);
|
||||
}
|
||||
|
||||
public static function confirm(\WP_REST_Request $request): \WP_REST_Response
|
||||
{
|
||||
self::ensure_cart_loaded();
|
||||
$amount = (float) WC()->cart->get_total('edit');
|
||||
|
||||
if (!HelcimGatewayConfig::is_configured()) {
|
||||
$transaction = [
|
||||
'transactionId' => random_int(900000000, 999999999),
|
||||
'status' => 'APPROVED',
|
||||
'cardToken' => 'fake_card_token_' . wp_generate_uuid4(),
|
||||
];
|
||||
} else {
|
||||
$raw = $request->get_param('rawDataResponse');
|
||||
$secret = (string) $request->get_param('secretToken');
|
||||
$transaction = is_array($raw) ? $raw : json_decode((string) $raw, true);
|
||||
|
||||
if (!is_array($transaction) || !self::hash_is_valid($transaction, $secret)) {
|
||||
return new \WP_REST_Response(['error' => 'Could not validate the payment result.'], 400);
|
||||
}
|
||||
if (empty($transaction['transactionId']) || ($transaction['status'] ?? '') !== 'APPROVED') {
|
||||
return new \WP_REST_Response(['error' => 'Payment was not approved.'], 400);
|
||||
}
|
||||
}
|
||||
|
||||
CheckoutSession::stash_pending_preauth([
|
||||
'preauth_transaction_id' => (int) $transaction['transactionId'],
|
||||
'card_token' => $transaction['cardToken'] ?? null,
|
||||
'amount' => $amount,
|
||||
]);
|
||||
|
||||
return new \WP_REST_Response(['ok' => true]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Helcim's documented algorithm: sha256(json_encode(transaction data)
|
||||
* . secretToken), compared against the response's own hash field —
|
||||
* see this class's docblock for the "not independently confirmed
|
||||
* against a real transaction yet" caveat.
|
||||
*/
|
||||
private static function hash_is_valid(array $transaction, string $secret): bool
|
||||
{
|
||||
if (empty($transaction['hash']) || $secret === '') {
|
||||
return false;
|
||||
}
|
||||
$data = $transaction;
|
||||
unset($data['hash']);
|
||||
$expected = hash('sha256', wp_json_encode($data) . $secret);
|
||||
return hash_equals($expected, (string) $transaction['hash']);
|
||||
}
|
||||
}
|
||||
@@ -1,51 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Payments;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
/**
|
||||
* The preauth has to exist before the WooCommerce order does (the
|
||||
* customer is present entering card details in the HelcimPay.js iframe
|
||||
* before submitting checkout), but Order\CheckoutRecheck's price/margin
|
||||
* validation still runs after that, right before process_payment() — if
|
||||
* it fails there, a live uncaptured hold already exists and must be
|
||||
* reversed even though process_payment() is never reached. A short-lived
|
||||
* transient, keyed by the same customer-session identity
|
||||
* Order\CheckoutRecheck::lock_key() already uses for its advisory lock,
|
||||
* is what lets both HelcimGateway::process_payment() and
|
||||
* CheckoutRecheck's failure path find (and clear) the same pending
|
||||
* preauth regardless of which one runs first.
|
||||
*/
|
||||
class CheckoutSession
|
||||
{
|
||||
private const TTL = 20 * MINUTE_IN_SECONDS;
|
||||
|
||||
public static function identity(): string
|
||||
{
|
||||
return WC()->session ? (string) WC()->session->get_customer_id() : (string) session_id();
|
||||
}
|
||||
|
||||
public static function transient_key(): string
|
||||
{
|
||||
return 'bsc_preauth_' . md5(self::identity());
|
||||
}
|
||||
|
||||
/** @param array{preauth_transaction_id:int, card_token:?string, amount:float} $data */
|
||||
public static function stash_pending_preauth(array $data): void
|
||||
{
|
||||
set_transient(self::transient_key(), $data, self::TTL);
|
||||
}
|
||||
|
||||
/** @return array{preauth_transaction_id:int, card_token:?string, amount:float}|null */
|
||||
public static function pending_preauth(): ?array
|
||||
{
|
||||
$data = get_transient(self::transient_key());
|
||||
return is_array($data) ? $data : null;
|
||||
}
|
||||
|
||||
public static function clear_pending_preauth(): void
|
||||
{
|
||||
delete_transient(self::transient_key());
|
||||
}
|
||||
}
|
||||
@@ -5,18 +5,15 @@ namespace Bookstore\Core\Payments;
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
/**
|
||||
* Design doc §05: "local WooCommerce fraud checks plus Helcim's
|
||||
* payment-side risk signals." Deliberately a no-op by default for Week 3
|
||||
* Design doc §05 local WooCommerce fraud-check extension point. It is a
|
||||
* no-op by default for Week 3
|
||||
* — the user has decided not to build custom fraud heuristics now, only
|
||||
* the extension point an optional paid plugin (Shop Defender) plugs into
|
||||
* later via add_filter('bsc_fraud_check_result', ...). The step still
|
||||
* runs and is logged on every order, unconditionally, so "Fraud Check" is
|
||||
* a real, auditable stage in the state machine rather than an absent one.
|
||||
* Called from HelcimGateway::process_payment(), right after the card is
|
||||
* preauthorized (held) but before the order is allowed to proceed to
|
||||
* Authorized status — moved here from Order\CheckoutRecheck by the
|
||||
* preauth-then-capture rework: fraud review now runs after the hold
|
||||
* exists, not before, per design doc Appendix B's revised sequence.
|
||||
* Called after Stripe authorizes the card and places the order on hold,
|
||||
* before the order proceeds to supplier submission.
|
||||
*/
|
||||
class FraudCheck
|
||||
{
|
||||
|
||||
@@ -1,9 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Payments;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
class HelcimApiException extends \RuntimeException
|
||||
{
|
||||
}
|
||||
@@ -1,64 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Payments;
|
||||
|
||||
use Automattic\WooCommerce\Blocks\Payments\Integrations\AbstractPaymentMethodType;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
/**
|
||||
* Blocks/Store API side of Payments\HelcimGateway — this store only
|
||||
* serves Cart/Checkout blocks (confirmed live, no shortcode checkout
|
||||
* exists — see Order\CheckoutRecheck's docblock), so a plain
|
||||
* WC_Payment_Gateway alone isn't enough to show up at checkout; it also
|
||||
* needs registering here plus a matching JS bundle
|
||||
* (assets/js/helcim-checkout-block.js) via
|
||||
* wc.wcBlocksRegistry.registerPaymentMethod. process_payment() on the
|
||||
* gateway itself is still what actually runs server-side — this class
|
||||
* only handles the block rendering/script-enqueueing side.
|
||||
*/
|
||||
class HelcimBlocksIntegration extends AbstractPaymentMethodType
|
||||
{
|
||||
protected $name = 'bsc_helcim';
|
||||
|
||||
public function initialize(): void
|
||||
{
|
||||
$this->settings = get_option(HelcimGatewayConfig::OPTION_NAME, []);
|
||||
}
|
||||
|
||||
public function is_active(): bool
|
||||
{
|
||||
return ($this->settings['enabled'] ?? 'no') === 'yes';
|
||||
}
|
||||
|
||||
public function get_payment_method_script_handles(): array
|
||||
{
|
||||
$asset_path = BSC_PLUGIN_DIR . 'assets/js/helcim-checkout-block.js';
|
||||
|
||||
wp_register_script(
|
||||
'bsc-helcim-checkout-block',
|
||||
plugins_url('assets/js/helcim-checkout-block.js', BSC_PLUGIN_FILE),
|
||||
['wc-blocks-registry', 'wc-settings', 'wp-element', 'wp-i18n'],
|
||||
file_exists($asset_path) ? (string) filemtime($asset_path) : BSC_VERSION,
|
||||
true
|
||||
);
|
||||
|
||||
wp_localize_script('bsc-helcim-checkout-block', 'bscHelcimData', [
|
||||
'title' => $this->settings['title'] ?? 'Credit Card',
|
||||
'description' => $this->settings['description'] ?? '',
|
||||
'restUrl' => esc_url_raw(rest_url('bsc/v1/helcim')),
|
||||
'nonce' => wp_create_nonce('wp_rest'),
|
||||
'fakeMode' => !HelcimGatewayConfig::is_configured(),
|
||||
]);
|
||||
|
||||
return ['bsc-helcim-checkout-block'];
|
||||
}
|
||||
|
||||
public function get_payment_method_data(): array
|
||||
{
|
||||
return [
|
||||
'title' => $this->settings['title'] ?? 'Credit Card',
|
||||
'description' => $this->settings['description'] ?? '',
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -1,123 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Payments;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
/**
|
||||
* Thin wrapper around Helcim's Payment API (devdocs.helcim.com), built
|
||||
* directly against HelcimPay.js/the raw API rather than the off-the-shelf
|
||||
* helcim-commerce-for-woocommerce plugin — see design doc Appendix B's
|
||||
* revised decision. Endpoints/parameters confirmed against Helcim's
|
||||
* current developer docs:
|
||||
* - POST /v2/helcim-pay/initialize {paymentType, amount, currency}
|
||||
* -> {checkoutToken, secretToken}
|
||||
* - POST /v2/payment/capture {preAuthTransactionId, amount, ipAddress}
|
||||
* -> transaction object (incl. cardToken, transactionId)
|
||||
* - POST /v2/payment/reverse {cardTransactionId, ipAddress}
|
||||
* -> transaction object
|
||||
* Capture/reverse's exact base path (the /v2 prefix specifically) was
|
||||
* not shown alongside their parameter docs the way initialize's was —
|
||||
* confirm against a real sandbox call before this is ever used in
|
||||
* anything but fake mode.
|
||||
*
|
||||
* FAKE MODE: HelcimGatewayConfig::is_configured() is false until a real
|
||||
* token exists (none does yet, pre-launch). Rather than blocking all
|
||||
* development on getting Helcim sandbox access, every method here
|
||||
* returns a synthetic approved response when unconfigured — same
|
||||
* pattern this project already uses on the supplier side before real
|
||||
* BooksRun access existed (Import\SyntheticOfferGenerator, the
|
||||
* gutenberg_test supplier). This lets the entire checkout -> preauth ->
|
||||
* fraud -> supplier -> capture/reverse flow be driven for real through
|
||||
* the WooCommerce/Blocks plumbing in dev today. The instant a real token
|
||||
* lands in HELCIM_API_TOKEN, every call here switches to hitting the
|
||||
* real API — no code change required anywhere.
|
||||
*/
|
||||
class HelcimClient
|
||||
{
|
||||
private const API_BASE = 'https://api.helcim.com/v2';
|
||||
|
||||
public static function initialize_checkout(float $amount, string $currency, string $payment_type): array
|
||||
{
|
||||
if (!HelcimGatewayConfig::is_configured()) {
|
||||
return [
|
||||
'checkoutToken' => 'fake_checkout_' . wp_generate_uuid4(),
|
||||
'secretToken' => 'fake_secret_' . wp_generate_uuid4(),
|
||||
'fake' => true,
|
||||
];
|
||||
}
|
||||
|
||||
return self::post('/helcim-pay/initialize', [
|
||||
'paymentType' => $payment_type,
|
||||
'amount' => $amount,
|
||||
'currency' => $currency,
|
||||
], with_idempotency_key: false);
|
||||
}
|
||||
|
||||
public static function capture(int $preauth_transaction_id, float $amount, string $ip_address): array
|
||||
{
|
||||
if (!HelcimGatewayConfig::is_configured()) {
|
||||
return self::fake_transaction_response($amount);
|
||||
}
|
||||
|
||||
return self::post('/payment/capture', [
|
||||
'preAuthTransactionId' => $preauth_transaction_id,
|
||||
'amount' => $amount,
|
||||
'ipAddress' => $ip_address,
|
||||
], with_idempotency_key: true);
|
||||
}
|
||||
|
||||
public static function reverse(int $transaction_id, string $ip_address): array
|
||||
{
|
||||
if (!HelcimGatewayConfig::is_configured()) {
|
||||
return self::fake_transaction_response(0.0);
|
||||
}
|
||||
|
||||
return self::post('/payment/reverse', [
|
||||
'cardTransactionId' => $transaction_id,
|
||||
'ipAddress' => $ip_address,
|
||||
], with_idempotency_key: true);
|
||||
}
|
||||
|
||||
private static function fake_transaction_response(float $amount): array
|
||||
{
|
||||
return [
|
||||
'transactionId' => random_int(900000000, 999999999),
|
||||
'status' => 'APPROVED',
|
||||
'amount' => $amount,
|
||||
'cardToken' => 'fake_card_token_' . wp_generate_uuid4(),
|
||||
'fake' => true,
|
||||
];
|
||||
}
|
||||
|
||||
private static function post(string $path, array $body, bool $with_idempotency_key): array
|
||||
{
|
||||
$token = HelcimGatewayConfig::token();
|
||||
$headers = ['api-token' => $token, 'Content-Type' => 'application/json'];
|
||||
if ($with_idempotency_key) {
|
||||
$headers['idempotency-key'] = wp_generate_uuid4();
|
||||
}
|
||||
|
||||
$response = wp_remote_post(self::API_BASE . $path, [
|
||||
'headers' => $headers,
|
||||
'body' => wp_json_encode($body),
|
||||
'timeout' => 30,
|
||||
]);
|
||||
|
||||
if (is_wp_error($response)) {
|
||||
throw new HelcimApiException('Helcim API request failed: ' . $response->get_error_message());
|
||||
}
|
||||
|
||||
$code = wp_remote_retrieve_response_code($response);
|
||||
$decoded = json_decode(wp_remote_retrieve_body($response), true);
|
||||
|
||||
if ($code < 200 || $code >= 300 || !is_array($decoded) || !empty($decoded['errors'])) {
|
||||
$message = is_array($decoded) && !empty($decoded['errors'])
|
||||
? implode('; ', (array) $decoded['errors'])
|
||||
: "unexpected HTTP {$code}";
|
||||
throw new HelcimApiException("Helcim API error on {$path}: {$message}");
|
||||
}
|
||||
|
||||
return $decoded;
|
||||
}
|
||||
}
|
||||
@@ -1,127 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Payments;
|
||||
|
||||
use Bookstore\Core\Order\OrderStatuses;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
/**
|
||||
* Custom WC_Payment_Gateway against HelcimPay.js directly (id
|
||||
* `bsc_helcim`) — replaces the off-the-shelf helcim-commerce-for-
|
||||
* woocommerce plugin's immediate-charge flow. See design doc Appendix
|
||||
* B's revised decision and Payments\HelcimClient's docblock (fake mode).
|
||||
*
|
||||
* process_payment() does NOT charge the card. By the time it runs, the
|
||||
* customer has already completed a preauth via the Blocks checkout JS
|
||||
* (assets/js/helcim-checkout-block.js) — Payments\CheckoutController's
|
||||
* /confirm endpoint already validated it and stashed it in
|
||||
* Payments\CheckoutSession. This method's job is: pick up that pending
|
||||
* preauth, run the (moved-here) fraud check, and either reverse the hold
|
||||
* and route to review, or mark the order Authorized and let
|
||||
* Order\SupplierOrderJob take it from there — capture only happens
|
||||
* after a successful supplier order.
|
||||
*/
|
||||
class HelcimGateway extends \WC_Payment_Gateway
|
||||
{
|
||||
public function __construct()
|
||||
{
|
||||
$this->id = 'bsc_helcim';
|
||||
$this->method_title = 'Helcim (preauth/capture)';
|
||||
$this->method_description = 'Card is held (preauth) at checkout and only captured once the supplier order succeeds — see design doc Appendix B.';
|
||||
$this->has_fields = false;
|
||||
$this->supports = ['products'];
|
||||
|
||||
$this->init_form_fields();
|
||||
$this->init_settings();
|
||||
|
||||
$this->title = $this->get_option('title', 'Credit Card');
|
||||
$this->description = $this->get_option('description', '');
|
||||
$this->enabled = $this->get_option('enabled', 'no');
|
||||
|
||||
add_action('woocommerce_update_options_payment_gateways_' . $this->id, [$this, 'process_admin_options']);
|
||||
}
|
||||
|
||||
public function init_form_fields(): void
|
||||
{
|
||||
$this->form_fields = [
|
||||
'enabled' => [
|
||||
'title' => 'Enable/Disable',
|
||||
'type' => 'checkbox',
|
||||
'label' => 'Enable this payment method',
|
||||
'default' => 'no',
|
||||
],
|
||||
'title' => [
|
||||
'title' => 'Title',
|
||||
'type' => 'text',
|
||||
'default' => 'Credit Card',
|
||||
],
|
||||
'description' => [
|
||||
'title' => 'Description',
|
||||
'type' => 'textarea',
|
||||
'default' => '',
|
||||
],
|
||||
'environment' => [
|
||||
'title' => 'Environment',
|
||||
'type' => 'select',
|
||||
'options' => ['sandbox' => 'Sandbox', 'live' => 'Live'],
|
||||
'default' => 'sandbox',
|
||||
],
|
||||
];
|
||||
}
|
||||
|
||||
public function process_payment($order_id): array
|
||||
{
|
||||
$order = wc_get_order($order_id);
|
||||
$pending = CheckoutSession::pending_preauth();
|
||||
|
||||
if (!$order || !$pending) {
|
||||
wc_add_notice('Your payment session expired — please try again.', 'error');
|
||||
return ['result' => 'failure'];
|
||||
}
|
||||
|
||||
CheckoutSession::clear_pending_preauth();
|
||||
|
||||
$order->update_meta_data('_bsc_preauth_transaction_id', $pending['preauth_transaction_id']);
|
||||
$order->update_meta_data('_bsc_preauth_card_token', $pending['card_token']);
|
||||
$order->update_meta_data('_bsc_preauth_amount', $pending['amount']);
|
||||
$order->save();
|
||||
|
||||
$fraud = FraudCheck::run($order);
|
||||
if (!$fraud['pass']) {
|
||||
$this->reverse_preauth($pending['preauth_transaction_id'], "Fraud check failed: {$fraud['reason']}");
|
||||
$order->update_status(OrderStatuses::EXCEPTION, "Fraud check failed: {$fraud['reason']}");
|
||||
wc_add_notice('Your order could not be processed and has been placed under review. Your card was not charged.', 'error');
|
||||
return ['result' => 'failure'];
|
||||
}
|
||||
|
||||
$order->update_status(OrderStatuses::AUTHORIZED, 'Card authorized (preauth held) — not yet charged.');
|
||||
|
||||
return [
|
||||
'result' => 'success',
|
||||
'redirect' => $this->get_return_url($order),
|
||||
];
|
||||
}
|
||||
|
||||
private function reverse_preauth(int $preauth_transaction_id, string $reason): void
|
||||
{
|
||||
try {
|
||||
HelcimClient::reverse($preauth_transaction_id, self::client_ip());
|
||||
} catch (HelcimApiException $e) {
|
||||
// Nothing was charged either way; a failed reverse call just
|
||||
// means the hold expires on its own within Helcim's 7-day
|
||||
// window instead of being released immediately — logged so
|
||||
// it's not silently invisible, matching "every failure path
|
||||
// must end in a visible review state."
|
||||
error_log("bsc_helcim: reverse failed for transaction {$preauth_transaction_id} ({$reason}): " . $e->getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
public static function client_ip(): string
|
||||
{
|
||||
if (class_exists(\WC_Geolocation::class)) {
|
||||
return \WC_Geolocation::get_ip_address();
|
||||
}
|
||||
return $_SERVER['REMOTE_ADDR'] ?? '0.0.0.0';
|
||||
}
|
||||
}
|
||||
@@ -1,79 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Payments;
|
||||
|
||||
defined('ABSPATH') || exit;
|
||||
|
||||
/**
|
||||
* Replaces Payments\HelcimConfig (which seeded settings for the
|
||||
* off-the-shelf helcim-commerce-for-woocommerce plugin — removed, see
|
||||
* design doc Appendix B's revised decision: that plugin only supports
|
||||
* immediate-charge "Purchase" transactions, not the preauth/capture flow
|
||||
* this now uses, so a custom gateway (Payments\HelcimGateway) replaces
|
||||
* it rather than extending it). Gateway id `bsc_helcim`, settings option
|
||||
* `woocommerce_bsc_helcim_settings` — our own, not the old plugin's.
|
||||
*
|
||||
* _FILE env-var reading mirrors Integration\HardcoverAdapter::token()
|
||||
* exactly, same reasoning: a plain ${VAR} is visible via `docker
|
||||
* inspect`/`/proc/<pid>/environ`, a 644 file inside a 700 secrets/ dir
|
||||
* isn't.
|
||||
*/
|
||||
class HelcimGatewayConfig
|
||||
{
|
||||
public const OPTION_NAME = 'woocommerce_bsc_helcim_settings';
|
||||
|
||||
/**
|
||||
* False today (no HELCIM_API_TOKEN in any .env yet) — this is
|
||||
* exactly the condition Payments\HelcimClient checks to decide
|
||||
* whether to talk to the real Helcim API or return fake-mode
|
||||
* responses. Flips to true, with zero code changes anywhere else,
|
||||
* the moment a real sandbox token is added.
|
||||
*/
|
||||
public static function is_configured(): bool
|
||||
{
|
||||
return self::token() !== null;
|
||||
}
|
||||
|
||||
public static function token(): ?string
|
||||
{
|
||||
$file = getenv('HELCIM_API_TOKEN_FILE');
|
||||
if (!$file || !is_readable($file)) {
|
||||
return null;
|
||||
}
|
||||
$value = trim((string) file_get_contents($file));
|
||||
return $value !== '' ? $value : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fills in only what's still unset — never overwrites a value a human
|
||||
* already changed by hand in wp-admin. Only ever seeds the sandbox
|
||||
* token: this repo has no production Helcim credentials, and going
|
||||
* live is a deliberate separate decision a human makes on the
|
||||
* settings screen, not something an env var should flip silently.
|
||||
*/
|
||||
public static function ensure_configured_from_env(): void
|
||||
{
|
||||
$token = self::token();
|
||||
if ($token === null) {
|
||||
return;
|
||||
}
|
||||
|
||||
$settings = get_option(self::OPTION_NAME, []);
|
||||
if (!is_array($settings)) {
|
||||
$settings = [];
|
||||
}
|
||||
|
||||
$settings += [
|
||||
'enabled' => 'no', // a human opts in explicitly once ready to test live at checkout
|
||||
'title' => 'Credit Card',
|
||||
'description' => '',
|
||||
'environment' => 'sandbox',
|
||||
];
|
||||
|
||||
if (empty($settings['sandbox_api_token'])) {
|
||||
$settings['sandbox_api_token'] = $token;
|
||||
}
|
||||
|
||||
update_option(self::OPTION_NAME, $settings);
|
||||
}
|
||||
}
|
||||
@@ -10,7 +10,7 @@ defined('ABSPATH') || exit;
|
||||
/**
|
||||
* Design doc §05: Retail Price = (Supplier Base + Supplier Shipping +
|
||||
* Fixed Processing) / (1 - Processing Rate - Target Margin). Processing
|
||||
* Rate is a placeholder blended estimate — tune from real Helcim
|
||||
* Rate is a placeholder blended estimate — tune from real Stripe
|
||||
* settlement data once it exists, not from guessing.
|
||||
*/
|
||||
class PricingEngine
|
||||
@@ -58,7 +58,7 @@ class PricingEngine
|
||||
}
|
||||
|
||||
/**
|
||||
* Week 3: what calculate_retail_price() assumed Helcim's cut would be
|
||||
* Week 3: what calculate_retail_price() assumed Stripe's cut would be
|
||||
* for a given selling price, for the order-audit ledger
|
||||
* (Order\AuditTrail) to compare against actual settlement later.
|
||||
* Exposed as its own method (rather than inlining the formula at every
|
||||
|
||||
@@ -1,115 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Tests\Unit\Payments;
|
||||
|
||||
use Bookstore\Core\Payments\HelcimApiException;
|
||||
use Bookstore\Core\Payments\HelcimClient;
|
||||
use Bookstore\Core\Tests\TestCase;
|
||||
use Brain\Monkey\Functions;
|
||||
|
||||
/**
|
||||
* HelcimGatewayConfig::token() reads getenv('HELCIM_API_TOKEN_FILE') —
|
||||
* mocking that directly is what switches HelcimClient between fake mode
|
||||
* (no token: every call returns a synthetic approved response, no
|
||||
* network call) and real mode (a token: real wp_remote_post calls with
|
||||
* the shape confirmed against Helcim's current developer docs).
|
||||
*/
|
||||
class HelcimClientTest extends TestCase
|
||||
{
|
||||
public function test_fake_mode_never_calls_the_real_api(): void
|
||||
{
|
||||
Functions\when('getenv')->justReturn(false);
|
||||
Functions\when('wp_generate_uuid4')->justReturn('fake-uuid');
|
||||
Functions\expect('wp_remote_post')->never();
|
||||
|
||||
$init = HelcimClient::initialize_checkout(42.00, 'USD', 'preauth');
|
||||
$this->assertTrue($init['fake']);
|
||||
$this->assertNotEmpty($init['checkoutToken']);
|
||||
$this->assertNotEmpty($init['secretToken']);
|
||||
|
||||
$capture = HelcimClient::capture(123456, 42.00, '127.0.0.1');
|
||||
$this->assertSame('APPROVED', $capture['status']);
|
||||
$this->assertIsInt($capture['transactionId']);
|
||||
$this->assertNotEmpty($capture['cardToken']);
|
||||
|
||||
$reverse = HelcimClient::reverse(123456, '127.0.0.1');
|
||||
$this->assertSame('APPROVED', $reverse['status']);
|
||||
}
|
||||
|
||||
public function test_real_mode_initialize_sends_the_documented_request_shape(): void
|
||||
{
|
||||
Functions\when('getenv')->justReturn('/fake/path/to/token');
|
||||
Functions\when('is_readable')->justReturn(true);
|
||||
Functions\when('file_get_contents')->justReturn('real-token-abc');
|
||||
Functions\when('wp_json_encode')->alias('json_encode');
|
||||
Functions\when('is_wp_error')->justReturn(false);
|
||||
Functions\when('wp_remote_retrieve_response_code')->justReturn(200);
|
||||
Functions\when('wp_remote_retrieve_body')->justReturn(json_encode([
|
||||
'checkoutToken' => 'real-checkout-token',
|
||||
'secretToken' => 'real-secret-token',
|
||||
]));
|
||||
|
||||
Functions\expect('wp_remote_post')
|
||||
->once()
|
||||
->withArgs(function ($url, $args) {
|
||||
$this->assertSame('https://api.helcim.com/v2/helcim-pay/initialize', $url);
|
||||
$this->assertSame('real-token-abc', $args['headers']['api-token']);
|
||||
$this->assertArrayNotHasKey('idempotency-key', $args['headers']);
|
||||
$body = json_decode($args['body'], true);
|
||||
$this->assertSame('preauth', $body['paymentType']);
|
||||
$this->assertEquals(42.0, $body['amount']);
|
||||
$this->assertSame('USD', $body['currency']);
|
||||
return true;
|
||||
})
|
||||
->andReturn(['response' => ['code' => 200]]);
|
||||
|
||||
$result = HelcimClient::initialize_checkout(42.00, 'USD', 'preauth');
|
||||
$this->assertSame('real-checkout-token', $result['checkoutToken']);
|
||||
}
|
||||
|
||||
public function test_real_mode_capture_includes_an_idempotency_key(): void
|
||||
{
|
||||
Functions\when('getenv')->justReturn('/fake/path/to/token');
|
||||
Functions\when('is_readable')->justReturn(true);
|
||||
Functions\when('file_get_contents')->justReturn('real-token-abc');
|
||||
Functions\when('wp_json_encode')->alias('json_encode');
|
||||
Functions\when('wp_generate_uuid4')->justReturn('idem-key-123');
|
||||
Functions\when('is_wp_error')->justReturn(false);
|
||||
Functions\when('wp_remote_retrieve_response_code')->justReturn(200);
|
||||
Functions\when('wp_remote_retrieve_body')->justReturn(json_encode(['transactionId' => 999, 'status' => 'APPROVED']));
|
||||
|
||||
Functions\expect('wp_remote_post')
|
||||
->once()
|
||||
->withArgs(function ($url, $args) {
|
||||
$this->assertSame('https://api.helcim.com/v2/payment/capture', $url);
|
||||
$this->assertSame('idem-key-123', $args['headers']['idempotency-key']);
|
||||
$body = json_decode($args['body'], true);
|
||||
$this->assertSame(555, $body['preAuthTransactionId']);
|
||||
$this->assertEquals(42.0, $body['amount']);
|
||||
$this->assertSame('127.0.0.1', $body['ipAddress']);
|
||||
return true;
|
||||
})
|
||||
->andReturn(['response' => ['code' => 200]]);
|
||||
|
||||
$result = HelcimClient::capture(555, 42.00, '127.0.0.1');
|
||||
$this->assertSame(999, $result['transactionId']);
|
||||
}
|
||||
|
||||
public function test_real_mode_throws_on_an_error_response(): void
|
||||
{
|
||||
Functions\when('getenv')->justReturn('/fake/path/to/token');
|
||||
Functions\when('is_readable')->justReturn(true);
|
||||
Functions\when('file_get_contents')->justReturn('real-token-abc');
|
||||
Functions\when('wp_json_encode')->alias('json_encode');
|
||||
Functions\when('wp_generate_uuid4')->justReturn('idem-key-123');
|
||||
Functions\when('is_wp_error')->justReturn(false);
|
||||
Functions\when('wp_remote_retrieve_response_code')->justReturn(422);
|
||||
Functions\when('wp_remote_retrieve_body')->justReturn(json_encode(['errors' => ['card declined']]));
|
||||
Functions\when('wp_remote_post')->justReturn(['response' => ['code' => 422]]);
|
||||
|
||||
$this->expectException(HelcimApiException::class);
|
||||
$this->expectExceptionMessageMatches('/card declined/');
|
||||
|
||||
HelcimClient::capture(555, 42.00, '127.0.0.1');
|
||||
}
|
||||
}
|
||||
@@ -1,84 +0,0 @@
|
||||
<?php
|
||||
|
||||
namespace Bookstore\Core\Tests\Unit\Payments;
|
||||
|
||||
use Bookstore\Core\Order\OrderStatuses;
|
||||
use Bookstore\Core\Payments\HelcimGateway;
|
||||
use Bookstore\Core\Tests\TestCase;
|
||||
use Brain\Monkey\Functions;
|
||||
use Mockery;
|
||||
|
||||
/**
|
||||
* process_payment()'s branching: pick up the preauth CheckoutController
|
||||
* already stashed (Payments\CheckoutSession, backed by get/set/delete_
|
||||
* transient — mocked at that WP-function layer, not by mocking
|
||||
* CheckoutSession itself, matching this suite's established pattern),
|
||||
* run the (moved-here) fraud check, and either authorize the order or
|
||||
* reverse the hold and route to review. HelcimClient runs in fake mode
|
||||
* here (no token env) so no real network call is involved either way.
|
||||
*/
|
||||
class HelcimGatewayTest extends TestCase
|
||||
{
|
||||
private function stub_pending_preauth(?array $data): void
|
||||
{
|
||||
Functions\when('get_transient')->justReturn($data);
|
||||
Functions\when('delete_transient')->justReturn(true);
|
||||
Functions\when('getenv')->justReturn(false); // HelcimClient stays in fake mode
|
||||
Functions\when('wp_generate_uuid4')->justReturn('fake-uuid');
|
||||
Functions\when('WC')->justReturn((object) ['session' => null]); // CheckoutSession::identity() falls back to session_id()
|
||||
}
|
||||
|
||||
private function mock_order(): \WC_Order
|
||||
{
|
||||
$order = Mockery::mock(\WC_Order::class);
|
||||
$order->shouldReceive('update_meta_data')->withAnyArgs();
|
||||
$order->shouldReceive('save');
|
||||
$order->shouldReceive('add_order_note')->withAnyArgs();
|
||||
$order->shouldReceive('get_meta')->withAnyArgs()->andReturn('');
|
||||
return $order;
|
||||
}
|
||||
|
||||
public function test_no_pending_preauth_fails_without_touching_the_order(): void
|
||||
{
|
||||
$this->stub_pending_preauth(null);
|
||||
Functions\when('wc_get_order')->justReturn(Mockery::mock(\WC_Order::class));
|
||||
Functions\expect('wc_add_notice')->once();
|
||||
|
||||
$gateway = new HelcimGateway();
|
||||
$result = $gateway->process_payment(123);
|
||||
|
||||
$this->assertSame('failure', $result['result']);
|
||||
}
|
||||
|
||||
public function test_fraud_pass_authorizes_the_order(): void
|
||||
{
|
||||
$this->stub_pending_preauth(['preauth_transaction_id' => 555, 'card_token' => 'tok_1', 'amount' => 42.00]);
|
||||
Functions\when('apply_filters')->justReturn(['pass' => true, 'reason' => 'no-op: fraud plugin not installed']);
|
||||
|
||||
$order = $this->mock_order();
|
||||
$order->shouldReceive('update_status')->once()->with(OrderStatuses::AUTHORIZED, Mockery::type('string'));
|
||||
Functions\when('wc_get_order')->justReturn($order);
|
||||
|
||||
$gateway = new HelcimGateway();
|
||||
$result = $gateway->process_payment(123);
|
||||
|
||||
$this->assertSame('success', $result['result']);
|
||||
$this->assertArrayHasKey('redirect', $result);
|
||||
}
|
||||
|
||||
public function test_fraud_fail_reverses_the_hold_and_routes_to_exception(): void
|
||||
{
|
||||
$this->stub_pending_preauth(['preauth_transaction_id' => 555, 'card_token' => 'tok_1', 'amount' => 42.00]);
|
||||
Functions\when('apply_filters')->justReturn(['pass' => false, 'reason' => 'high risk score']);
|
||||
Functions\expect('wc_add_notice')->once();
|
||||
|
||||
$order = $this->mock_order();
|
||||
$order->shouldReceive('update_status')->once()->with(OrderStatuses::EXCEPTION, Mockery::type('string'));
|
||||
Functions\when('wc_get_order')->justReturn($order);
|
||||
|
||||
$gateway = new HelcimGateway();
|
||||
$result = $gateway->process_payment(123);
|
||||
|
||||
$this->assertSame('failure', $result['result']);
|
||||
}
|
||||
}
|
||||
@@ -27,46 +27,6 @@ if (!class_exists(\WC_Cart::class)) {
|
||||
}
|
||||
}
|
||||
|
||||
// Payments\HelcimGateway extends this. Minimal stand-in for the real
|
||||
// WC_Payment_Gateway's settings-API plumbing (init_settings()/
|
||||
// get_option()) so the constructor doesn't fatal in a unit test — real
|
||||
// WooCommerce's version does much more (admin fields rendering, etc.),
|
||||
// none of which the gateway's process_payment() branching depends on.
|
||||
if (!class_exists(\WC_Payment_Gateway::class)) {
|
||||
class WC_Payment_Gateway
|
||||
{
|
||||
public $id;
|
||||
public $method_title;
|
||||
public $method_description;
|
||||
public $has_fields;
|
||||
public $supports = [];
|
||||
public $title;
|
||||
public $description;
|
||||
public $enabled;
|
||||
public $form_fields = [];
|
||||
public $settings = [];
|
||||
|
||||
public function init_settings(): void
|
||||
{
|
||||
$this->settings = [];
|
||||
}
|
||||
|
||||
public function get_option($key, $default = '')
|
||||
{
|
||||
return $this->settings[$key] ?? $default;
|
||||
}
|
||||
|
||||
public function get_return_url($order)
|
||||
{
|
||||
return 'https://example.test/order-received/';
|
||||
}
|
||||
|
||||
public function process_admin_options(): void
|
||||
{
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (!class_exists(\WP_Error::class)) {
|
||||
class WP_Error
|
||||
{
|
||||
|
||||
Reference in new issue
Block a user