SuperAPI AI 工具集

portaly-payment-integration

编程与开发

查看项目

更新于 10-15 21:41

技能介绍

用途:帮助工程师用集成范围 API Key(前缀 pcs_test_itg_ 或 pcs_live_itg_)将应用接入 Portaly Payment 托管结账,输出偏操作性(步骤、请求/响应要点、可直接复制的代码),而非架构文章。

主要能力:该密钥可读取订阅方案、创建结账会话、验证并消费签名回调,可选取消/恢复订阅、创建订阅者自助门户会话、查询订阅与订单;不能创建或修改方案、商户配置、折扣码或上传图片,尝试会返回 403 KEY_SCOPE_FORBIDDEN。方案、价格与折扣码由商户在 Portaly 面板管理,须在运行时调用 GET /api/creator-subscription/plans?status=active 获取,不可硬编码。

使用方式:向商户索取 PORTALY_API_KEY 与 PORTALY_CALLBACK_SECRET 存入 .env(勿在对话中粘贴密钥,若已粘贴应轮换)。创建结账用 POST /api/creator-subscription/checkout-sessions(planId、HTTPS 的 callbackUrl,可选 successRedirectUrl、cancelRedirectUrl、metadata、discountCode、profitSharingId 等),跳转到返回的 data.checkoutUrl。回调用 HMAC-SHA256 校验 x-portaly-signature,时间戳须在 ±5 分钟内,按事件级键去重;有现成签名适配脚本(scripts/sign_callback.mjs、scripts/sign_callback.webcrypto.mjs、scripts/sign_callback.py),发布前运行 scripts/check_callback_vectors.mjs --runtime <node|webcrypto|python|go> 验证。处理 422 PLAN_INACTIVE、404 PLAN_NOT_FOUND、403 KEY_SCOPE_FORBIDDEN 等错误。可选自助接口包括 POST /subscriptions/{id}/cancel、/resume、POST /portal-sessions 及 GET /subscriptions、/orders 查询。

限制:严禁用此密钥调用退款接口 POST /orders/{orderId}/refund;方案、定价、折扣码变更需走商户面板或全权限路径。版本上报接口为 POST https://portaly.ai/api/creator-subscription/skill-version。其余细节资料未提供。