ECPay Payment SDK for Node.js

English | 繁體中文

Unofficial ECPay Payment SDK for Node.js, built with Bun, supporting both ESM and CJS.

Features

• 🚀 Full TypeScript support
• 📦 Supports both ESM and CommonJS
• 🔒 Built-in CheckMacValue calculation and verification
• 🛠 Provides FormBuilder for quick payment form generation

Installation

npm install ecpay-payment-node
# or
yarn add ecpay-payment-node
# or
pnpm add ecpay-payment-node
# or
bun add ecpay-payment-node

Usage

1. Credit Card Payment (One-Time)

import { CreditPayment, FormBuilder } from 'ecpay-payment-node'

// 1. Initialize
const payment = new CreditPayment('2000132', '5294y06JbISpM5x9', 'v77hoKGq4kWxNNIS')

// 2. Set Parameters
payment
  .setMerchantTradeNo('Credit' + Date.now())
  .setMerchantTradeDate(new Date())
  .setTotalAmount(1000)
  .setTradeDesc('Test Transaction')
  .setItemName('Item A x 1')
  .setReturnURL('https://example.com/return')
  // Optional
  .setClientBackURL('https://example.com/client-back')
  .setNeedExtraPaidInfo('Y')

// 3. Generate HTML Form
const builder = new FormBuilder()
const html = builder.build(payment)

2. Credit Card Installment

import { CreditInstallment, FormBuilder } from 'ecpay-payment-node'

const payment = new CreditInstallment('2000132', '5294y06JbISpM5x9', 'v77hoKGq4kWxNNIS')
payment.setMerchantTradeNo('Inst' + Date.now())
       .setTotalAmount(3000)
       .setTradeDesc('Installment Test')
       .setItemName('Expensive Item x 1')
       .setReturnURL('https://example.com/return')
       // Set Installment Period (3, 6, 12, 18, 24)
       .setCreditInstallment('3')

const html = new FormBuilder().build(payment)

3. Credit Card Recurring (Subscription)

💡 Use Case: Subscription services, regular donations, membership fees.

import { CreditRecurring, FormBuilder, PeriodType } from 'ecpay-payment-node'

const payment = new CreditRecurring('2000132', '5294y06JbISpM5x9', 'v77hoKGq4kWxNNIS')
payment.setMerchantTradeNo('Rec' + Date.now())
       .setTotalAmount(99) // First authorization amount (usually same as period amount)
       .setTradeDesc('Subscription Service')
       .setItemName('Monthly Membership')
       .setReturnURL('https://example.com/return') // Callbak for initial authorization
       // Recurring Parameters (Required)
       .setPeriodAmount(99)        // Amount per charge
       .setPeriodType(PeriodType.Month) // Cycle unit (Year, Month, Day)
       .setFrequency(1)            // Frequency (Every 1 Month)
       .setExecTimes(12)           // Total executions (12 times)
       .setPeriodReturnURL('https://example.com/period-return') // Callback for each recurring charge

const html = new FormBuilder().build(payment)

Parameter Details:

| Method | Description | Example | | :--- | :--- | :--- | | setPeriodAmount | Period AmountThe amount to be charged for each period. | 99 | | setPeriodType | Cycle UnitUnit of the recurring cycle.- PeriodType.Day- PeriodType.Month- PeriodType.Year | PeriodType.Month | | setFrequency | FrequencyInterval of the cycle.e.g., if Type is Month and Frequency is 1, it means "Every 1 Month". | 1 | | setExecTimes | Execution TimesTotal number of times to charge.e.g., 12 means charge 12 times in total. | 12 | | setPeriodReturnURL| Recurring Callback URLServer URL notified by ECPay after each successful recurring charge. | https://... |

4. ATM (Virtual Account)

import { AtmPayment, FormBuilder } from 'ecpay-payment-node'

const payment = new AtmPayment('2000132', '5294y06JbISpM5x9', 'v77hoKGq4kWxNNIS')
payment.setMerchantTradeNo('ATM' + Date.now())
       .setTotalAmount(500)
       .setTradeDesc('ATM Test')
       .setItemName('Transfer Item')
       .setReturnURL('https://example.com/return')
       // ATM Specifics
       .setExpireDate(3) // Expires in 3 days
       .setPaymentInfoURL('https://example.com/payment-info') // Server webhook

const html = new FormBuilder().build(payment)

5. CVS (Convenience Store Code)

import { CvsPayment, FormBuilder } from 'ecpay-payment-node'

const payment = new CvsPayment('2000132', '5294y06JbISpM5x9', 'v77hoKGq4kWxNNIS')
payment.setMerchantTradeNo('CVS' + Date.now())
       .setTotalAmount(200)
       .setTradeDesc('CVS Test')
       .setItemName('CVS Item')
       .setReturnURL('https://example.com/return')
       // CVS Specifics
       .setStoreExpireDate(10080) // Minutes (7 days)
       .setPaymentInfoURL('https://example.com/payment-info')

const html = new FormBuilder().build(payment)

6. Apple Pay

import { ApplePayPayment, FormBuilder } from 'ecpay-payment-node'

const payment = new ApplePayPayment(merchantID, hashKey, hashIV)
payment.setMerchantTradeNo('Apple' + Date.now())
       .setTotalAmount(1000)
       .setTradeDesc('Apple Pay Test')
       .setItemName('IPhone Case')
       .setReturnURL('https://example.com/return')

const builder = new FormBuilder()
const html = builder.build(payment)

Verify Notification

import { PaymentNotify } from 'ecpay-payment-node'

const notify = new PaymentNotify(hashKey, hashIV)
const data = { /* Parameters returned by ECPay */ }

if (notify.verify(data)) {
  console.log('Verification Successful')
  // Process order...
}

Order Query

import { QueryOrder, EcPayClient } from 'ecpay-payment-node'

const client = new EcPayClient(merchantID, hashKey, hashIV)
const query = new QueryOrder(merchantID, hashKey, hashIV)
query.setMerchantTradeNo('Test123456')

const result = await client.query(query)
console.log(result)

Development

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

License

MIT © 2024 Carl Lee