From adbb89021b9dfcc931bbd9f1309a4b2aaac18b3f Mon Sep 17 00:00:00 2001
From: Allan Almeida <allan.almeida@immutable.com>
Date: Tue, 8 Sep 2026 14:23:15 +1000
Subject: [PATCH] fix(checkout): surface Transak order status on sale
 SALE_SUCCESS event
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sale widget card path emits SALE_SUCCESS as soon as Transak reports
PROCESSING (payment captured, mint not yet settled — typically a couple of
minutes). The host payload was {paymentMethod, transactions, tokenIds,
transactionId} with no field to tell PROCESSING from COMPLETED; the handler
already builds orderStatus but only forwarded transactionId.

Add an optional `status` field to the SaleSuccess event payload and thread the
Transak order status through sendSuccessEvent -> sendSaleSuccessEvent, so
integrators can distinguish a still-processing sale from a settled one and
reconcile settlement server-side using transactionId. Additive and backward
compatible (crypto payments, which settle synchronously, leave status undefined).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../checkout/sdk/src/widgets/definitions/events/sale.ts  | 9 +++++++++
 .../widgets-lib/src/widgets/sale/SaleWidgetEvents.ts     | 2 ++
 .../widgets-lib/src/widgets/sale/hooks/useSaleEvents.ts  | 1 +
 3 files changed, 12 insertions(+)

diff --git a/packages/checkout/sdk/src/widgets/definitions/events/sale.ts b/packages/checkout/sdk/src/widgets/definitions/events/sale.ts
index fd9648edff..857eacf0c9 100644
--- a/packages/checkout/sdk/src/widgets/definitions/events/sale.ts
+++ b/packages/checkout/sdk/src/widgets/definitions/events/sale.ts
@@ -33,6 +33,15 @@ export type SaleSuccess = {
   }[];
   /** The order reference id, use it to trace order throughout flow */
   transactionId: string;
+  /**
+   * Settlement status of the order. For card payments this mirrors the Transak
+   * order status: `'PROCESSING'` while the payment is captured but the mint is
+   * not yet settled (typically a couple of minutes), and `'COMPLETED'` once
+   * settled. Undefined for crypto payments, which settle on-chain synchronously.
+   * Do not treat the sale as final until settlement is confirmed — reconcile
+   * server-side using `transactionId`.
+   */
+  status?: string;
   [key: string]: unknown;
 };
 
diff --git a/packages/checkout/widgets-lib/src/widgets/sale/SaleWidgetEvents.ts b/packages/checkout/widgets-lib/src/widgets/sale/SaleWidgetEvents.ts
index fa5f0e65bb..a23d8f57a2 100644
--- a/packages/checkout/widgets-lib/src/widgets/sale/SaleWidgetEvents.ts
+++ b/packages/checkout/widgets-lib/src/widgets/sale/SaleWidgetEvents.ts
@@ -28,6 +28,7 @@ export const sendSaleSuccessEvent = (
   transactions: ExecutedTransaction[] = [],
   tokenIds: string[] = [],
   transactionId: string = '',
+  status?: string,
 ) => {
   const event = new CustomEvent<
   WidgetEvent<WidgetType.SALE, SaleEventType.SUCCESS>
@@ -39,6 +40,7 @@ export const sendSaleSuccessEvent = (
         transactions,
         tokenIds,
         transactionId,
+        status,
       },
     },
   });
diff --git a/packages/checkout/widgets-lib/src/widgets/sale/hooks/useSaleEvents.ts b/packages/checkout/widgets-lib/src/widgets/sale/hooks/useSaleEvents.ts
index ae1befee88..54e55dc028 100644
--- a/packages/checkout/widgets-lib/src/widgets/sale/hooks/useSaleEvents.ts
+++ b/packages/checkout/widgets-lib/src/widgets/sale/hooks/useSaleEvents.ts
@@ -90,6 +90,7 @@ export const useSaleEvent = () => {
       transactions,
       tokenIds,
       details.transactionId,
+      details.orderStatus,
     );
   };