Official Package

Payment

CanxJS's payment package provides a unified API for payment processing. It offers secure payment gateway integration with Midtrans (Indonesia's leading payment gateway). Built with security best practices.

Midtrans Snap

Full Snap API support for seamless checkout experience.

Secure Verification

SHA-512 signature with timing-safe comparison prevents attacks.

Zero Dependencies

Standalone driver with no core framework dependency required.

Environment Aware

Auto-switches between sandbox and production endpoints.

Installation

The payment module is an optional package to keep the core framework lightweight.

terminal

1npm install @canxjs/payment
2# or
3bun add @canxjs/payment

Configuration

Add your Midtrans credentials to your environment variables.

.env

1# .env
2MIDTRANS_SERVER_KEY=SB-Mid-server-xxxx
3MIDTRANS_CLIENT_KEY=SB-Mid-client-xxxx
4MIDTRANS_ENV=sandbox  # or 'production'

Creating a Checkout

Use the MidtransDriver to create a Snap checkout session.

controllers/CheckoutController.ts

1import { MidtransDriver } from '@canxjs/payment';
2
3export class CheckoutController {
4  
5  async create(req: Request) {
6    const driver = new MidtransDriver();
7    
8    const { url, id } = await driver.checkout({
9      amount: 150000,
10      currency: 'IDR',
11      successUrl: 'https://myshop.com/thankyou',
12      customer: req.user.email,
13      orderId: 'ORDER-001',
14      metadata: { 
15        items: [
16          { id: 'SKU-001', name: 'Product Name', price: 150000, quantity: 1 }
17        ] 
18      }
19    });
20    
21    // Redirect user to Midtrans payment page
22    return { redirect_url: url };
23  }
24}

Webhook Verification

Securely verify incoming webhooks using SHA-512 signature verification with timing-safe comparison.

controllers/WebhookController.ts

1import { MidtransDriver } from '@canxjs/payment';
2
3export class WebhookController {
4  
5  async handle(req: Request) {
6    const driver = new MidtransDriver();
7    const payload = await req.json();
8    
9    // 1. Verify Signature (SHA-512 with timing-safe comparison)
10    const isValid = await driver.verifySignature(payload);
11    if (!isValid) {
12      throw new Error("Invalid Signature");
13    }
14
15    // 2. Process based on status
16    const { order_id, transaction_status } = payload;
17    
18    switch (transaction_status) {
19      case 'capture':
20      case 'settlement':
21        await Order.markPaid(order_id);
22        break;
23      case 'pending':
24        // Waiting for payment
25        break;
26      case 'deny':
27      case 'cancel':
28      case 'expire':
29        await Order.markFailed(order_id);
30        break;
31    }
32    
33    return new Response('OK');
34  }
35}

Security Best Practices

✓Always verify webhooks — Never trust unverified payment notifications
✓Use HTTPS — Ensure your webhook endpoint uses HTTPS
✓Validate amounts — Cross-check amounts with your database
✓Handle idempotency — Webhooks may be sent multiple times

Next Steps

Explore other official packages to extend your CanxJS application.