Flex Microform v2 — card data is tokenized directly at CyberSource; it never touches your server
Device Fingerprint (ThreatMetrix) — fraud scoring via device profiling before payment
Authorization + manual capture from the Medusa admin dashboard
Auto-capture (sale mode) for instant settlement
Partial and full refunds
Zero-amount orders — 100% discounts and free orders are handled automatically (no gateway call)
Admin widget — CyberSource transaction details panel injected into order detail view

Requirements


Medusa.js	v2 ()
Node.js	18+
CyberSource	Business Center account

Installation

npm install medusa-payment-cybersource

Environment Variables

Add these to your :

1CYBERSOURCE_MERCHANT_ID=your_merchant_id
2CYBERSOURCE_KEY_ID=your_shared_key_id
3CYBERSOURCE_SECRET_KEY=your_shared_secret_key
4CYBERSOURCE_ENV=sandbox           # or "production"
5CYBERSOURCE_AUTO_CAPTURE=false    # set to "true" for sale/auto-capture mode

Where to find these values: CyberSource Business Center → Account Management → Transaction Security Keys → Security Keys for the HTTP Signature Security Policy

Configuration

In , add the plugin to both (for the API route) and (for the payment provider):

1import { loadEnv, defineConfig } from "@medusajs/framework/utils"
2
3loadEnv(process.env.NODE_ENV || "development", process.cwd())
4
5module.exports = defineConfig({
plugins: [
  // Required: registers the built-in /store/cybersource/authorize route
  { resolve: "medusa-payment-cybersource" },
],
projectConfig: {
  // ... your existing config
},
modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "medusa-payment-cybersource",
          id: "cybersource",
          options: {
            merchantID: process.env.CYBERSOURCE_MERCHANT_ID,
            merchantKeyId: process.env.CYBERSOURCE_KEY_ID,
            merchantsecretKey: process.env.CYBERSOURCE_SECRET_KEY,
            environment:
              process.env.CYBERSOURCE_ENV === "production"
                ? "production"
                : "sandbox",
            capture: process.env.CYBERSOURCE_AUTO_CAPTURE === "true",
          },
        },
      ],
    },
  },
],
36})

Plugin Options

Option	Type	Description
		Required. Your CyberSource Merchant ID
		Required. Shared key ID (HTTP Signature)
		Required. Shared secret key (HTTP Signature)
		or . Default:
		Auto-capture on authorization (sale mode). Default:
		Card networks for Flex. Default:

Payment Flow

1Storefront          Backend            CyberSource
  |                  |                    |
  | select method    |                    |
  |----------------->|                    |
  |                  |-- /flex/v2/sessions-->|
  |<-- captureContext JWT ----------------|
  |                  |                    |
  | Flex iFrames render (SAQ-A)          |
  | Fingerprint script loads in bg       |
  |                  |                    |
  | microform.createToken()              |
  |----------------------------------------->|
  |<-- transient_token (JWT 15 min) ---------|
  |                  |                    |
  | POST /store/cybersource/authorize    |
  |  { payment_session_id,              |
  |    transient_token,                 |
  |    fingerprint_session_id }         |
  |----------------->|                    |
  |                  |-- /pts/v2/payments-->|
  |                  |  + deviceInformation |
  |                  |<-- AUTHORIZED --------|
  |<-- { cs_payment_id } -------------|
  |                  |                    |
  | POST /store/carts/:id/complete   |
  |----------------->|                    |
  |                  | authorizePayment() |
  |                  | reads cs_payment_id|
  |<-- order created--|                    |

Frontend Integration

1. Load Flex Microform

<script src="https://flex.cybersource.com/microform/bundle/v2/flex-microform.min.js"></script>

2. Load Device Fingerprint Script

When the user selects CyberSource as payment method, generate a unique session ID and load the ThreatMetrix script. The same ID must be sent in the authorize request.

1const fingerprintSessionId = crypto.randomUUID()
2
3const script = document.createElement("script")
4script.src = `https://h.online-metrix.net/fp/tags.js?org_id=${ORG_ID}&session_id=${fingerprintSessionId}`
5script.async = true
6document.head.appendChild(script)
7
8// org_id values:
9// Sandbox:    1snn5n9w
10// Production: k8vif92e  (confirm in Business Center → Decision Manager)

3. Initialize Flex

1// captureContext comes from payment_session.data.captureContext
2const flex = new Flex(captureContext)
3const microform = flex.microform()
4
5const cardNumber = microform.createField("number", { placeholder: "Card number" })
6const cvn = microform.createField("securityCode", { placeholder: "CVV" })
7
8cardNumber.load("#card-number-container")
9cvn.load("#cvn-container")

4. Tokenize and Pre-authorize

Call this before :

