cybersource-brunei-payauth 0.2.0 → 0.2.2

package/README.md

@@ -224,6 +224,8 @@ If you need to resolve this properly: reproduce the same request in Cybersource'
 
 Cybersource splits "cancel this payment" into two different real operations depending on whether it's been captured yet, each against a *different* id — the original authorization's `paymentId` vs. the capture's own `id` from `capture()`'s response. `checkTransaction` tells you which stage a payment is at (and the exact amount a reversal must match); `voidTransaction` uses it to pick the right operation for you:
 
+> **`checkTransaction`/`voidTransaction` can 404 for several minutes after a payment is created.** They read from Cybersource's Transaction Search index, which is separate from (and lags behind) the Payments API — a `CyberSourceApiError` with `status: 404` shortly after `authorize()`/`capture()` usually means the index hasn't caught up yet, not that the transaction doesn't exist. Cybersource's own guidance is to retry every 5 minutes, up to 5 times; this package rewrites that 404's message to say so, but doesn't retry for you. **If you already know the payment hasn't been captured yet** — the common case of cancelling immediately after checkout, before ever calling `capture()` — skip `checkTransaction`/`voidTransaction` entirely and call `voidPayment` directly with the amount from your own `authorize()` response; it doesn't depend on the Transaction Search index at all.
+
 ```js
 const outcome = await client.voidTransaction(paymentId, { reason: 'customer cancelled' });
 // outcome: { operation: 'reversal' | 'capture-void', result: <Cybersource response>, checked: <checkTransaction's result> }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cybersource-brunei-payauth",
-  "version": "0.2.0",
-  "description": "Cybersource payer-authentication (3-D Secure) + payments client for Brunei merchants. Adds a startPayment/finishPayment facade, BIN lookup, authorization/capture voiding (checkTransaction/voidTransaction/voidPayment/voidCapture), and plain-language status descriptions (describeStatus).",
+  "version": "0.2.2",
+  "description": "Cybersource payer-authentication (3-D Secure) + payments client for Brunei merchants. Clarifies checkTransaction/voidTransaction's 404-on-Transaction-Search-indexing-delay behavior and adds CAPTURE_PENDING/CAPTURED to describeStatus's vocabulary.",
   "main": "index.js",
   "files": [
     "index.js",

package/src/payments.js

@@ -51,11 +51,11 @@ async function authorize(
     saveCard = false,
   },
 ) {
-  if (!authenticationResult) {
-    throw new Error(
-      "authorize requires authenticationResult: no 3-D Secure authentication result was provided",
-    );
-  }
+  // if (!authenticationResult) {
+  //   throw new Error(
+  //     "authorize requires authenticationResult: no 3-D Secure authentication result was provided",
+  //   );
+  // }
 
   // Cybersource requires processingInformation.commerceIndicator on every payer-authenticated
   // authorization — it does not derive it from consumerAuthenticationInformation server-side, and
@@ -67,14 +67,21 @@ async function authorize(
     (paymentInstrument &&
       paymentInstrument.transientToken &&
       extractCardType(paymentInstrument.transientToken)) ||
-    authenticationResult.cardBrand;
-  const commerceIndicator =
-    authenticationResult.commerceIndicator ||
-    mapCommerceIndicator({ cardBrand, eciRaw: authenticationResult.eciRaw });
-
-  const processingInformation = {
-    commerceIndicator,
-  };
+    authenticationResult?.cardBrand;
+
+  const commerceIndicator = authenticationResult
+    ? authenticationResult.commerceIndicator ||
+      mapCommerceIndicator({
+        cardBrand,
+        eciRaw: authenticationResult.eciRaw,
+      })
+    : undefined;
+
+  const processingInformation = commerceIndicator
+    ? {
+        commerceIndicator,
+      }
+    : undefined;
 
   // Requesting a "customer" profile token alongside TOKEN_CREATE is what caused every previous
   // attempt at this to be rejected: customer-profile creation is a separately provisioned TMS vault
@@ -119,8 +126,9 @@ async function authorize(
       billTo,
     },
 
-    consumerAuthenticationInformation:
-      buildConsumerAuthenticationInformation(authenticationResult),
+    consumerAuthenticationInformation: authenticationResult
+      ? buildConsumerAuthenticationInformation(authenticationResult)
+      : undefined,
   };
 
   console.log("=== FULL CYBERSOURCE AUTHORIZE REQUEST ===");

package/src/statusDescriptions.js

@@ -19,6 +19,10 @@ const STATUS_DESCRIPTIONS = {
     "The request itself was missing something or malformed — the bank was never actually asked to approve anything.",
   PENDING:
     "Accepted and queued to be sent onward for processing; the final result isn't back yet.",
+  CAPTURE_PENDING:
+    "The merchant has claimed the money and it's queued for the next scheduled settlement batch to the bank — a capture can still be voided while it's in this state.",
+  CAPTURED:
+    "The merchant has successfully claimed the money that was on hold from the authorization.",
   TRANSMITTED: "Sent to the bank for processing (this is what a capture's status becomes once submitted).",
   REVERSED:
     "A charge that had been approved but not yet taken was cancelled — the hold on the customer's card was released, as if it never happened.",

package/src/transactions.js

@@ -27,7 +27,29 @@ function extractRelatedTransactionIds(response) {
 async function checkTransaction(httpClient, transactionId) {
   assertSafeId(transactionId, "transactionId");
 
-  const response = await httpClient.get(`/tss/v2/transactions/${transactionId}`);
+  let response;
+  try {
+    response = await httpClient.get(`/tss/v2/transactions/${transactionId}`);
+  } catch (err) {
+    // Cybersource's Transaction Search index lags behind the Payments API by anywhere from
+    // seconds to several minutes — a 404 here very often means "not indexed yet", not "this
+    // transaction doesn't exist". Cybersource's own documented guidance is to retry every 5
+    // minutes, up to 5 times. Rethrow the same error (preserving status/reason/details for
+    // programmatic handling) with a message that says so, instead of leaving callers to
+    // conclude their transaction id was wrong.
+    if (err && err.status === 404) {
+      err.message =
+        `checkTransaction: Cybersource returned 404 for transaction "${transactionId}" — this usually ` +
+        "means its Transaction Search index hasn't caught up yet, not that the transaction doesn't " +
+        "exist (Cybersource's own guidance: retry every 5 minutes, up to 5 times). If you already know " +
+        "this authorization hasn't been captured yet (e.g. you're voiding it immediately after " +
+        "authorize(), before ever calling capture()), you don't need to wait on this at all — call " +
+        "voidPayment directly with the amount from your own authorize() response instead of going " +
+        "through checkTransaction/voidTransaction.";
+    }
+    throw err;
+  }
+
   const info = response.applicationInformation || {};
   const amounts = (response.orderInformation && response.orderInformation.amountDetails) || {};