cybersource-brunei-payauth 0.2.2 → 0.2.4

package/README.md

@@ -232,7 +232,7 @@ const outcome = await client.voidTransaction(paymentId, { reason: 'customer canc
 ```
 
 - **`operation: 'reversal'`** — the authorization hadn't been captured yet, so this released the hold via an authorization reversal (`POST /pts/v2/payments/{id}/reversals`). The reversed amount is read automatically from Cybersource's own record of the authorized amount, not re-derived or guessed.
-- **`operation: 'capture-void'`** — a capture already existed, so this voided *that* instead (`POST /pts/v2/captures/{id}/voids`). Cybersource typically batches captures to the processor once a day, so this only works same-day; after that, use a refund instead (not currently exposed by this package).
+- **`operation: 'capture-void'`** — a capture already existed, so this voided *that* instead (`POST /pts/v2/captures/{id}/voids`). Cybersource typically batches captures to the processor once a day, so this only works same-day; after that, use one of the refund methods below.
 
 `voidTransaction` assumes the only follow-on transaction it will ever see against one of its own authorizations is this package's own `capture()` call — if Cybersource reports *any* related transaction, it voids that one. If your integration creates other follow-on transactions against the same authorization outside this package (e.g. from the Cybersource Business Center), call the lower-level functions yourself instead:
 
@@ -244,7 +244,29 @@ await client.voidPayment(paymentId, { totalAmount, currency, reason, clientRefer
 await client.voidCapture(captureId, { clientReferenceCode });                                 // post-capture
 ```
 
-`voidPayment`'s `totalAmount`/`currency` must match the *authorized* amount from `authorize()`'s own response — not the amount you originally requested, which Cybersource notes can differ (e.g. partial approvals). It throws immediately, before any network call, if either is omitted, rather than sending Cybersource a request that would be declined anyway.
+`voidPayment`'s `totalAmount`/`currency` must match the *authorized* amount from `authorize()`'s own response — not the amount you originally requested, which Cybersource notes can differ (e.g. partial approvals). It throws immediately, before any network call, if either is omitted, rather than sending Cybersource a request that would be declined anyway.
+
+## Refunding a settled payment
+
+CyberSource provides two refund endpoints based on how the original payment was captured. Both methods support full or partial refunds; pass the amount to return, using the original transaction's currency:
+
+```js
+// Use only when authorization and capture were combined in the original POST /pts/v2/payments.
+await client.refundPayment(paymentId, {
+  totalAmount: '50.00',
+  currency: 'BND',
+  clientReferenceCode: 'refund-order-1', // optional
+});
+
+// Use when capture() was called separately. Pass capture()'s response id, not paymentId.
+await client.refundCapture(captureId, {
+  totalAmount: '20.00',
+  currency: 'BND',
+  clientReferenceCode: 'partial-refund-order-1', // optional
+});
+```
+
+`refundPayment` calls `POST /pts/v2/payments/{paymentId}/refunds`; `refundCapture` calls `POST /pts/v2/captures/{captureId}/refunds`. Both require `totalAmount` and `currency` and return CyberSource's response unchanged, including the refund transaction `id` and `status`.
 
 ### Plain-language status descriptions
 
@@ -263,7 +285,7 @@ describeStatus('PENDING_AUTHENTICATION');
 //  bank) before the charge can proceed."
 ```
 
-It covers every documented status value across `authorize()`, `capture()`, `voidPayment()`, and `voidCapture()`. `checkTransaction()`'s result already includes this as `statusDescription`, computed from its own `status` field. An unrecognized status (or `null`/missing) returns a safe fallback sentence rather than throwing — this is a plain-language convenience, not a validator.
+It covers every documented status value across `authorize()`, `capture()`, `voidPayment()`, `voidCapture()`, `refundPayment()`, and `refundCapture()`. `checkTransaction()`'s result already includes this as `statusDescription`, computed from its own `status` field. An unrecognized status (or `null`/missing) returns a safe fallback sentence rather than throwing — this is a plain-language convenience, not a validator.
 
 ## BIN Lookup
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cybersource-brunei-payauth",
-  "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.",
+  "version": "0.2.4",
+  "description": "Cybersource payer-authentication (3-D Secure) and payments client for Brunei merchants, including payment and capture refunds.",
   "main": "index.js",
   "files": [
     "index.js",

package/src/client.js

@@ -5,7 +5,14 @@ const {
   validateStepUp,
 } = require("./payerAuth");
 const { buildStepUpFormHtml } = require("./stepUpForm");
-const { authorize, capture, voidPayment, voidCapture } = require("./payments");
+const {
+  authorize,
+  capture,
+  voidPayment,
+  voidCapture,
+  refundPayment,
+  refundCapture,
+} = require("./payments");
 const { storeInstrument, getInstrument, deleteInstrument } = require("./tms");
 const { startPayment, finishPayment } = require("./facade");
 const { lookupBin } = require("./binLookup");
@@ -23,6 +30,8 @@ function createCyberSourceClient(config) {
     capture: (paymentId, payload) => capture(httpClient, paymentId, payload),
     voidPayment: (paymentId, payload) => voidPayment(httpClient, paymentId, payload),
     voidCapture: (captureId, payload) => voidCapture(httpClient, captureId, payload),
+    refundPayment: (paymentId, payload) => refundPayment(httpClient, paymentId, payload),
+    refundCapture: (captureId, payload) => refundCapture(httpClient, captureId, payload),
     storeInstrument: (payload) => storeInstrument(httpClient, payload),
     getInstrument: (payload) => getInstrument(httpClient, payload),
     deleteInstrument: (payload) => deleteInstrument(httpClient, payload),

package/src/httpClient.js

@@ -20,6 +20,43 @@ function createHttpClient({
     );
   }
 
+  function extractCybersourceError(parsed, status) {
+    if (parsed?.errorInformation) {
+      return {
+        reason: parsed.errorInformation.reason || "UNKNOWN_ERROR",
+
+        message:
+          parsed.errorInformation.message ||
+          `Cybersource request failed with status ${status}`,
+
+        details: {
+          ...parsed.errorInformation,
+          transactionId: parsed.id,
+          clientReferenceInformation: parsed.clientReferenceInformation,
+          status: parsed.status,
+          rawResponse: parsed,
+        },
+      };
+    }
+
+    if (parsed?.errors?.length) {
+      return {
+        reason: parsed.errors[0]?.reason || "UNKNOWN_ERROR",
+        message:
+          parsed.errors[0]?.message ||
+          `Cybersource request failed with status ${status}`,
+        details: parsed.errors,
+      };
+    }
+
+    return {
+      reason: parsed?.reason || "UNKNOWN_ERROR",
+      message:
+        parsed?.message || `Cybersource request failed with status ${status}`,
+      details: parsed?.details || parsed,
+    };
+  }
+
   async function request(method, path, body) {
     const date = new Date().toUTCString();
     const signatureHeaders = buildSignatureHeaders({
@@ -69,13 +106,13 @@ function createHttpClient({
     }
 
     if (!response.ok) {
+      const error = extractCybersourceError(parsed, response.status);
+
       throw new CyberSourceApiError({
         status: response.status,
-        reason: parsed.reason || "UNKNOWN_ERROR",
-        message:
-          parsed.message ||
-          `Cybersource request failed with status ${response.status}`,
-        details: parsed.details || parsed,
+        reason: error.reason,
+        message: error.message,
+        details: error.details,
       });
     }
 

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
@@ -228,9 +228,9 @@ async function voidPayment(
 // Reverses an already-settled capture (POST /pts/v2/captures/{id}/voids), before it reaches the
 // processor — Cybersource typically batches captures to the processor once a day, so this only
 // works same-day. Takes the capture()'s own id, not the original authorization's paymentId.
-async function voidCapture(
-  httpClient,
-  captureId,
+async function voidCapture(
+  httpClient,
+  captureId,
   { clientReferenceCode } = {},
 ) {
   assertSafeId(captureId, "captureId");
@@ -242,8 +242,57 @@ async function voidCapture(
         }
       : undefined,
   };
-
-  return httpClient.post(`/pts/v2/captures/${captureId}/voids`, body);
-}
-
-module.exports = { authorize, capture, voidPayment, voidCapture };
+
+  return httpClient.post(`/pts/v2/captures/${captureId}/voids`, body);
+}
+
+function buildRefundBody({ currency, totalAmount, clientReferenceCode } = {}) {
+  if (!totalAmount || !currency) {
+    throw new Error("Refund requires totalAmount and currency");
+  }
+
+  return {
+    clientReferenceInformation: clientReferenceCode
+      ? {
+          code: clientReferenceCode,
+        }
+      : undefined,
+
+    orderInformation: {
+      amountDetails: {
+        totalAmount,
+        currency,
+      },
+    },
+  };
+}
+
+// Use this only when authorization and capture were combined in authorize(). The id is the
+// payment id returned by that combined operation, as required by Cybersource's payment-scoped
+// refund endpoint.
+async function refundPayment(httpClient, paymentId, payload) {
+  assertSafeId(paymentId, "paymentId");
+  return httpClient.post(
+    `/pts/v2/payments/${paymentId}/refunds`,
+    buildRefundBody(payload),
+  );
+}
+
+// Use this when capture() was called separately. Cybersource requires the capture response's id,
+// not the original authorization's payment id, for this endpoint.
+async function refundCapture(httpClient, captureId, payload) {
+  assertSafeId(captureId, "captureId");
+  return httpClient.post(
+    `/pts/v2/captures/${captureId}/refunds`,
+    buildRefundBody(payload),
+  );
+}
+
+module.exports = {
+  authorize,
+  capture,
+  voidPayment,
+  voidCapture,
+  refundPayment,
+  refundCapture,
+};

package/src/statusDescriptions.js

@@ -1,7 +1,7 @@
 // Cybersource's own status vocabulary, spelled out in plain language for people who don't work
 // with payment processing day to day. Covers every status value documented for the response types
 // this package returns: authorize() (Payments API), capture(), voidPayment() (Authorization
-// Reversal), and voidCapture() (Capture Void).
+// Reversal), voidCapture() (Capture Void), refundPayment(), and refundCapture().
 const STATUS_DESCRIPTIONS = {
   AUTHORIZED:
     "The bank approved the charge. The money is held on the customer's card, but the merchant hasn't taken it yet — that happens on capture.",