1async function authorizePayment(paymentSessionId, fingerprintSessionId) {
// 1. Get transient token from Flex Microform
const transientToken = await new Promise((resolve, reject) => {
  microform.createToken({ expirationMonth: "12", expirationYear: "2030" }, (err, token) => {
    if (err) reject(err)
    else resolve(token)
  })
})
9
// 2. Pre-authorize at CyberSource via the built-in plugin route
const response = await fetch("/store/cybersource/authorize", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-publishable-api-key": YOUR_PUBLISHABLE_API_KEY,
  },
  body: JSON.stringify({
    payment_session_id: paymentSessionId,
    transient_token: transientToken,
    fingerprint_session_id: fingerprintSessionId,  // same UUID used in the script URL
    bill_to: {               // optional but recommended
      firstName: "John",
      lastName: "Doe",
      email: "john@example.com",
      address1: "123 Main St",
      locality: "Guatemala City",
      administrativeArea: "Guatemala",
      postalCode: "01001",
      country: "GT",
    },
  }),
})
33
const result = await response.json()
35
if (!response.ok) {
  throw new Error(result.message || "Payment declined")
}
39
return result // { success: true, cs_payment_id, cs_status }
41}
42
43// Usage
44await authorizePayment(
cart.payment_collection.payment_sessions[0].id,
fingerprintSessionId,
47)
48await placeOrder() // Medusa completes the order using the stored cs_payment_id

— Request / Response

Request body:

Field	Required	Description
	Yes	Medusa payment session ID
	Yes	JWT from
	No	Session ID used in the ThreatMetrix script URL
	No	Billing address object for AVS/fraud checks

Success response (200):

{ "success": true, "cs_payment_id": "7278957202756800104005", "cs_status": "AUTHORIZED" }

Declined response (402):

{ "error": "Payment declined", "reason": "INSUFFICIENT_FUND", "cs_status": "DECLINED" }

Device Fingerprint

The plugin sends and to the CyberSource Payments API. The flag is required so that CyberSource looks up ThreatMetrix using the raw session ID (your UUID) instead of the default composite key — which would cause a mismatch with what the frontend script registered.

You can verify fingerprint collection is working by checking a transaction in CyberSource Business Center. A successful integration shows a hash under Device Fingerprint ID instead of "Not Submitted".

Capture Modes

Manual Capture (default)

CyberSource authorizes the card on order placement. You capture the funds from the Medusa Admin → Orders → Payment panel. Authorization expires in 5–7 days if not captured.

Auto-Capture (sale mode)

Set . CyberSource processes authorization and capture together; the payment is marked as captured immediately on order placement.

The plugin injects a CyberSource panel into the order detail page of the Medusa admin (). It shows:

Field	Description
Status badge	Derived display status (see table below)
Transaction ID	CyberSource authorization ID
Capture ID	Only shown if different from Transaction ID (manual capture)
Reconciliation ID	CyberSource reconciliation ID
Card	Card brand + last 4 digits
Last Refund ID	ID of the last refund issued
Last Refund Amount	Amount of the last refund

Status badge logic:

Condition	Badge
is set	🔵 REFUNDED
+ set (auto-capture)	🟢 CAPTURED
(no capture ID)	🟠 AUTHORIZED
	🟢 CAPTURED
	⚫ VOIDED
	🔴 DECLINED

Admin Refund Route

Medusa's default refund UI has a validation that can block refunds in some edge cases. Add this route to your Medusa store for a direct refund bypass:

Create in your Medusa project:

1import { MedusaRequest, MedusaResponse } from "@medusajs/framework"
2import { Modules } from "@medusajs/framework/utils"
3
4type RefundRequestBody = {
5  payment_id: string
6  amount?: number
7  note?: string
8}
9
10export const POST = async (
11  req: MedusaRequest<RefundRequestBody>,
12  res: MedusaResponse
13) => {
14  const { payment_id, amount, note } = req.body
15
16  if (!payment_id) {
17    return res.status(400).json({ error: "payment_id is required" })
18  }
19
20  const paymentModule = req.scope.resolve(Modules.PAYMENT)
21
22  const payments = await paymentModule.listPayments(
23    { id: [payment_id] },
24    { relations: ["captures", "refunds"] }
25  )
26  const payment = payments[0]
27
28  if (!payment) {
29    return res.status(404).json({ error: "Payment not found" })
30  }
31
32  const captured = (payment.captures ?? []).reduce(
33    (sum: number, c: any) => sum + Number(c.amount ?? 0),
34    0
35  )
36  const alreadyRefunded = (payment.refunds ?? []).reduce(
37    (sum: number, r: any) => sum + Number(r.amount ?? 0),
38    0
39  )
40  const refundable = captured - alreadyRefunded
41
42  if (refundable <= 0) {
43    return res.status(400).json({ error: "No capturable amount available to refund" })
44  }
45
46  const refundAmount = amount ?? refundable
47
48  if (refundAmount > refundable) {
49    return res.status(400).json({
50      error: `Cannot refund ${refundAmount}. Maximum refundable: ${refundable}`,
51    })
52  }
53
54  const updatedPayment = await paymentModule.refundPayment({
55    payment_id,
56    amount: refundAmount,
57    created_by: (req as any).auth_context?.actor_id,
58    note,
59  })
60
61  return res.json({ payment: updatedPayment })
62}

Call it from your admin UI or custom dashboard:

1curl -X POST http://localhost:9000/admin/cybersource/refund \
-H "Authorization: Bearer <admin_token>" \
-H "Content-Type: application/json" \
-d '{ "payment_id": "pay_01...", "amount": 50.00 }'

Development

1# Clone
2git clone https://github.com/Eleven-Estudio/medusa-payment-cybersource.git
3cd medusa-payment-cybersource
4
5# Install dependencies
6npm install
7
8# Build
9npm run build
10
11# Watch mode (backend only)
12npm run dev

Linking to a local Medusa store with yalc

1# In the plugin directory
2npm run build
3npx yalc push
4
5# In your Medusa store directory
6npx yalc add medusa-payment-cybersource
7npx medusa develop