JavaScript SDK（FastStar.js）

FastStar.js 是零依赖、单文件的浏览器端 SDK（UMD）。它以居中弹层打开托管收银台，让买家无需离开你的网站，并提供安全的加卡弹层把卡片保存到卡库。

引入 SDK

在页面底部引入脚本，或放在 <head> 中并加 defer：

<script src="https://cashier.faststarpay.com/sdk/v1/faststar.min.js" defer></script>

SDK 通过 UMD 包装同样支持 CommonJS/AMD 环境（require('./faststar.js')）。 FastStar.init() 可省略——直接调用 FastStar.checkout.open() 时会用默认配置自动初始化。

子资源完整性（SRI）

SDK 部署在带版本号的路径下（/sdk/v1/）。如安全策略需要，可用 SRI 固定校验文件内容：对你核验过的文件计算哈希（例如 openssl dgst -sha384 -binary faststar.min.js | openssl base64 -A），再给 script 标签加上 integrity="sha384-..." 与 crossorigin="anonymous"。每次升级 SDK 版本后需重新生成哈希。

域名固定与白名单

自 v1.1.0 起，收银台域名固定为 https://cashier.faststarpay.com，无需也不可配置。可配置的 baseUrl 会成为钓鱼 / 弹层劫持面：任何页面都能把貌似 FastStar 的弹层指向任意域名。

同理，FastStar.checkout.open({ url }) 只接受平台白名单域的 URL——https://cashier.faststarpay.com 与 https://merchant.faststarpay.com，其他 URL 一律拒绝。仅允许 http(s) 协议，javascript: 等伪协议无法注入。

打开收银台

推荐走 Checkout Session：服务端凭 API Key 创建会话，把会话 url 下发给浏览器：

// presentation: 'iframe' —— SDK 弹层（买家不离开你的网站）
FastStar.checkout.open({ url: data.url });

// presentation: 'link' —— 整页跳转
window.location.href = data.url;

也支持支付链接，可传完整 URL 或仅传 id：

// 完整支付链接 URL
FastStar.checkout.open({ url: 'https://cashier.faststarpay.com/pay/plink_abc123' });

// 仅传 linkId —— SDK 自动拼接为 {收银台域}/pay/{linkId}
FastStar.checkout.open({ linkId: 'plink_abc123' });

SDK 会创建全屏半透明遮罩 + 居中 iframe 弹层（收银台 URL 自动附加 embedded=1 参数），带关闭按钮、点击遮罩空白处或按 ESC 关闭、纯 CSS 加载动画，移动端（宽度 ≤ 640px）自动全屏。可调用 FastStar.checkout.close() 手动关闭。

事件

结算页通过 postMessage 把结果回传给你的页面，SDK 已封装为事件：

事件	触发时机	data 示例
`checkout.success`	支付成功（弹层自动关闭）	`{ payment_intent_id: 'pi_xxx' }`
`checkout.cancel`	买家关闭弹层或在结算页主动取消	`{ reason: 'user_closed' }`
`checkout.error`	支付失败（弹层保留，便于买家重试）	`{ message: '...' }`
`checkout.open` / `checkout.loaded` / `checkout.close`	弹层生命周期	—

function onSuccess(data) {
  console.log('支付成功，payment_intent_id =', data.payment_intent_id);
  // 注意：履约请以服务端 Webhook 为准，而非本事件
}

FastStar.on('checkout.success', onSuccess);
FastStar.on('checkout.cancel', function (data) { console.log('已取消', data); });
FastStar.on('checkout.error',  function (data) { console.warn('支付失败', data); });

// 解绑：传回调解绑单个监听器；不传则解绑该事件全部回调
FastStar.off('checkout.success', onSuccess);

使用 Checkout Session 时，事件 data 中还会携带 checkout_session_id。

自动绑定 data-faststar-checkout

给任意元素加 data-faststar-checkout 属性，点击即自动唤起弹层。属性值可以是完整 URL 或 linkId：

<!-- 完整 URL -->
<a href="#" data-faststar-checkout="https://cashier.faststarpay.com/pay/plink_abc123">立即购买</a>

<!-- 仅 linkId -->
<button data-faststar-checkout="plink_abc123">立即购买</button>

<!-- 属性值留空：回退使用 <a> 标签的 href -->
<a href="https://cashier.faststarpay.com/pay/plink_abc123" data-faststar-checkout>立即购买</a>

绑定基于事件委托实现，动态插入的元素同样生效，无需重新初始化。

保存信用卡：FastStar.cards.add

FastStar.cards.add(session, callbacks) 打开安全加卡弹层，把买家的卡保存到 FastStar 卡库，供之后 off-session 扣款。整个过程是「iframe 套 iframe」：

商户站 → (SDK 弹层 iframe) → FastStar 加卡页（我们域名） → 通道的安全 iframe

卡号只会进入支付通道的安全 iframe——既不经过商户，也不经过 FastStar 服务器。你最终只拿到 FastStar 令牌（pm_xxx）+ 脱敏卡信息。

时序（务必按此对接）

商户服务端先凭 API Key 创建 SetupIntent（不要把 API Key 放到浏览器）：

POST /api/v1/public/customers/:id/setup-intent
→ data: { client_secret, publishable_key, setup_intent_id, provider }

服务端把上一步结果，连同加卡令牌化接口地址与你签发的短期令牌，一并下发给浏览器，前端调用：

FastStar.cards.add(
  {
    customerId: 'cus_xxx',
    clientSecret: 'seti_xxx_secret_xxx',     // 来自 setup-intent
    publishableKey: 'pk_live_xxx',           // 来自 setup-intent
    attachUrl: 'https://api.faststarpay.com/api/v1/public/customers/cus_xxx/payment-methods',
    authToken: '短期令牌'                     // 由你的服务端签发，用于调用 attachUrl
  },
  {
    onSuccess: function (card) {
      // card = { payment_method_id: 'pm_xxx', brand, last4, exp_month, exp_year, is_default }
      console.log('已保存卡片', card.payment_method_id);
    },
    onError: function (err) { console.warn('加卡失败', err.message); }, // 弹层保留，可重试
    onCancel: function () { console.log('用户取消加卡'); }
  }
);

SDK 打开居中弹层 iframe，指向收银台域的 cards/add?embedded=1。加卡页就绪后，SDK 通过 postMessage 把 session 安全传入——凭据不进 URL，authToken 不会暴露。
买家在通道的安全输入框中填卡并保存。加卡页完成令牌化后，携带 { setup_intent_id } 调用 attachUrl 绑定支付方式。
加卡页把脱敏卡信息回传给 SDK，触发 onSuccess(card) 并自动关闭弹层。

加卡事件

同样的结果也会以事件形式抛出，可用 FastStar.on 监听：

事件	含义	data
`card.added`	加卡成功（弹层自动关闭）	`{ payment_method_id, brand, last4, exp_month, exp_year, is_default }`
`card.error`	令牌化或绑定失败（弹层保留，可重试）	`{ message }`
`card.cancel`	买家关闭弹层或主动取消	—
`card.ready`	加卡页就绪（SDK 内部据此注入 session）	—

FastStar.cards.close() 可手动关闭加卡弹层且不触发回调，便于你在自己的回调里收尾。

安全说明

弹层 iframe 启用了 sandbox （allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation）；其中 allow-top-navigation-by-user-activation 与 allow-popups 用于支持 3DS 银行验证跳转。
SDK 只接受消息体为 { source: 'faststar', ... } 且 origin 与当前结算页 / 加卡页一致的 postMessage，其他消息一律忽略。
checkout.success 事件仅用于前端交互（关弹层、跳转感谢页等）。履约必须以服务端 Webhook 为准。
加卡时卡号不经过商户也不经过 FastStar 服务器；authToken 通过 postMessage 传入而非 URL，避免泄露。