@alguna/ checkout-sdk (英语)
嵌入 阿尔古纳 检查你的产品。 您的服务器薄荷 带有密钥 API 的退出会话; 您的前端挂载 包含返回的 URL 组件; Alguna 处理付款的收集、税收和 账户/订阅创建——与斯德雷克嵌入式相同的信任模式 结出.
从阿尔古纳的原产地运来的iframe 里面有检查结果 这是一个
硬隔离边界:您页面的 CSS 无法访问到检查, 以及
退出无法重写您的页面 。 卡片条目使用Frede 自己的 Iframe(所以您
网站不在PCI范围。 样式取出 仅限 通过
appearance prop——与"花纹元素"相同的模型. SDK飞船没有
样式表; 没有要导入的内容 .
npm install @alguna/checkout-sdk
快速启动
0. 一次性设置(Alguna仪表板)
- 创建 API 密钥 : 设置 ~ API 密钥 (单位:千美元)
id.secret— 服务器 秘密,永远不要把它送到浏览器. - 至少连接了1个支付处理器(例如:friede),用于法律 实体,你的账单.
1. 决定买方是谁(三种身份模式)
| 你的情况 | 在会话中发送什么 | 退职有什么用 |
|---|---|---|
| 买家是阿尔古纳的客户 | customer_id (或 customer_alias(中文(简体) ) | 向客户收费;可以显示其保存的卡片(参见 已保存的牌(中文(简体) ) |
| 购买者已登录 产品 | customer: { name, email, address? … } | 从您已经知道的创建 Alguna 客户端 —— 不重制版 |
| 购买者匿名( 公开定价页面) | (什么都没有) | 付款前退出收集电子邮件/ 姓名 |
2. 创建会话( 您的服务器)
const response = await fetch("https://api.alguna.io/checkout-sessions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ALGUNA_API_KEY}`,
"Alguna-Version": "2026-04-01", // pin the API version
"Content-Type": "application/json",
},
body: JSON.stringify({
customer: { name: "Acme Corp", email: "[email protected]" }, // mode 2
plan_id: "plan_...", // or line_items: [...] / amount
client_reference_id: "order_1234", // echoed on the webhook
expires_in_seconds: 3600,
}),
});
const session = await response.json();
// → { id, url, session_token, amount, currency, expires_at, ... }
3. 挂出( 您的前端)
反应 :
import { AlgunaCheckout } from "@alguna/checkout-sdk/react";
<AlgunaCheckout
url={session.url}
layout="compact" // your page provides the context
appearance={{ accentColor: "#4d68eb" }}
onComplete={({ checkoutSessionId }) => showSuccess()}
onError={({ code }) => {
if (code === "session_expired") refreshSession(); // mint a new one, re-mount
}}
/>;
香草:
import { AlgunaCheckout } from "@alguna/checkout-sdk";
const checkout = AlgunaCheckout.init({
url: session.url,
container: "#checkout",
onComplete: () => (window.location.href = "/welcome"),
});
// checkout.update({ appearance }); checkout.destroy();
onComplete 支付成功时点火——替换或卸载
组件并带客户前进; 退出仅显示一个简短
中性确认.
4. 对完成的反应(您的服务器)
订阅 checkout.session.completed webhook——它的有效载荷
accountId, (中文(简体) ), subscriptionId, (中文(简体) ), paymentId, (中文(简体) ), invoiceId,还有你的
clientReferenceId - 或民意调查 GET /checkout-sessions/{id} 直至
payment_id编号 :subscription_id 出现.
外观
一切都在你的组织仪表板上进行直播(没有重挂) 品牌:
appearance={{
preset: "soft", // or "minimal" | "sharp" — a curated
// starting point; every field below overrides it
accentColor: "#4f46e5", // CTAs & highlights
primaryColor: "#0f0f0f",
mode: "dark", // dark canvas
borderRadius: 12, // cards, inputs, buttons
fontFamily: "Georgia, serif",// no font download — use stacks you load
density: "compact", // tighter vertical rhythm
payButtonLabel: "Subscribe for {amount}",
colors: { // fine-grained palette
surface: "#0b1220", card: "#111a2e", text: "#e7e5e4",
mutedText: "#a8a29e", border: "#1f2b45", inputBackground: "#0e1626",
inputBorder: "#2563eb", // input outlines, separate from `border` (the
// frame) — set `border` to the surface color to
// flatten the frame while keeping fields outlined
},
}}
组件大小: layout: "compact" 放弃退出
页面内嵌入。 iframe 自动调整内容; 通过 maxHeight 改为
盖上,窗体会在这个高度以上的组件内滚动.
样式
唯一支持的校对方式是 appearance 道具——颜色,
边框半径,字体家族,轻/暗模式,以及被整理的预设. 因为
退出在 Iframe 中被隔离, 您页面的 CSS 无法( 也不应该) 目标
这个 这反映了花纹元素和原始元素的样式.
自定义支付按钮
调整自己的付款按钮而不是内置的按钮:
const ref = useRef<AlgunaCheckoutRef>(null);
const [state, setState] = useState<CheckoutState>();
<AlgunaCheckout
ref={ref}
url={session.url}
hidePayButton
onCheckoutStateChange={setState}
onComplete={...}
/>
<button disabled={!state?.canSubmit} onClick={() => ref.current?.submit()}>
{state?.isProcessing ? "Processing…" : "Pay"}
</button>
hidePayButton 隐藏我们的按钮( “ 付款是安全的, 加密的 ” 行)
留职); submit() (一) 电机触发付款; onCheckoutStateChange 报告
{ canSubmit, isProcessing, isComplete, error } 这样你就可以按下按钮了.
已保存的牌
默认情况下,每个买家——新买或退买——都新鲜地入出出出牌. 让一个
用他们之前用的卡片还客户薪,通过
showSavedPaymentMethods (仅对 customer_id 编号 : customer_alias
我们了解谁是买方:
<AlgunaCheckout url={session.url} showSavedPaymentMethods />
有了它,一个客户 谁在文件中有一张卡 看到了它的预选,有一个"使用a 输入新卡的选项。 纸牌由您管理 客户端设置, 退出时未编辑内置 .
任期
取出时会显示一个术语接受复选框 必须 于 买家可以付钱。 它将你的法律实体的服务条件联系起来——同样的条件 在别处为该实体配置(引用、主机检查)——所以不需要 将传递给SDK.
使复选框具有可选性(不是块付款),通过
requireTermsAcceptance={false}数字 :
<AlgunaCheckout url={session.url} requireTermsAcceptance={false} />
信任线
支付按钮下"支付安全并加密"行可被隐藏:
<AlgunaCheckout url={session.url} hidePaymentSecurityText />
正在回放以滚动
检查的iframe 大小到它的内容, 所以轮子手势在它上
转发到您的页面(默认滚动)。 要处理滚动自己
例如,在自定义滚动容器内使用 onScroll数字 :
<AlgunaCheckout url={session.url} onScroll={(deltaY) => myScroller.scrollBy(0, deltaY)} />
镜子 onResize。 。 。 .
会话错误( M)
- 届会到期( E)
expires_in_seconds,默认为24h,最大为7d). 每个创建一个 检查尝试. onError代码 :session_expired(清新会话并重新挂起)和load_failed(重试/支持).
安保模式
检查从阿尔古纳的原产地开始,所以你的页面从不触及 敏感数据或检查的 DOM :
- 会话符号是短寿命和单目的. 每个都由你做成
服务器(带有您的秘密密钥),用于一次检出,范围为该会话,以及
期满
expires_in_seconds) (中文(简体) ). 浏览器只持有这个范围标记, 从来没有你的 API 密钥. - 卡片数据从不输入你的DOM. 它被俘获在史崔克的内框里 因此,你的站点留在PCI SAQ-A范围.
- 您的CSS无法联系到报到,反之亦然. Iframe是很难的
边框——仅通过样式
appearance。 。 。 . - 来源允许列入名单. 兽群可以限制哪些场所可以嵌入它们 退出( 磁盘设置); 嵌入层拒绝在被否决的上渲染 源代码。 SDK通过您的页面源头, 从而可以对每个页面进行校对 后弥陀.