Wayflow
    • 接入指南
    • 认证与签名
    • 加密与解密
    • Webhook 通知
    • 错误码与重试
    • 关于SDK
      • SDK 使用指南
      • PHP 快速开始
      • Java 快速开始
      • Node.js / TypeScript 快速开始
      • Python 快速开始
      • Go 快速开始
    • 卡产品组
      • 卡产品组列表（分页）
        POST
      • 卡产品组列表（非分页）
        POST
      • 卡产品组详情
        POST
    • 卡产品
      • 卡产品相关字典
        • 费用模型字典
        • 舍入模式字典
      • 卡产品列表（分页）
        POST
      • 卡产品列表（非分页）
        POST
      • 卡产品详情
        POST
    • 卡钱包
      • 卡钱包划转
        • 卡钱包转出
        • 卡钱包转入
      • 卡钱包相关字典
        • 交易订单状态字典
        • 交易订单流向字典
        • 交易订单审批状态字典
      • 卡钱包查询
        • 卡钱包列表（分页）
        • 卡钱包列表（非分页）
        • 卡钱包详情
    • 卡片交易
      • 交易查询
        • 卡片交易列表（分页）
        • 卡片交易详情
      • 卡片交易相关字典
        • 交易类型字典
        • 交易状态字典
        • 交易商户国家字典
        • 交易资金流向字典
    • 卡钱包交易
      • 卡钱包交易订单
        • 卡钱包转账订单列表（分页）
        • 卡钱包转账订单详情
        • 取消卡钱包转账订单
      • 卡钱包交易流水
        • 卡钱包流水列表（分页）
        • 卡钱包流水详情
    • 卡片
      • 卡片查询
        • 10010105
          • 卡片详情
        • 10010107
          • 卡片详情
        • 卡片列表（分页）
        • 查询卡片敏感信息
      • 发卡
        • 10010105
          • 消费控制配置示例
          • 字典
            • 商户查询
              • 商户列表（分页）
              • 商户详情
            • 国家字典
            • 消费限制类型字典
            • 消费限额周期字典
          • 发卡预检
          • 发卡
        • 10010107
          • 发卡
          • 发卡预检
      • 卡片更新
        • 10010105
          • 更新卡片消费规则
        • 更新卡片别名
      • 卡片状态操作
        • 卡片冻结
        • 卡片解冻
        • 卡片注销
      • 卡片任务
        • 发卡任务详情
        • 发卡任务明细（分页）
        • 批量修改卡片状态
        • 卡片状态任务明细（分页）
        • 卡片状态任务详情
      • 卡片相关字典
        • 卡片状态字典
        • 时区字典
      • 充值
        • 10010107
          • 充值预检
          • 充值
      • 提现
        • 10010107
          • 提现预检
          • 提现

    Webhook 通知

    通过 Webhook 接收卡片、交易及卡钱包划转等事件通知。

    创建 Webhook#

    1.
    进入开发者中心的 Webhook 页面，点击「创建」。
    2.
    填写接收通知的 HTTPS 地址，选择已启用的 API Key。
    3.
    选择需要接收的事件通知。
    4.
    确认配置，完成安全验证。
    5.
    创建并启用后，订阅的事件发生时，系统将向指定地址发送通知。
    6.
    在投递记录中查看结果，必要时重新投递。

    如何接收#

    1.
    PHP SDK 配置本地 API Key、客户端加密私钥和平台鉴权公钥，调用 WebhookHandler.handle()，自动完成验签、接收方检查、解密和事件字段校验。
    2.
    按 deliveryBizId 去重；可靠保存后返回 HTTP 2xx，再异步处理业务。重复通知直接返回 2xx，不重复执行业务。
    独立调用 decrypt() 时，必须先对同一份请求头和原始请求体调用 verifySignature()；验签失败立即停止。验签、解密或保存失败时，不返回成功。
    签名和加密细节见认证与签名、加密与解密。

    请求头#

    请求头说明
    Content-Typeapplication/json; charset=utf-8
    X-SlaunchX-Delivery-Id投递 ID
    X-SlaunchX-Event-Type事件类型
    X-SlaunchX-Timestamp毫秒时间戳
    X-SlaunchX-Key-Id接收方 API Key 业务 ID
    X-SlaunchX-Signature平台签名
    以下字段均指解密后的业务内容。

    事件结构#

    字段说明
    eventId同一业务事实的稳定 ID
    deliveryBizId一次投递生命周期 ID，用于去重
    eventType事件类型，见下表
    payloadSchemaVersion当前为 1；不支持的版本不得猜测处理
    occurredAt业务发生时间，UTC RFC 3339
    workspaceBizId所属工作区标识
    resource.type / resource.bizId资源类型和业务 ID，用于路由及回查
    data该事件类型的业务内容
    eventTyperesource.type用途
    card.statuscard_information卡片状态变化
    card.issuancecard_information发卡结果
    card.controlscard_information消费控制变更
    card.transactioncard_transaction卡片交易结果
    card.group.wallet.transferuser_card_product_group_wallet_order卡钱包划转审批及结果

    事件字段#

    card.status#

    字段说明
    previousStatus变更前状态
    currentStatus变更后状态
    reasonCategory原因分类
    cardVersion卡资料版本，用来判断先后
    状态：
    ISSUING / ISSUE_FAILED / IN_USE / FROZEN / USER_CANCELLED /
