Webhook 通知

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

创建 Webhook

进入开发者中心的 Webhook 页面，点击「创建」。

填写接收通知的 HTTPS 地址，选择已启用的 API Key。

选择需要接收的事件通知。

确认配置，完成安全验证。

创建并启用后，订阅的事件发生时，系统将向指定地址发送通知。

在投递记录中查看结果，必要时重新投递。

如何接收

PHP SDK 配置本地 API Key、客户端加密私钥和平台鉴权公钥，调用 WebhookHandler.handle()，自动完成验签、接收方检查、解密和事件字段校验。

按 deliveryBizId 去重；可靠保存后返回 HTTP 2xx，再异步处理业务。重复通知直接返回 2xx，不重复执行业务。

独立调用 decrypt() 时，必须先对同一份请求头和原始请求体调用 verifySignature()；验签失败立即停止。验签、解密或保存失败时，不返回成功。

签名和加密细节见认证与签名、加密与解密。

请求头

请求头	说明
`Content-Type`	`application/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`	该事件类型的业务内容

`eventType`	`resource.type`	用途
`card.status`	`card_information`	卡片状态变化
`card.issuance`	`card_information`	发卡结果
`card.controls`	`card_information`	消费控制变更
`card.transaction`	`card_transaction`	卡片交易结果
`card.group.wallet.transfer`	`user_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 相对卡钱包。

transactionType	transactionStatus	资金方向
`AUTHORIZATION`	`SUCCEEDED`	通常 `OUTFLOW`
`DECLINED`	`FAILED`	通常 `OUTFLOW`
`CAPTURE`	`SUCCEEDED`	通常 `OUTFLOW`
`REFUND`	`SUCCEEDED`	`INFLOW`
`REVERSAL`	`SUCCEEDED`	`INFLOW`

授权、捕获、退款或冲正也可能以对应 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 相对卡钱包；金额结构与交易事件相同。

阶段	`status`	`approvalStatus`
发起	`PENDING_APPROVAL`	`PENDING_APPROVAL`
审批通过	`PROCESSING`	`APPROVED`
完成	`COMPLETED`	`APPROVED`
驳回	`FAILED`	`REJECTED`
取消	`CANCELLED`	`CANCELLED`
执行失败	`FAILED`	`APPROVED`

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，可在开发者中心查看记录，并在请求快照未过期时手工重放。

创建 Webhook#

如何接收#

请求头#

事件结构#

事件字段#

card.status#

card.issuance#

card.controls#

card.transaction#

card.group.wallet.transfer#

投递与重试#