Paywiser

Context

Paywiser provides merchant acquiring and payment gateway infrastructure for card payments. For WooCommerce merchants, the integration needs to fit WooCommerce’s order lifecycle and handle asynchronous outcomes (redirect flows and server-side postbacks) without leaving orders in ambiguous states.

Problem

Card payment flows in WooCommerce have a few non-negotiables:

• Checkout must transition orders into predictable states (pending → paid/failed).
• Redirect-based flows must handle “customer returned” correctly.
• Server-to-server notifications must be verified to prevent tampering.
• Modern checkout (WooCommerce Blocks) needs a dedicated integration layer.

Project Goals

• Provide Paywiser as a first-class payment method in WooCommerce checkout.
• Support Paywiser’s Redirect and Hosted solutions from a single plugin.
• Verify postback payloads and update order state deterministically.
• Keep the integration compatible with both legacy checkout and Blocks checkout.

Constraints & Challenges

• Follow the `WC_Payment_Gateway` lifecycle to avoid brittle checkout behavior.
• Treat postback/return parameters as untrusted input and verify them.
• Avoid rounding mismatches by aligning amounts sent to the gateway with WooCommerce totals.
• Keep configuration merchant-friendly under `WooCommerce → Settings → Payments`.

Solution Overview

We implemented a WooCommerce gateway plugin that:

• Registers a new payment method (`paywiser`) with configurable title/description.
• Supports two gateway modes: Redirect (hosted pages) and Hosted (card details captured in checkout).
• Submits transactions to Paywiser TxHandler via HTTP POST to `https://office.paywiser.com/secure/txHandler.php`.
• Receives and verifies payment results via `/wc-api/pw-postback` and the `order-received` return flow.

Architecture & Technical Approach

Gateway configuration

• `sid` and `rcode`
• solution type: `redirect` or `hosted`
• transaction action: `PREAUTH` or `PAYMENT`

Checkout initiation

• posts a form to TxHandler with totals, customer fields, postback URL and redirect URL
• includes an MD5 request hash for validation

Postback verification and order finalization

The postback handler verifies the payload using the `vrfy` SHA-256 signature (`sid;rcode;txid;status;amount;currency;tx_action`).

• Successful payments finalize via `payment_complete(txid)`.
• Failed payments update the order to `failed` with a diagnostic message.

WooCommerce Blocks support

Blocks integration (`checkout.js`) registers Paywiser as a Blocks payment method with input handling and UI.

Technology Stack

• WordPress
• WooCommerce
• PHP (WooCommerce gateway implementation)
• JavaScript (Blocks checkout integration + input masking for hosted flow)
• Paywiser TxHandler + postback verification (Acquiring API)

Implementation Process

1. Model the redirect vs hosted flows and map them into WooCommerce status transitions.
2. Implement gateway settings and validation in wp-admin.
3. Implement TxHandler POST submission and request hashing.
4. Add verified postback handling (`/wc-api/pw-postback`) and return URL verification.
5. Integrate WooCommerce Blocks checkout and test end-to-end flows across both solutions.

Results & Impact

• WooCommerce merchants can enable Paywiser card payments with a predictable operational flow.
• Both redirect and hosted solutions are supported from one plugin.
• Server-side postbacks are verified before changing order state.
• Checkout remains compatible across WooCommerce legacy and Blocks experiences.

Reflection

Redirect-based payments only stay operable if the server-to-server postback is treated as the source of truth and is verified before changing order state. Building this in from the start prevents fraud-prone “status by URL parameter” behavior and reduces support load caused by ambiguous outcomes.

Summary

This plugin integrates Paywiser into WooCommerce with two supported payment modes, verified postback handling, and compatibility across both legacy and Blocks checkout flows.