ADMIN_CANCELLED / EXPIRED / PROVIDER_CLOSED
    原因：
    ISSUANCE_RESULT / USER_REQUESTED / ADMINISTRATIVE_ACTION / RISK_CONTROL /
NATURAL_EXPIRY / EXTERNAL_STATUS_CHANGE / PLATFORM_RECONCILIATION
    USER_REQUESTED 表示用户侧发起（例如解冻），不是风控或管理员动作。

    card.issuance#

    公共字段：batchBizId、userCardProductGroupBizId、platformCardProductBizId、status。
    status=SUCCEEDED：cardBizId 必有
    status=FAILED：failureCategory 为 VALIDATION_FAILED / CAPABILITY_UNAVAILABLE / PROCESSING_FAILED
    resource.bizId 是平台卡 ID。不暴露渠道卡号或原始拒绝文案。

    card.controls#

    data 只有 cardVersion。表示平台生效的管控集合已替换；当前值请再查卡详情接口。

    card.transaction#

    公共字段：cardBizId、cardGroupWalletBizId、transactionType、transactionStatus、fundFlowType、settlement、transactionAt。可选商户字段：merchantName、merchantCategoryCode、merchantCountryCode。fundFlowType 相对卡钱包。
    transactionTypetransactionStatus资金方向
    AUTHORIZATIONSUCCEEDED通常 OUTFLOW
    DECLINEDFAILED通常 OUTFLOW
    CAPTURESUCCEEDED通常 OUTFLOW
    REFUNDSUCCEEDEDINFLOW
    REVERSALSUCCEEDEDINFLOW
    授权、捕获、退款或冲正也可能以对应 transactionType 携带 transactionStatus=FAILED，不能只用类型判断成功。失败时资金方向仍按操作类型定义，不表示资金已实际移动。
    拒绝 / 失败还带 declineCategory：
    INSUFFICIENT_FUNDS / CARD_STATUS / CARD_CONTROL / RISK_CONTROL /
CAPABILITY_UNAVAILABLE / PROCESSING_FAILED
    金额是 {currency, amount}：currency 大写币种名，amount 是主单位十进制字符串，不是 JSON 数字。

    card.group.wallet.transfer#

    公共字段：userCardProductGroupBizId、cardGroupWalletBizId、internalWalletBizId、direction、amount、status。direction 相对卡钱包；金额结构与交易事件相同。
    阶段statusapprovalStatus
    发起PENDING_APPROVALPENDING_APPROVAL
    审批通过PROCESSINGAPPROVED
    完成COMPLETEDAPPROVED
    驳回FAILEDREJECTED
    取消CANCELLEDCANCELLED
    执行失败FAILEDAPPROVED
    executionStatus 与 outcomeCategory 是可选字段，不存在时不返回，不使用 null。
    发起时不返回 executionStatus；审批通过为 PENDING_EXECUTION，完成为 SETTLED。
    审批驳回不返回 executionStatus。取消或执行失败时按实际返回值处理，不根据 status 推导执行状态。
    执行状态全集：PENDING_EXECUTION、CHANNEL_PROCESSING、CHANNEL_CONFIRMED、SETTLED、REFUNDED。
    结果分类全集：BUSINESS_REJECTED、USER_CANCELLED、CAPABILITY_UNAVAILABLE、PROCESSING_FAILED、FUNDS_RESTORED。按实际返回值处理，不建立未经确认的一对一映射。
    通知可能重复、乱序或缺失中间阶段。不得用较早阶段覆盖已确认的终态；状态不明确时，回查 GET /card-products/wallets/transfers/{bizId}。

    投递与重试#

    项目默认规则
    成功条件HTTP 2xx，不检查响应体
    请求超时10 秒，可配置 1–60 秒
    失败重试上次尝试完成后等待 60 秒、5 分钟、15 分钟、60 分钟
    尝试次数最多 5 次，含首次
    记录保留90 天
    自动重试和手工重放复用原投递 ID、时间戳、签名及密文。SDK 默认不启用 Webhook 时间戳窗口，每次接收仍须验签和去重。
    全部尝试失败后标记为 FAILED，可在开发者中心查看记录，并在请求快照未过期时手工重放。
    修改于 2026-09-19 08:50:06
    上一页
    加密与解密
    下一页
    错误码与重试
    Built with