medusa-payment-windcave

Windcave payment provider for MedusaJS v2. Integrates Windcave's Drop-in payment solution with your Medusa e-commerce store.

Features

• Windcave Drop-in (Hosted Payment Page) integration
• PCI SAQ-A compliant
• Supports credit/debit cards, Apple Pay, Google Pay
• Full payment lifecycle: authorize, capture, cancel, refund
• Webhook support for payment notifications
• Sandbox and production environments

Installation

npm install medusa-payment-windcave

Configuration

Add the provider to your medusa-config.ts:

module.exports = {
  // ... other config
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "medusa-payment-windcave",
            id: "windcave",
            options: {
              apiUsername: process.env.WINDCAVE_API_USERNAME,
              apiKey: process.env.WINDCAVE_API_KEY,
              sandbox: process.env.NODE_ENV !== "production",
            },
          },
        ],
      },
    },
  ],
};

Environment Variables

WINDCAVE_API_USERNAME=your_api_username
WINDCAVE_API_KEY=your_api_key

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiUsername | string | Yes | Windcave REST API username | | apiKey | string | Yes | Windcave REST API key | | sandbox | boolean | No | Use sandbox environment (default: false) | | defaultCurrency | string | No | Default currency code (e.g., "NZD") | | merchantName | string | No | Merchant name for mobile wallets |

Frontend Integration

1. Initiate Payment Session

When the customer proceeds to checkout, Medusa creates a payment session. The session data includes Windcave's sessionLinks needed for the Drop-in.

2. Load Windcave Drop-in

Add the Windcave JavaScript SDK to your storefront:

<script src="https://sec.windcave.com/js/windcavepayments-dropin-v1.js"></script>

3. Create the Drop-in

// Get payment session from Medusa API
const paymentSession = await medusa.carts.createPaymentSessions(cartId);
const windcaveSession = paymentSession.payment_session;

// Create Drop-in
const dropIn = WindcavePayments.DropIn.create({
  container: "payment-container",
  links: windcaveSession.data.sessionLinks,
  totalValue: windcaveSession.data.amount,
  onSuccess: function(status) {
    if (status === "Done") {
      // Complete checkout via Medusa
      completeCheckout();
    }
  },
  onError: function(stage, error) {
    console.error("Payment failed:", stage, error);
  }
});

4. Complete Checkout

After successful payment, complete the order through Medusa:

async function completeCheckout() {
  // Authorize the payment
  await medusa.carts.authorizePaymentSession(cartId, {
    provider_id: "windcave"
  });

  // Complete the order
  const order = await medusa.carts.complete(cartId);
}

Webhooks

Configure your Windcave notification URL to:

https://your-store.com/hooks/payment/windcave

The provider handles webhook notifications automatically to update payment status.

API Reference

Payment Data Structure

The payment session data contains:

{
  sessionId: string;        // Windcave session ID
  sessionLinks: Array<{     // Links for Drop-in SDK
    href: string;
    rel: string;
    method: string;
  }>;
  amount: string;           // Payment amount
  currency: string;         // Currency code
  merchantReference: string; // Unique reference
  transactionId?: string;   // Set after authorization
  status?: string;          // Payment status
}

Testing

Use Windcave's test credentials in sandbox mode:

• Sandbox URL: https://uat.windcave.com
• Test Cards: See Windcave Test Cards

Resources

• Windcave Drop-in Documentation
• Windcave REST API
• MedusaJS Payment Providers

License

MIT