YS CART – ECPay

⚠️ Upgrade Order (Please read first)

Hard requirement for this board YS CART core >= 2.57.0Please.First upgrade the core to 2.57.1, then update this plugin。

When the core version is insufficient, this plugin will hang at the startup gate:Do not register any payment gateways, shipping methods, REST routes, or CLI, only display the notice in the backend. If the order is reversed, ECPay's payment method and logistics order creation on the checkout page will temporarily disappear until the core upgrade is complete.

Add New

• Credit card refund (query-first state machine)First check the closing status of `CreditDetail/QueryTrade`, then route according to ECPay's official workflow—authorized → N (full amount only), full amount closing → E followed by N, partial closing → R, already closed → R; deny the operation in all cases of unknown status.
• crash-safe idempotent protectionUse the core `refund_request_id` as the idempotency key. If an identical request has already succeeded, complete evidence is required to determine an idempotent replay;Transmission uncertainty (timeout / non-2xx / no RtnCode) shall always remain pending; blind retries are rejected.Retry only if the provider explicitly refuses.
• atomic refund reservationArbitration and writes are completed within the same CAS closure, and under concurrency, only one request can successfully reserve; any `DoAction` must occur after the reservation is persisted.
• Transaction fingerprint matchingAmount / `TradeNo` / `MerchantTradeNo` / `gwsr` / Environment / Merchant ID must be typed-present and type-sensitive; old records lacking a fingerprint are strictly regarded as "unable to prove it is the same transaction."
• immutable result eventAdd an append-only log for every payment flow action (step, attempted/executed, transmission category, RtnCode/RtnMsg, response transaction ID, fingerprint digest, timestamp).
• Order-level refund freezeReject any new refund requests if there are any pending refund requests with undetermined outcomes, until manual review and approval.
• `wp ys-cart-ecpay refund-attempt` CLI (list / resolve; resolve is a true CAS conditional UPDATE).
• Credit Card Security Code (CreditCheckCode) Configure fields: encrypted storage, same atomic pipeline as payment credentials; modify order creation to send `NeedExtraPaidInfo=Y` and persist the authorization order number (gwsr).
• Installment / reward / UnionPay / transactions with unprovable payment methods are all directed to manual refunds (fail-closed).

Changes (Core 2.57.0 Matching)

• Declare core hard requirement `YS_CART_ECPAY_REQUIRES_CORE = 2.57.0`; capability probing adds `YSPaymentDetailStore` and `YSPaymentDispatch::current_operation_key`. Total core absence is also changed to notice-only (no longer silent).
• All writes to payment_detailDelegated Core Shared CAS(`YSPaymentDetailStore`); the logistics callback's shipping projection also goes through this CAS—payment notification, refund ledger, and logistics projection are henceforth coordinated writers of the same JSON field.
• MerchantTradeNo is now derived from the core stable operation key.

Current restrictions (please note)

• Credit card refundLive testing in a controlled official store environment(Green World stage environment does not officially provide DoAction.) Before gate is completed Automatic refunds are disabled by default., maintain record-only/manual-only; `ys_ec_ecpay_auto_refund_enabled` must be explicitly enabled.
• Stage mode directly rejects refund reversals.
• ATM, convenience store, and barcode payments remain manual refunds; only credit cards declare `supports_gateway_refund()`.

Verify

• Clean clone × Official core 2.57.1: Full return All 25 stocks are in the green。
• Two independent clean clone rebuilds, ZIP bytes are identical (`sha256 c898bc68…`).
• Kit contents contract 26/0: 67 files + 30 directories, bit-for-bit identical with git HEAD blobs file by file.