PayWay Cambodia SDK

Official Node.js SDK for PayWay Cambodia Payment Gateway API.

Features

• ✅ QR Code Payment Generation
• ✅ Web Purchase (Checkout Page)
• ✅ Payment Link Creation
• ✅ Transaction Detail Retrieval
• ✅ Transaction List (Filtered & Paginated)
• ✅ Check Transaction (Quick Status)
• ✅ Refund (Full & Partial)
• ✅ Exchange Rate Fetching
• ✅ Close/Cancel Transactions
• ✅ Hash Calculation Utilities
• ✅ Full TypeScript Support
• ✅ Sandbox Mode for Testing
• 🤖 AI Agent Skills for Claude, Copilot, Cursor & more

Installation

npm install aba-payway-sdk

🤖 Install AI Agent Skills (Optional)

Enhance your AI coding assistant with PayWay SDK knowledge:

# Install skill for your preferred AI agent
npx aba-payway-sdk skills add claude

# Supported agents: claude, cursor, copilot, codex, opencode
npx aba-payway-sdk skills add claude cursor copilot

# List installed skills
npx aba-payway-sdk skills list

After installing, your AI assistant (GitHub Copilot, Claude, Cursor, etc.) will provide accurate PayWay integration code suggestions, best practices, and troubleshooting help.

Quick Start

const { PayWayClient } = require('aba-payway-sdk');

// Initialize with credentials
const payway = new PayWayClient({
  merchantId: 'your-merchant-id',
  apiKey: 'your-api-key',
  baseUrl: 'https://api.payway.com.kh'
});

// Generate QR code
const response = await payway.createQR({
  amount: 10,
  currency: 'USD',
  customerInfo: {
    email: '[email protected]',
    phone: '012345678'
  }
});

console.log('QR Image:', response.qrImage);
console.log('Transaction ID:', response.status.tran_id);

API Reference

Create QR Code

Generate a QR code for payment:

const result = await payway.createQR({
  amount: 10.50,
  currency: 'USD',
  items: [
    { name: 'Item 1', quantity: 1, price: 10.50 }
  ],
  payer: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    phone: '012345678'
  },
  callbackUrl: 'https://example.com/callback'
});

Get Transaction Detail

Retrieve transaction details including status and history:

const details = await payway.getTransactionDetail({
  tranId: '17394277693'
});

console.log('Payment Status:', details.data.payment_status);
console.log('Amount:', details.data.payment_amount);
console.log('Bank Reference:', details.data.bank_ref);

// Check status
if (details.data.payment_status === 'APPROVED') {
  console.log('Payment confirmed!');
}

Payment Status Values:

• APPROVED - Payment completed successfully
• PRE-AUTH - Payment held under pre-authorization
• PENDING - Awaiting completion
• DECLINED - Payment declined
• REFUNDED - Payment refunded
• CANCELLED - Transaction cancelled

Note: Limited to 10 requests per minute. Does not support real-time status checks during payment processing.

Create Purchase (Web Checkout)

Create a web-based purchase that redirects customers to PayWay's checkout page:

const purchaseData = await payway.createPurchase({
  amount: 25.00,
  currency: 'USD',
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]',
  phone: '012345678',
  items: [
    { name: 'Premium Plan', quantity: 1, price: 25.00 }
  ],
  tranId: 'ORDER-12345',
  continueSuccessUrl: 'https://yoursite.com/success',
  returnUrl: 'https://yoursite.com/return',
  callbackUrl: 'https://yoursite.com/api/webhook'
});

// Redirect user to checkout
console.log('Checkout URL:', purchaseData.checkout_url);
// Or use the form HTML
console.log('Form HTML:', purchaseData.form_html);

Key Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | amount | number | Yes | Transaction amount | | currency | string | No | 'USD' or 'KHR' (default: 'USD') | | firstName | string | Yes | Customer first name | | lastName | string | Yes | Customer last name | | email | string | Yes | Customer email | | phone | string | Yes | Customer phone number | | items | array | No | List of items being purchased | | tranId | string | No | Custom transaction ID (auto-generated if not provided) | | continueSuccessUrl | string | Yes | URL to redirect after successful payment | | returnUrl | string | No | URL when customer cancels/returns | | callbackUrl | string | No | Webhook URL for payment notifications |

Use Cases:

• E-commerce checkout pages
• Subscription payments
• Online services
• Digital products
• Any scenario requiring full web checkout

Create Payment Link

Create a shareable payment link that customers can use to pay:

const paymentLink = await payway.createPaymentLink({
  title: 'Product Purchase',
  amount: 50.00,
  currency: 'USD',
  description: 'Premium subscription',
  payment_limit: 10, // Max 10 payments allowed
  expired_date: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
  return_url: 'https://example.com/payment-callback',
  merchant_ref_no: 'LINK-001'
});

console.log('Payment Link:', paymentLink.data.payment_link);
console.log('Link ID:', paymentLink.data.id);
console.log('Status:', paymentLink.data.status); // OPEN

Key Features:

• Shareable payment URLs
• Multiple payment methods (cards, KHQR, wallets)
• Optional image upload (max 3MB)
• Payment limits and expiration dates
• Payout split for marketplaces
• Requires: RSA public key encryption

Close Transaction

Cancel a pending transaction:

const result = await payway.closeTransaction({
  tranId: 'ORDER-12345'
});

if (result.status.code === '00') {
  console.log('Transaction cancelled successfully');
}

Response Codes:

• 00 - Success (transaction cancelled)
• 1 - Wrong hash (authentication failed)
• 5 - Transaction not found
• 26 - Invalid merchant

🤖 AI Agent Skills

Supercharge your development workflow! Install PayWay SDK knowledge for your AI coding assistant:

# Install for your AI agent
npx aba-payway-sdk skills add claude

# Supported agents
npx aba-payway-sdk skills add claude cursor copilot codex opencode

What you get:

• ✅ Accurate code suggestions for PayWay integration
• ✅ Built-in best practices and security patterns
• ✅ Context-aware error handling examples
• ✅ Real-world integration patterns

Example: After installing the skill, ask your AI assistant:

"Create a PayWay QR code for a $50 payment"

Your AI will generate complete, production-ready code with proper error handling and security best practices.

CLI Commands:

aba-payway-sdk skills add <agent>     # Install skill
aba-payway-sdk skills list             # List installed
aba-payway-sdk skills remove <agent>   # Remove skill
aba-payway-sdk skills help             # Show help

Links

• GitHub: https://github.com/seabnavin19/payway-sdk
• npm: https://www.npmjs.com/package/aba-payway-sdk
• Issues: https://github.com/seabnavin19/payway-sdk/issues

License

MIT