Vendure Midtrans Plugin

Plugin pembayaran Midtrans untuk Vendure e-commerce framework. Mendukung berbagai metode pembayaran populer di Indonesia menggunakan Midtrans Core API.

A Midtrans payment gateway plugin for Vendure e-commerce framework. Supports popular Indonesian payment methods using Midtrans Core API.

🚀 Features

• ✅ Bank Transfer - BCA, BNI, BRI, Permata, CIMB Virtual Account
• ✅ E-Wallet - GoPay, ShopeePay
• ✅ QRIS - Scannable by all Indonesian e-wallets
• ✅ Convenience Store - Alfamart, Indomaret
• ✅ Credit Card - With 3DS authentication
• ✅ Webhook Notifications - Automatic payment status updates
• ✅ Refund Support - Full and partial refunds
• ✅ TypeScript - Full type safety
• ✅ GraphQL API - Extended Shop and Admin APIs

📦 Installation

npm install vendure-plugin-midtrans
# or
yarn add vendure-plugin-midtrans
# or
pnpm add vendure-plugin-midtrans

🔧 Configuration

1. Register Plugin

Add the plugin to your Vendure config:

import { MidtransPlugin } from 'vendure-plugin-midtrans';
import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  // ... other config
  plugins: [
    MidtransPlugin.init({
      serverKey: process.env.MIDTRANS_SERVER_KEY!,
      clientKey: process.env.MIDTRANS_CLIENT_KEY!,
      isProduction: process.env.NODE_ENV === 'production',
      merchantId: process.env.MIDTRANS_MERCHANT_ID,
      enableLogging: true, // Enable for debugging
    }),
    // ... other plugins
  ],
};

2. Environment Variables

Add these to your .env file:

# Midtrans Sandbox (for testing)
MIDTRANS_SERVER_KEY=SB-Mid-server-xxxxxxxxxxxxx
MIDTRANS_CLIENT_KEY=SB-Mid-client-xxxxxxxxxxxxx
MIDTRANS_MERCHANT_ID=G123456789

# Midtrans Production
# MIDTRANS_SERVER_KEY=Mid-server-xxxxxxxxxxxxx
# MIDTRANS_CLIENT_KEY=Mid-client-xxxxxxxxxxxxx
# MIDTRANS_MERCHANT_ID=G123456789

Get your credentials from Midtrans Dashboard.

3. Create Payment Method

In Vendure Admin:

1. Go to Settings → Payment Methods
2. Click Create new payment method
3. Set:
   • Name: Midtrans
   • Code: midtrans
   • Handler: Select "Midtrans Payment Gateway"
4. Click Create

4. Configure Webhook

In Midtrans Dashboard:

1. Go to Settings → Configuration

2. Set Payment Notification URL to:

   https://your-domain.com/midtrans/webhook

3. Enable HTTP Notification

4. Save settings

💳 Usage Examples

Bank Transfer (Virtual Account)

// Frontend - Create payment with BCA Virtual Account
const result = await addPaymentToOrder({
  method: 'midtrans',
  metadata: {
    paymentType: 'bank_transfer',
    bank: 'bca', // bca, bni, bri, permata, cimb
  },
});

// Response will include VA number
console.log(result.metadata.vaNumbers);
// [{ bank: 'bca', vaNumber: '12345678901' }]

E-Wallet (GoPay)

const result = await addPaymentToOrder({
  method: 'midtrans',
  metadata: {
    paymentType: 'gopay',
  },
});

// Response includes deeplink for GoPay app
console.log(result.metadata.actions);
// [{ name: 'deeplink-redirect', url: 'gojek://...' }]

QRIS

const result = await addPaymentToOrder({
  method: 'midtrans',
  metadata: {
    paymentType: 'qris',
  },
});

// Response includes QR code string
console.log(result.metadata.qrString);
// Display as QR code for customer to scan

Convenience Store

const result = await addPaymentToOrder({
  method: 'midtrans',
  metadata: {
    paymentType: 'cstore',
    store: 'alfamart', // alfamart or indomaret
  },
});

// Response includes payment code
console.log(result.metadata.paymentCode);
// Customer brings this code to store

ShopeePay

const result = await addPaymentToOrder({
  method: 'midtrans',
  metadata: {
    paymentType: 'shopeepay',
  },
});

// Response includes deeplink
console.log(result.metadata.actions);

🔌 GraphQL API

Shop API

Query payment configuration:

query {
  midtransConfig {
    clientKey
    isProduction
    merchantId
  }
}

Get payment data for an order:

query {
  midtransPaymentData(orderCode: "ABC123") {
    paymentType
    transactionId
    transactionStatus
    vaNumbers {
      bank
      vaNumber
    }
    qrString
    paymentCode
    expiryTime
  }
}

Admin API

Get transaction status:

query {
  midtransTransactionStatus(transactionId: "xxx-xxx-xxx") {
    transactionStatus
    fraudStatus
    settlementTime
  }
}

Cancel transaction:

mutation {
  midtransCancelTransaction(transactionId: "xxx-xxx-xxx") {
    success
    message
  }
}

🔄 Payment Flow

1. Customer initiates payment → Frontend calls addPaymentToOrder with payment method metadata
2. Plugin creates charge → Calls Midtrans Core API to create transaction
3. Customer completes payment → Uses VA number, QR code, or deeplink
4. Midtrans sends webhook → Plugin receives notification at /midtrans/webhook
5. Payment settled → Order status automatically updated in Vendure

🛡️ Security

• Signature Verification: All webhooks are verified using SHA512 signature
• HTTPS Required: Webhook endpoint should use HTTPS in production
• Server Key Protection: Never expose server key to frontend

🧪 Testing

Use Midtrans Sandbox credentials for testing:

1. Get sandbox credentials from Midtrans Dashboard
2. Set isProduction: false in plugin config
3. Use test card numbers from Midtrans Docs

Test Cards

• Success: 4811 1111 1111 1114
• Failure: 4911 1111 1111 1113
• Challenge: 4411 1111 1111 1118

📚 API Reference

Plugin Options

interface MidtransPluginOptions {
  serverKey: string;        // Midtrans server key
  clientKey: string;        // Midtrans client key
  isProduction: boolean;    // Production mode flag
  merchantId?: string;      // Merchant ID (optional)
  webhookPath?: string;     // Webhook path (default: 'midtrans/webhook')
  enableLogging?: boolean;  // Enable debug logging (default: false)
}

Payment Metadata

interface PaymentMetadata {
  paymentType: 'bank_transfer' | 'echannel' | 'gopay' | 'shopeepay' | 'qris' | 'cstore' | 'credit_card';
  bank?: 'bca' | 'bni' | 'bri' | 'permata' | 'cimb';  // For bank_transfer
  store?: 'alfamart' | 'indomaret';                    // For cstore
}

🐛 Troubleshooting

Webhook not received

1. Check webhook URL is publicly accessible
2. Verify HTTPS is enabled
3. Check Midtrans Dashboard notification settings
4. Enable logging to see webhook requests

Payment not settling

1. Check webhook signature verification
2. Verify order code matches
3. Check payment state in Admin panel
4. Review logs for errors

TypeScript errors

Make sure you have @vendure/core installed as peer dependency:

npm install @vendure/core

📖 Resources

• Midtrans Documentation
• Vendure Documentation
• Midtrans Dashboard
• GitHub Repository

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details

💬 Support

• GitHub Issues: Report a bug
• Midtrans Support: [email protected]

🙏 Credits

Built with ❤️ for the Indonesian e-commerce community.

Note: This is an unofficial plugin and is not affiliated with Midtrans or Vendure.