boyonglin/shopline-payments-skill
shopline-payments
VerifiedUSE WHEN: 用戶詢問 SHOPLINE Payments 金流串接、導轉式付款流程、建立結帳交易(sessionUrl)、 returnUrl 回跳處理、Webhook 簽章驗證、交易查詢、退款/請款/取消操作, 或整合 LINE Pay、信用卡、ATM、街口支付(JKO)等台灣在地付款方式。 DO NOT USE WHEN: 詢問其他金流服務(如綠界 ECPay、藍新 NewebPay、TapPay)、 非台灣地區金流、或 SHOPLINE 電商平台非金流相關功能。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.3 KB |
| references/capture-cancel.md | markdown | 8.5 KB |
| references/embedded.md | markdown | 8.4 KB |
| references/error-codes.md | markdown | 14.0 KB |
| references/payment-methods.md | markdown | 1.5 KB |
| references/query.md | markdown | 4.8 KB |
| references/redirect.md | markdown | 10.8 KB |
| references/refund.md | markdown | 5.1 KB |
| references/sandbox.md | markdown | 4.6 KB |
| references/webhook.md | markdown | 9.0 KB |
| scripts/checkout.js | script | 7.6 KB |
| scripts/gas-integration.js | script | 12.2 KB |
| scripts/webhook.js | script | 7.0 KB |
scripts/checkout.js
View on GitHub/**
* SHOPLINE Payments - Checkout Session
* Node.js 建立結帳交易完整範例
*/
const fetch = require('node-fetch');
// 環境設定
const CONFIG = {
sandbox: {
baseUrl: 'https://api-sandbox.shoplinepayments.com',
merchantId: process.env.SHOPLINE_MERCHANT_ID,
apiKey: process.env.SHOPLINE_API_KEY
},
production: {
baseUrl: 'https://api.shoplinepayments.com',
merchantId: process.env.SHOPLINE_MERCHANT_ID,
apiKey: process.env.SHOPLINE_API_KEY
}
};
/**
* 建立結帳交易
* @param {Object} orderData - 訂單資料
* @param {string} env - 環境:'sandbox' 或 'production'
* @returns {Promise<Object>} - 結帳交易回應
*/
async function createCheckoutSession(orderData, env = 'sandbox') {
const config = CONFIG[env];
const url = `${config.baseUrl}/api/v1/trade/sessions/create`;
const requestId = `REQ-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
// 建構請求電文
const payload = {
referenceId: orderData.orderId,
language: orderData.language || 'zh-TW',
amount: {
value: Math.round(orderData.amount * 100), // 轉換為分
currency: 'TWD'
},
expireTime: orderData.expireTime || 360, // 預設 360 分鐘
returnUrl: orderData.returnUrl,
mode: 'regular',
allowPaymentMethodList: orderData.paymentMethods || ['CreditCard', 'LinePay'],
paymentMethodOptions: buildPaymentMethodOptions(orderData),
order: buildOrderInfo(orderData),
customer: buildCustomerInfo(orderData),
billing: buildBillingInfo(orderData),
client: {
ip: orderData.clientIp || '127.0.0.1',
userAgent: orderData.userAgent || 'Node.js',
language: orderData.language || 'zh-TW'
}
};
try {
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'merchantId': config.merchantId,
'apiKey': config.apiKey,
'requestId': requestId
},
body: JSON.stringify(payload)
});
const result = await response.json();
if (!response.ok) {
throw new ShoplinePaymentError(result.code, result.msg, result);
}
return {
success: true,
sessionId: result.sessionId,
referenceId: result.referenceId,
status: result.status,
sessionUrl: result.sessionUrl,
createTime: result.createTime
};
} catch (error) {
if (error instanceof ShoplinePaymentError) {
throw error;
}
throw new Error(`Network error: ${error.message}`);
}
}
/**
* 建構付款方式選項
*/
function buildPaymentMethodOptions(orderData) {
const options = {};
// 信用卡分期設定
if (orderData.paymentMethods?.includes('CreditCard')) {
options.CreditCard = {
installmentCounts: orderData.installments || ['0']
};
}
// ATM 虛擬帳號期限
if (orderData.paymentMethods?.includes('VirtualAccount')) {
options.VirtualAccount = {
// 預設 1440 分鐘(1 天),可依需求調整
paymentExpireTime: orderData.atmExpireTime || 1440
};
}
// 街口支付期限
if (orderData.paymentMethods?.includes('JKOPay')) {
options.JKOPay = {
// 預設 120 分鐘,可依需求調整
paymentExpireTime: orderData.jkoExpireTime || 120
};
}
// 中租 BNPL 設定
if (orderData.paymentMethods?.includes('ChaileaseBNPL')) {
options.ChaileaseBNPL = {
installmentCounts: orderData.bnplInstallments || ['3', '6', '12'],
// 預設 120 分鐘,可依需求調整
paymentExpireTime: orderData.bnplExpireTime || 120
};
}
return options;
}
/**
* 建構訂單資訊
*/
function buildOrderInfo(orderData) {
const order = {};
// 商品資訊
if (orderData.products && orderData.products.length > 0) {
order.products = orderData.products.map(product => ({
id: product.id,
name: product.name,
quantity: product.quantity || 1,
amount: {
value: Math.round(product.price * 100),
currency: 'TWD'
},
sku: product.sku,
desc: product.description,
url: product.url
}));
}
// 配送資訊
if (orderData.shipping) {
order.shipping = {
shippingMethod: orderData.shipping.method || '宅配',
carrier: orderData.shipping.carrier,
personalInfo: {
firstName: orderData.shipping.name,
email: orderData.shipping.email,
phone: orderData.shipping.phone
},
address: {
countryCode: 'TW',
city: orderData.shipping.city,
district: orderData.shipping.district,
street: orderData.shipping.address,
postcode: orderData.shipping.postcode
}
};
}
return order;
}
/**
* 建構顧客資訊
*/
function buildCustomerInfo(orderData) {
if (!orderData.customer) {
throw new Error('customer 未提供');
}
// 拆分姓名為 firstName 和 lastName
const { firstName, lastName } = splitName(orderData.customer.name);
return {
referenceCustomerId: orderData.customer.id,
type: orderData.customer.type || '0', // 0: 個人, 1: 公司
personalInfo: {
firstName: firstName,
lastName: lastName,
email: orderData.customer.email,
phone: orderData.customer.phone
}
};
}
/**
* 建構帳單資訊
*/
function buildBillingInfo(orderData) {
// 若未提供 billing,則使用 customer 資訊
const billingData = orderData.billing || orderData.customer;
if (!billingData) {
throw new Error('billing 或 customer 未提供');
}
const { firstName, lastName } = splitName(billingData.name);
return {
personalInfo: {
firstName: firstName,
lastName: lastName,
email: billingData.email,
phone: billingData.phone
}
};
}
/**
* 拆分中文姓名為姓和名
* 預設第一個字為姓,其餘為名
*/
function splitName(fullName) {
if (!fullName) {
return { firstName: '', lastName: '' };
}
const name = fullName.trim();
if (name.length <= 1) {
return { firstName: name, lastName: name };
}
return {
lastName: name.substring(0, 1), // 姓
firstName: name.substring(1) // 名
};
}
/**
* 自訂錯誤類別
*/
class ShoplinePaymentError extends Error {
constructor(code, message, response) {
super(message);
this.name = 'ShoplinePaymentError';
this.code = code;
this.response = response;
}
}
// ============= 使用範例 =============
async function example() {
try {
const result = await createCheckoutSession({
orderId: `ORDER-${Date.now()}`,
amount: 1000, // NT$1000
returnUrl: 'https://your-domain.com/payment/return',
paymentMethods: ['CreditCard', 'LinePay', 'VirtualAccount'],
installments: ['0', '3', '6', '12'],
customer: {
id: 'CUST-001',
name: '王小明',
email: 'customer@example.com',
phone: '+886912345678'
},
products: [{
id: 'PROD-001',
name: '測試商品',
price: 1000,
quantity: 1
}],
shipping: {
name: '王小明',
phone: '+886912345678',
city: '台北市',
district: '松山區',
address: '敦化北路170號10樓',
postcode: '105405'
},
clientIp: '127.0.0.1'
}, 'sandbox');
console.log('結帳交易建立成功!');
console.log('Session ID:', result.sessionId);
console.log('付款頁面 URL:', result.sessionUrl);
console.log('請將顧客導轉至付款頁面');
} catch (error) {
if (error instanceof ShoplinePaymentError) {
console.error(`SHOPLINE 錯誤 [${error.code}]: ${error.message}`);
} else {
console.error('錯誤:', error.message);
}
}
}
// 執行範例
// example();
module.exports = {
createCheckoutSession,
ShoplinePaymentError
};
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |