medusa-payment-kadima 0.1.0 → 0.1.2

package/.medusa/server/src/{chunk-MKSGS2DZ.js → chunk-KVJTOLRY.js}

@@ -2,7 +2,7 @@ import {
   CARD_HOSTS,
   DASHBOARD_HOSTS,
   verifySignature
-} from "./chunk-A4QO3PSZ.js";
+} from "./chunk-RPREKUY6.js";
 
 // src/providers/kadima-card.ts
 import { AbstractPaymentProvider, BigNumber } from "@medusajs/framework/utils";
@@ -284,6 +284,10 @@ var KadimaCardProviderService = class extends AbstractPaymentProvider {
     this.options_ = options;
     this.client = new KadimaCardClient(options);
     this.vault = new KadimaVaultClient(options);
+    const sb = !!options.sandbox;
+    console.info(
+      `[kadima-card] init \u2014 sandbox=${sb} \xB7 gateway=${sb ? CARD_HOSTS.sandbox : CARD_HOSTS.prod} \xB7 dashboard=${sb ? DASHBOARD_HOSTS.sandbox : DASHBOARD_HOSTS.prod} \xB7 terminal=${options.terminalId ?? "(unset)"} \xB7 token=${options.apiToken ? "set" : "MISSING"}`
+    );
   }
   /**
    * No money moves. Mint a Hosted Fields token so the storefront can collect the

package/.medusa/server/src/{chunk-R62JQB26.js → chunk-UO5EBYD2.js}

@@ -1,7 +1,7 @@
 import {
   DASHBOARD_HOSTS,
   verifySignature
-} from "./chunk-A4QO3PSZ.js";
+} from "./chunk-RPREKUY6.js";
 
 // src/providers/kadima-ach.ts
 import { AbstractPaymentProvider } from "@medusajs/framework/utils";
@@ -90,6 +90,10 @@ var KadimaAchProviderService = class extends AbstractPaymentProvider {
     super(container, options);
     this.options_ = options;
     this.client = new KadimaAchClient(options);
+    const sb = !!options.sandbox;
+    console.info(
+      `[kadima-ach] init \u2014 sandbox=${sb} \xB7 host=${sb ? DASHBOARD_HOSTS.sandbox : DASHBOARD_HOSTS.prod}/api/ach \xB7 dba=${options.dbaId ?? "(unset)"} \xB7 token=${options.apiToken ? "set" : "MISSING"}`
+    );
   }
   async initiatePayment(input) {
     return {

package/.medusa/server/src/index.d.ts

@@ -21,7 +21,9 @@ import './types-BUuMxNOL.js';
  *               terminalId: Number(process.env.KADIMA_TERMINAL_ID),
  *               webhookSecret: process.env.KADIMA_WEBHOOK_SECRET,
  *               captureMethod: "auth",      // or "sale"
- *               sandbox: process.env.NODE_ENV !== "production",
+ *               // Set explicitly — NODE_ENV is "production" on most hosts, which
+ *               // would silently send sandbox creds to the LIVE host (→ 401).
+ *               sandbox: process.env.KADIMA_SANDBOX === "true",
  *             },
  *           },
  *           {
@@ -32,6 +34,7 @@ import './types-BUuMxNOL.js';
  *               dbaId: Number(process.env.KADIMA_DBA_ID),
  *               webhookSecret: process.env.KADIMA_WEBHOOK_SECRET,
  *               secCode: "WEB",
+ *               sandbox: process.env.KADIMA_SANDBOX === "true",
  *             },
  *           },
  *         ],

package/.medusa/server/src/index.js

@@ -1,10 +1,10 @@
 import {
   kadima_ach_default
-} from "./chunk-R62JQB26.js";
+} from "./chunk-UO5EBYD2.js";
 import {
   kadima_card_default
-} from "./chunk-MKSGS2DZ.js";
-import "./chunk-A4QO3PSZ.js";
+} from "./chunk-KVJTOLRY.js";
+import "./chunk-RPREKUY6.js";
 
 // src/index.ts
 import { ModuleProvider, Modules } from "@medusajs/framework/utils";

package/.medusa/server/src/providers/kadima-ach.js

@@ -1,7 +1,7 @@
 import {
   kadima_ach_default
-} from "../chunk-R62JQB26.js";
-import "../chunk-A4QO3PSZ.js";
+} from "../chunk-UO5EBYD2.js";
+import "../chunk-RPREKUY6.js";
 export {
   kadima_ach_default as default
 };

package/.medusa/server/src/providers/kadima-card.js

@@ -1,7 +1,7 @@
 import {
   kadima_card_default
-} from "../chunk-MKSGS2DZ.js";
-import "../chunk-A4QO3PSZ.js";
+} from "../chunk-KVJTOLRY.js";
+import "../chunk-RPREKUY6.js";
 export {
   kadima_card_default as default
 };

package/README.md

@@ -38,7 +38,7 @@ module.exports = defineConfig({
               dbaId: Number(process.env.KADIMA_DBA_ID), // for saved cards
               webhookSecret: process.env.KADIMA_WEBHOOK_SECRET,
               captureMethod: "auth", // or "sale"
-              sandbox: process.env.NODE_ENV !== "production",
+              sandbox: process.env.KADIMA_SANDBOX === "true",
             },
           },
           {
@@ -49,7 +49,7 @@ module.exports = defineConfig({
               dbaId: Number(process.env.KADIMA_DBA_ID),
               webhookSecret: process.env.KADIMA_WEBHOOK_SECRET,
               secCode: "WEB",
-              sandbox: process.env.NODE_ENV !== "production",
+              sandbox: process.env.KADIMA_SANDBOX === "true",
             },
           },
         ],
@@ -59,6 +59,24 @@ module.exports = defineConfig({
 })
 ```
 
+> ⚠️ **Set `sandbox` explicitly — do not derive it from `NODE_ENV`.** Most hosting
+> platforms (Railway, Render, Vercel, Heroku, Fly) set `NODE_ENV=production`, so
+> `NODE_ENV !== "production"` silently evaluates to `false` and your test build hits
+> the **live** Kadima hosts with sandbox credentials → `HTTP 401: invalid credentials`.
+> While testing, set `KADIMA_SANDBOX=true` in your env; unset it (or `false`) for production.
+> `sandbox: true` uses `sandbox.kadimadashboard.com` / `sandbox-gateway.kadimadashboard.com`;
+> `false` uses the live hosts. The token, terminal ID and DBA ID must come from the
+> **same** environment as the flag (a sandbox token on a live host, or vice-versa, is a 401).
+
+On startup each provider logs its resolved configuration so mismatches are obvious, e.g.:
+
+```
+[kadima-card] init — sandbox=true · gateway=https://sandbox-gateway.kadimadashboard.com · dashboard=https://sandbox.kadimadashboard.com · terminal=404 · token=set
+```
+
+If you see `token=MISSING`, the env var isn't set in your deployment. If `sandbox` or the
+host is wrong for your token, fix the flag and redeploy.
+
 Enable the providers in your sales channel / region, point your Kadima webhook at
 `https://<your-store>/hooks/payment/kadima-card` (and `/kadima-ach`), and add the
 storefront components from [`storefront/`](./storefront/README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-payment-kadima",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Medusa v2 payment provider for Kadima — direct card + ACH, no middle gateway",
   "license": "MIT",
   "private": false,
@@ -26,20 +26,22 @@
   "exports": {
     ".": {
       "types": "./.medusa/server/src/index.d.ts",
-      "import": "./.medusa/server/src/index.js"
+      "import": "./.medusa/server/src/index.js",
+      "default": "./.medusa/server/src/index.js"
     },
     "./providers/kadima-card": {
       "types": "./.medusa/server/src/providers/kadima-card.d.ts",
-      "import": "./.medusa/server/src/providers/kadima-card.js"
+      "import": "./.medusa/server/src/providers/kadima-card.js",
+      "default": "./.medusa/server/src/providers/kadima-card.js"
     },
     "./providers/kadima-ach": {
       "types": "./.medusa/server/src/providers/kadima-ach.d.ts",
-      "import": "./.medusa/server/src/providers/kadima-ach.js"
+      "import": "./.medusa/server/src/providers/kadima-ach.js",
+      "default": "./.medusa/server/src/providers/kadima-ach.js"
     }
   },
   "files": [
     ".medusa/server",
-    "src",
     "storefront",
     "README.md"
   ],

package/src/index.ts

@@ -1,43 +0,0 @@
-import { ModuleProvider, Modules } from "@medusajs/framework/utils"
-import KadimaCardProviderService from "./providers/kadima-card"
-import KadimaAchProviderService from "./providers/kadima-ach"
-
-/**
- * Registers BOTH providers under the Payment module. In medusa-config.ts:
- *
- *   modules: [
- *     {
- *       resolve: "@medusajs/medusa/payment",
- *       options: {
- *         providers: [
- *           {
- *             resolve: "medusa-payment-kadima/providers/kadima-card",
- *             id: "kadima-card",
- *             options: {
- *               apiToken: process.env.KADIMA_CARD_TOKEN,
- *               terminalId: Number(process.env.KADIMA_TERMINAL_ID),
- *               webhookSecret: process.env.KADIMA_WEBHOOK_SECRET,
- *               captureMethod: "auth",      // or "sale"
- *               sandbox: process.env.NODE_ENV !== "production",
- *             },
- *           },
- *           {
- *             resolve: "medusa-payment-kadima/providers/kadima-ach",
- *             id: "kadima-ach",
- *             options: {
- *               apiToken: process.env.KADIMA_ACH_TOKEN,
- *               dbaId: Number(process.env.KADIMA_DBA_ID),
- *               webhookSecret: process.env.KADIMA_WEBHOOK_SECRET,
- *               secCode: "WEB",
- *             },
- *           },
- *         ],
- *       },
- *     },
- *   ]
- */
-export default ModuleProvider(Modules.PAYMENT, {
-  services: [KadimaCardProviderService, KadimaAchProviderService],
-})
-
-export { KadimaCardProviderService, KadimaAchProviderService }

