Critical Update: Ensuring Accurate Refund Transactions in ESHOPMAN Order Cancellations

In the dynamic world of headless commerce, maintaining impeccable financial records is paramount. For ESHOPMAN merchants leveraging the power of HubSpot for storefront management and Node.js/TypeScript for their backend, accuracy in every transaction, especially refunds, is non-negotiable. Recently, a critical insight emerged from the ESHOPMAN community regarding a specific behavior in the platform's order cancellation workflow that could lead to discrepancies in recorded refund transactions.

The Challenge: Inaccurate Refund Bookings in ESHOPMAN

The core issue revolves around how ESHOPMAN handles order cancellations when a captured payment needs to be refunded. Ideally, if a merchant cancels an order, and a refund is initiated, the system should only record a refund transaction if the payment provider successfully processes the refund. However, a specific scenario revealed that ESHOPMAN's system might incorrectly book a refund transaction even if the external payment provider refuses the refund request.

This means an ESHOPMAN order could show a "refund -X" transaction, implying money was returned, when in reality, the payment provider never processed it. This discrepancy can lead to significant financial reporting inaccuracies for merchants, impacting reconciliation and overall business operations.

Understanding the ESHOPMAN Workflow Discrepancy

The detailed analysis by the ESHOPMAN community pinpointed the exact steps within the platform's core flows:

  • When an order is cancelled via the ESHOPMAN Admin API (e.g., POST /admin/orders/:id/cancel), the internal cancelOrderWorkflow is triggered.
  • This workflow, in turn, initiates the refundCapturedPaymentsWorkflow to process any captured payments associated with the order.
  • Within this refund process, the refundPaymentsStep attempts to call the integrated paymentModule.refundPayment for each payment.
  • The Critical Point: If the payment provider's refundPayment method throws an error (indicating a refusal or failure to process the refund), ESHOPMAN's system currently catches this error and only logs it. The refundPaymentsStep then proceeds, returning only the refunds that did succeed.
  • However, the subsequent refundPaymentsWorkflow, responsible for creating the order transaction data, builds this data from its initial input (the requested refund amounts) rather than from the actual successful refunds returned by the refundPaymentsStep.
  • Consequently, the addOrderTransactionStep books a refund transaction for the full amount, regardless of whether the payment provider actually returned the funds.

The only indication of a failed refund is a log entry and a soft-deleted refund row within the payment's records, which isn't immediately visible or reflected in the primary order transaction history.

Reproducing the Issue for ESHOPMAN Developers

For ESHOPMAN developers working with custom payment integrations, this issue can be reproduced by simulating a payment provider that explicitly refuses refunds. Here’s a conceptual example of such a provider's refundPayment method within an ESHOPMAN integration:

async refundPayment(input: RefundPaymentInput): Promise {
  throw new Error("Refunds are made in the provider's dashboard")
}

To observe this behavior:

  1. Register this custom payment provider within your ESHOPMAN instance.
  2. Place an order using this provider and authorize its payment.
  3. Capture the payment via the ESHOPMAN Admin API: POST /admin/payments/:id/capture.
  4. Then, attempt to cancel the order: POST /admin/orders/:id/cancel.
  5. You will notice the order is marked 'canceled', and a refund transaction is booked, despite the provider's refusal.

Proposed Solutions and ESHOPMAN's Commitment to Accuracy

The ESHOPMAN team and community members have proposed two main approaches to resolve this critical issue:

  • Option 1: Fail the Cancellation: If a refund of a captured payment fails, the entire order cancellation workflow should fail and compensate, preventing the order from being marked as cancelled with an unfulfilled refund.
  • Option 2: Conditional Transaction Booking: The orderTransactionData should be built strictly from the refunds that actually succeeded, ensuring that no refund transaction is booked for amounts that were never returned by the payment provider.

This discussion highlights ESHOPMAN's dedication to robust financial integrity and transparent development. The team is actively addressing this to ensure that all financial records within ESHOPMAN accurately reflect real-world transactions, providing merchants with reliable data for their headless commerce operations.

We encourage ESHOPMAN developers and merchants to stay informed on these updates and contribute to our growing community knowledge base. Your insights are invaluable!

Start with the tools

Explore migration tools

See options, compare methods, and pick the path that fits your store.

Explore migration tools