用途 本技能面向 Setel 商户支付集成工作,用于搭建、开发、调试、审查和讲解 Setel 支付集成。Setel 的主要线上支付产品是“Pay with Setel online”:创建结账会话后,顾客会被引导至 Setel Checkout 页面或 Setel App,在其中使用 Setel Wallet 或 Setel CardTerus 完成支付。
主要能力 技能配套以下参考资料(在给出事实性 API 指导或编写集成代码前应先阅读):
- references/setel-api.md:环境、认证头、端点目录、结账会话与支付意图字段表、状态、Webhook 载荷与签名算法、退款、取消、捕获、错误码及已知文档不一致之处。
- references/setel-other-apis.md:Pay with Setel 扫码(钱包交易)、SSO/OAuth、用户账户、用户支付方式、Mesra 忠诚度、外部订单、自动停车与电动车充电 API。
- references/setel-settlement.md:结算报告(Setel Dashboard、SFTP)、MPF 文件格式及手动结算 API。
- references/account-setup.md:开户、凭证、仪表盘、沙箱与生产环境、环境变量名称及商务联系方式。
- references/source-map.md:用于选择正确的官方页面并查看文档覆盖情况。
使用方式(核心工作流)
- 确认商户已在 Setel 完成开户,并持有对应环境的 x-api-key、x-api-secret 与 merchantId。
- 选定接入面:线上结账会话(Web/移动)、扫码钱包交易(线下)或合作伙伴流程(SSO、忠诚度、停车、充电)。
- 调用 Setel 前,先在本地创建带唯一 referenceId 的待处理订单。
- 决定捕获模式:capture: true(直接捕获)或 capture: false(先授权,30 分钟内捕获)。
- 在服务端调用 POST /v1/checkout/sessions,携带 x-api-key 与 x-api-secret,请求体包含 amount(字符串,MYR)、currency: "MYR"、redirect.successUrl / redirect.cancelUrl 及 webhook.url。
- 将顾客引导至返回的结账 URL(PC 端为 Setel Checkout 页面;移动端可使用跳转链接、结账 URL 或 App 深度链接)。在沙箱中记录真实的响应字段名。
- successUrl 仅用于浏览器体验,不得据此履约。
- 收到 Webhook 后,重新计算签名头:以 x-api-secret 的十六进制 SHA-256 为密钥,对文档规定的字段拼接串做 HMAC-SHA256,并使用恒定时间比较。
- 通过 GET /v1/checkout/sessions/{session id}(或 GET /v1/payments/payment-intents/{id})确认,仅当 paymentIntentStatus 为 succeeded 且 amount、currency、referenceId 与 session id 均匹配时才幂等入账。
- 若为已授权的最终支付,使用 POST /v1/payments/payment-intents/{id}/capture 捕获(不得超过授权金额),或将其取消。
- 对超时未收到 Webhook 的会话进行回查;Setel 说明 Webhook 可能丢失或重复发送。
关键事实
- 沙箱基础 URL:http://api-pre-prod.setel.com(System environment 页面,最后更新于 2024 年 11 月 18 日);生产环境:https://api.setel.com。
- 合作伙伴认证:每个请求携带 x-api-key 与 x-api-secret 头,Content-Type: application/json;密钥仅限后端使用。
- 创建会话:POST /v1/checkout/sessions,必填字段为 amount、currency、redirect。
- 查询会话:GET /v1/checkout/sessions/{id};取消:PATCH /v1/checkout/sessions/{id}/cancel。
- 支付意图:GET /v1/payments/payment-intents/{id}、POST .../{id}/capture、POST .../{id}/cancel、POST .../{id}/refund。
- amount 为以林吉特计价的字符串(示例使用 "10"),仅支持 MYR。
- capture 默认为 true;已授权(hold)支付 30 分钟后过期。
- 支付意图状态:requires_payment_method、requires_action(暂不支持)、authorised、processing、failed、succeeded、cancelled、expired、partially_refunded、refunded。
- Webhook 通过 webhook.url 按会话设置;请求头为 signature;载荷包含 id、createdAt、updatedAt、apiKey、paymentIntentId、paymentIntentStatus、amount、referenceId。
- 签名:secretHash = sha256_hex(x-api-secret);data = id+createdAt+updatedAt+apiKey+paymentIntentId+paymentIntentStatus+amount+referenceId(缺失字段视为空字符串);signature = hmac_sha256_hex(key=secretHash, data)。
- 线上支付方式:Setel Wallet 与 Setel CardTerus;扫码仅支持 Setel Wallet,且没有 Webhook。
- 重复 referenceId 返回 400 REFERENCE_ID_EXISTED(9300101)。
- 退款从商户可用余额(非待结算余额)扣减;允许部分退款,直到 refundedAmount 等于 amount。
- 结算报告每日 GMT+8 01:00 生成,覆盖前一日 00:00 至 23:59。
适用场景 适用于需要接入 Setel 线上结账、扫码钱包交易、SSO/OAuth、忠诚度、外部订单、自动停车或电动车充电等能力的商户侧支付集成开发与审查工作,也适用于调试和讲解既有 Setel 集成。
限制与待确认事项
- 密钥必须仅保留在服务端,不得下发到浏览器或移动端包中,不得提交到代码库。
- 不得将 processing 或 authorised 视为已支付;只有 succeeded(及后续退款状态)表示已收款。
- 对 capture: false 的场景,须在 30 分钟内捕获或取消,否则支付意图会过期。
- 第三方收单机构须发送 subMerchant(name、reference、merchantCategoryCode、state)。
- 参考资料中列出的字段名与方法不一致之处,应视为需在沙箱确认的事项,而非既定事实。
- 不得引用费率;Setel 未公布商户费率。
- 以下内容文档未提供,须与 Setel 确认:确切的结账 URL 字段名、按 referenceId 查询的方法、Webhook 重试计划、Webhook 来源 IP、速率限制、沙箱测试账户、沙箱协议(http 与 https)及商务条款。