package/src/lib/errors.ts

@@ -1,46 +0,0 @@
-import { KadimaTxnStatus } from "../types"
-
-/**
- * Kadima returns a rich set of decline reasons (see docs/2-Payment Gateway API.pdf).
- * We surface the raw reason but classify a few that Medusa / the storefront should
- * treat specially (retryable vs hard decline vs needs-action).
- */
-export class KadimaError extends Error {
-  constructor(
-    message: string,
-    readonly status: KadimaTxnStatus,
-    readonly reason?: string | null,
-    readonly raw?: unknown
-  ) {
-    super(message)
-    this.name = "KadimaError"
-  }
-}
-
-const RETRYABLE = new Set([
-  "Time out",
-  "System Error",
-  "Error on Host",
-  "Host connectivity failed",
-  "Issuer or Switch inoperative",
-  "Functionality currently not available",
-])
-
-export function isRetryable(reason?: string): boolean {
-  return reason ? RETRYABLE.has(reason) : false
-}
-
-/** Throw if Kadima did not approve. */
-export function assertApproved(resp: {
-  status?: { status?: KadimaTxnStatus; reason?: string | null }
-}): void {
-  const s = resp.status?.status
-  if (s !== "Approved") {
-    throw new KadimaError(
-      `Kadima transaction ${s ?? "Error"}: ${resp.status?.reason ?? "unknown"}`,
-      s ?? "Error",
-      resp.status?.reason,
-      resp
-    )
-  }
-}

