LINE Pay Offline V4 Node.js SDK

Official LINE Pay Offline V4 API SDK for Node.js/Bun - Type-safe, zero dependencies, built on line-pay-core-v4.

Language / 語言 / 言語 / ภาษา: English | 繁體中文 | 日本語 | ไทย

Features

✅ Full Offline API v4 Support

• Payment Request (with oneTimeKey barcode)
• Check Payment Status
• Query Authorization Information
• Capture Payment
• Void Authorization
• Retrieve Payment Details
• Refund

✅ Type-Safe - Full TypeScript support with comprehensive type definitions
✅ Zero Dependencies - Only depends on line-pay-core-v4
✅ Modern - Built for Node.js 18+ and Bun
✅ Dual Package - ESM and CommonJS support
✅ 100% Test Coverage - Comprehensive test suite

Installation

npm install line-pay-offline-v4

or with Bun:

bun add line-pay-offline-v4

or with pnpm:

pnpm add line-pay-offline-v4

or with yarn:

yarn add line-pay-offline-v4

Quick Start

import { LinePayOfflineClient } from 'line-pay-offline-v4'

const client = new LinePayOfflineClient({
  channelId: process.env.LINE_PAY_CHANNEL_ID!,
  channelSecret: process.env.LINE_PAY_CHANNEL_SECRET!,
  merchantDeviceProfileId: 'POS-001',
  merchantDeviceType: 'POS',
  env: 'sandbox', // or 'production'
})

// Request payment with customer's barcode
const payment = await client.requestPayment({
  amount: 100,
  currency: 'TWD',
  oneTimeKey: '12345678901245678', // from customer's LINE Pay barcode
  orderId: 'ORDER-001',
})

console.log(payment.info.transactionId)

API Documentation

For detailed API documentation, see the doc directory.

Payment Request

const payment = await client.requestPayment({
  amount: 100,
  currency: 'TWD',
  oneTimeKey: '12345678901245678',
  orderId: 'ORDER-001',
  packages: [{
    id: 'PKG-001',
    amount: 100,
    products: [{
      name: 'Product Name',
      quantity: 1,
      price: 100
    }]
  }]
})

Check Payment Status

const status = await client.checkPaymentStatus('ORDER-001')
console.log(status.info.status) // 'COMPLETE' | 'FAIL' | 'REFUND'

Query Authorization Information

const auths = await client.queryAuthorizations({ orderId: 'ORDER-001' })
console.log(auths.info[0].payStatus) // 'AUTHORIZATION' | 'VOIDED_AUTHORIZATION'

Capture Payment

For separated authorization and capture flow:

const capture = await client.capturePayment('ORDER-001', {
  amount: 100,
  currency: 'TWD'
})

Void Authorization

Cancel authorized payment before capture:

await client.voidAuthorization('ORDER-001')

Retrieve Payment Details

const details = await client.retrievePaymentDetails({ orderId: 'ORDER-001' })
console.log(details.info[0])

Refund

// Full refund
await client.refundPayment('ORDER-001')

// Partial refund
await client.refundPayment('ORDER-001', {
  refundAmount: 50
})

Error Handling

import { 
  LinePayError, 
  LinePayTimeoutError,
  LinePayConfigError 
} from 'line-pay-offline-v4'

try {
  const payment = await client.requestPayment({...})
} catch (error) {
  if (error instanceof LinePayTimeoutError) {
    // Handle timeout - use checkPaymentStatus to verify
    const status = await client.checkPaymentStatus(orderId)
  } else if (error instanceof LinePayError) {
    console.error('LINE Pay Error:', error.returnCode, error.returnMessage)
    
    // Check error type
    if (error.isAuthError) {
      // Authentication/authorization error (1xxx)
    } else if (error.isPaymentError) {
      // Payment error (2xxx)
    } else if (error.isInternalError) {
      // Internal error (9xxx)
    }
  } else {
    console.error('Unknown error:', error)
  }
}

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | channelId | string | Yes | LINE Pay Channel ID | | channelSecret | string | Yes | LINE Pay Channel Secret | | merchantDeviceProfileId | string | Yes | Unique merchant device ID | | merchantDeviceType | string | No | Device type (default: "POS") | | env | 'production' | 'sandbox' | No | Environment (default: 'sandbox') | | timeout | number | No | Request timeout in ms (default: 20000) |

Security Best Practices

// ❌ DON'T: Hard-code secrets
const client = new LinePayOfflineClient({
  channelId: '1234567890',
  channelSecret: 'my-secret-key', // Never hard-code!
  merchantDeviceProfileId: 'POS-001'
})

// ✅ DO: Use environment variables
const client = new LinePayOfflineClient({
  channelId: process.env.LINE_PAY_CHANNEL_ID!,
  channelSecret: process.env.LINE_PAY_CHANNEL_SECRET!,
  merchantDeviceProfileId: process.env.MERCHANT_DEVICE_ID!
})

Contributing

See CONTRIBUTING.md for details.

License

MIT - see LICENSE for details.

Related Packages

• line-pay-core-v4 - Core utilities and base client
• line-pay-v4 - Online payment SDK