package/src/lib/kadima-ach-client.ts

@@ -1,166 +0,0 @@
-import { DASHBOARD_HOSTS, KadimaAchOptions } from "../types"
-
-/**
- * Client over the Kadima ACH API (kadimadashboard.com/api/ach).
- *
- * Verified against Kadima_Dashboard_API_COMPLETE.md:
- *   POST   /api/ach                      create a Debit/Credit (returns { id })
- *   GET    /api/ach/<id>                  view a transaction
- *   POST   /api/ach/<id>/<action>        void | cancel | verify
- *   POST   /api/ach/customer             create a vault customer
- *   POST   /api/ach/customer/<id>/account add a bank account to a customer
- *
- * ACH is ASYNCHRONOUS: create returns status Pending; settlement (`Settled`) or
- * failure (`Returned`) arrive later via the ach/updateStatus webhook. So a debit
- * create means "submitted", not "captured".
- *
- * Request field names are exact and case-sensitive: `SECCode`, `transactionType`,
- * `accountName`, `accountNumber`, `routingNumber`, `accountType`, `dba.id`.
- */
-export class KadimaAchClient {
-  private readonly base: string
-
-  constructor(private readonly opts: KadimaAchOptions) {
-    this.base = `${opts.sandbox ? DASHBOARD_HOSTS.sandbox : DASHBOARD_HOSTS.prod}/api/ach`
-  }
-
-  // Create returns { id }. NOTE: id is a string in the minimal response but
-  // numeric in the save-customer response — treat it as string | number.
-  /** Create a debit. Returns the new ACH transaction id. */
-  async debit(input: AchTxnInput): Promise<{ id: string | number }> {
-    return this.request(this.base, "POST", this.buildBody(input, "Debit"))
-  }
-
-  /** Offsetting credit — refunds a settled debit (PPD/CCD only). */
-  async credit(input: AchTxnInput): Promise<{ id: string | number }> {
-    return this.request(this.base, "POST", this.buildBody(input, "Credit"))
-  }
-
-  /** void | cancel | verify  (void only while Held/Pending/Submitted). */
-  async action(id: string | number, action: "void" | "cancel" | "verify") {
-    return this.request(`${this.base}/${id}/${action}`, "POST")
-  }
-
-  async get(id: string | number): Promise<KadimaAchTxn> {
-    return this.request(`${this.base}/${id}`, "GET")
-  }
-
-  // --- Customer Vault ------------------------------------------------------
-  async createCustomer(data: Record<string, unknown>): Promise<{ id: string }> {
-    return this.request(`${this.base}/customer`, "POST", data)
-  }
-  async addAccount(customerId: string | number, account: Record<string, unknown>) {
-    return this.request(`${this.base}/customer/${customerId}/account`, "POST", account)
-  }
-
-  private buildBody(input: AchTxnInput, transactionType: "Debit" | "Credit") {
-    const body: Record<string, unknown> = {
-      amount: input.amount,
-      transactionType,
-      SECCode: input.secCode ?? this.opts.secCode ?? "WEB",
-      dba: { id: this.opts.dbaId },
-      ...(input.tax != null ? { tax: input.tax } : {}),
-      ...(input.memo ? { memo: input.memo } : {}),
-      ...(input.addendaText ? { addendaText: input.addendaText } : {}),
-    }
-
-    if (input.customerId) {
-      // Existing vault customer (+ optional specific saved account).
-      body.customer = { id: input.customerId }
-      if (input.accountId) body.account = { id: input.accountId }
-    } else {
-      // New inline bank account. Bank fields are TOP-LEVEL, not nested.
-      body.accountName = input.accountName
-      body.accountNumber = input.accountNumber
-      body.routingNumber = input.routingNumber
-      body.accountType = input.accountType ?? "Checking"
-      body.customer = {
-        ...(input.saveCustomer ? { save: "Yes" } : {}),
-        ...input.customer,
-      }
-    }
-    return body
-  }
-
-  private async request<T = any>(
-    url: string,
-    method: "POST" | "GET",
-    body?: unknown
-  ): Promise<T> {
-    const resp = await fetch(url, {
-      method,
-      headers: {
-        Authorization: `Bearer ${this.opts.apiToken}`,
-        "Content-Type": "application/json",
-      },
-      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
-    })
-    const text = await resp.text()
-    const json = text ? JSON.parse(text) : {}
-    if (!resp.ok) {
-      const msg = (json as any)?.message ?? text
-      throw new Error(`Kadima ACH HTTP ${resp.status}: ${msg}`)
-    }
-    return json as T
-  }
-}
-
-export interface AchTxnInput {
-  amount: number
-  tax?: number
-  secCode?: "PPD" | "CCD" | "WEB" | "TEL"
-  memo?: string
-  addendaText?: string
-  // Either an existing vault customer ...
-  customerId?: string | number
-  accountId?: string | number
-  // ... or a new inline bank account (top-level fields) + customer details.
-  accountName?: string
-  accountNumber?: string
-  routingNumber?: string
-  accountType?: "Checking" | "Savings"
-  saveCustomer?: boolean // customer.save = "Yes"
-  customer?: {
-    firstName?: string
-    lastName?: string
-    email?: string
-    phone?: string
-    address1?: string
-    address2?: string
-    city?: string
-    state?: string
-    zipCode?: string
-    identifier?: string // merchant-side unique id for the payer
-    sendReceipt?: "Yes" | "No"
-  }
-}
-
-/** ACH transaction object (List/View/webhook achObject). */
-export interface KadimaAchTxn {
-  id: number | string
-  amount: string
-  tax?: string
-  SECCode?: "PPD" | "CCD" | "WEB" | "TEL"
-  accountName?: string
-  accountNumber?: string
-  accountType?: "Checking" | "Savings"
-  routingNumber?: string
-  transactionType?: "Debit" | "Credit"
-  transactionStatus?: KadimaAchStatus
-  dba?: { id: number; name?: string }
-  customer?: { id?: string | null; identifier?: string | null; email?: string | null }
-  verification?: { status?: string; date?: string | null }
-  return?: { code?: string | null; date?: string | null }
-  source?: string
-  createdOn?: string
-  updatedOn?: string
-}
-
-export type KadimaAchStatus =
-  | "Voided"
-  | "Hold"
-  | "Pending"
-  | "Submitted"
-  | "Transmitted"
-  | "Settled"
-  | "Returned"