JCB 回调 - MC Platform Open API

JCB Webhook 会推送到商户在 SpeedPay 商户平台 API KEY 中配置的 HTTPS 回调地址。api_name 标识回调类型，每次回调仅会填充一个与该类型对应的业务对象。

接入方式

项目	说明
方法	`POST`
地址	商户在 SpeedPay 商户平台 API KEY 中配置的 HTTPS 回调地址
内容类型	`application/json`
签名 Header	`Authorization`

Authorization 是 SpeedPay 使用平台私钥对完整原始 JSON 请求体生成的签名。商户必须使用 SpeedPay 公钥验签，并在验签通过后处理业务数据。

处理流程

读取并保留完整原始 JSON 请求体和 Authorization Header。
使用 SpeedPay 公钥对原始请求体验签，验签失败时停止处理。
根据 api_name 确定业务对象，只读取该类型对应的对象字段。
根据业务流水号、交易 ID 或卡号做幂等处理。
建议先持久化或写入队列，再执行耗时业务逻辑。
接收成功后返回数字类型的 code: 0。

回调索引

`api_name`	说明	业务对象	详情
`jcb_card_apply_status`	申请状态	`card`	查看详情
`jcb_card_status_change`	卡状态变更	`jcb_card_status`	查看详情
`jcb_card_transaction_3ds`	3DS 验证码	`transaction_opt_code`	查看详情
`jcb_card_block_transaction`	链上充值	`block_transaction`	查看详情
`jcb_card_transaction`	卡片消费	`transaction`	查看详情
`jcb_card_block_express`	物流信息	`jcb_card_express`	查看详情
`jcb_card_to_card`	卡对卡转账	`jcb_card_to_card`	查看详情
`jcb_mobile_advice`	手机号变更	`jcb_card_mob`	查看详情
`jcb_email_advice`	邮箱变更	`jcb_card_email`	查看详情
`jcb_card_no_advice`	卡号变更	`jcb_card_no`	查看详情
`jcb_apply_edit_advice`	申请资料变更	`jcb_card_apply_edit`	查看详情

申请状态

在 JCB 卡申请状态变化后通知商户申请结果和失败原因。

项目	值
`api_name`	`jcb_card_apply_status`
业务对象	`card`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_card_apply_status`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`card_no`	`string`	否	卡号，可能为脱敏卡号
`status`	`number`	否	申请状态
`fail_reason`	`string`	否	失败原因，失败时返回
`water_no`	`string`	否	商户侧业务流水号

status 中 4 表示申请拒绝，6 表示申请失败，7 表示申请成功。 请求示例

{
  "api_name": "jcb_card_apply_status",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "card": {
    "card_no": "356772******6942",
    "status": 7,
    "water_no": "APPLY202607240001"
  }
}

卡状态变更

在 JCB 卡状态发生变化时通知商户更新本地卡状态。

项目	值
`api_name`	`jcb_card_status_change`
业务对象	`jcb_card_status`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_card_status_change`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`card_no`	`string`	否	卡号，可能为脱敏卡号
`card_status`	`number`	否	平台卡状态

请求示例

{
  "api_name": "jcb_card_status_change",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "jcb_card_status": {
    "card_no": "356772******6942",
    "card_status": 6
  }
}

3DS 验证码

在 JCB 交易需要 3DS 验证时推送验证码、金额和有效时间。

项目	值
`api_name`	`jcb_card_transaction_3ds`
业务对象	`transaction_opt_code`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_card_transaction_3ds`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`card_no`	`string`	否	卡号，可能为脱敏卡号
`transaction_amount`	`string`	否	交易金额
`transaction_currency`	`string`	否	交易币种
`otp_code`	`string`	否	3DS 验证码
`created_at`	`number`	否	验证码生成时间戳
`expired_at`	`number`	否	验证码过期时间戳
`merchant_name`	`string`	否	商户名称

请求示例

{
  "api_name": "jcb_card_transaction_3ds",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "transaction_opt_code": {
    "card_no": "356772******6942",
    "transaction_amount": "1.20",
    "transaction_currency": "HKD",
    "otp_code": "159238",
    "created_at": 1784880000,
    "expired_at": 1784880300,
    "merchant_name": "Alipay"
  }
}

链上充值

在链上充值入账时推送区块链交易、地址、金额和费用信息。

项目	值
`api_name`	`jcb_card_block_transaction`
业务对象	`block_transaction`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_card_block_transaction`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`amount`	`string`	是	充值金额
`amount_in_usd`	`string`	是	折算美元金额
`block_hash`	`string`	是	区块链交易哈希
`blockchain`	`string`	是	区块链网络
`calculated_fee`	`string`	是	计算后的费用
`currency`	`string`	是	充值币种
`destination_address`	`string`	是	目标钱包地址
`id`	`string`	是	链上充值记录 ID
`p_created_at`	`string`	是	记录创建时间
`source_address`	`string`	是	来源钱包地址
`card_no`	`string`	是	卡号，可能为脱敏卡号

请求示例

{
  "api_name": "jcb_card_block_transaction",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "block_transaction": {
    "card_no": "356772******6942",
    "amount": "1",
    "amount_in_usd": "1",
    "block_hash": "0x68412719f288c5c49b86138cd5de265ed29e1eacdd920de1a7921110bf8be0fa",
    "blockchain": "ETH-SEPOLIA",
    "calculated_fee": "0",
    "currency": "USDC",
    "destination_address": "0x95912225fe944cc96b142e63fad8a31450aaed93",
    "id": "f7752f50-7668-4dec-9745-257d893ac4f1",
    "p_created_at": "2026-07-24 19:39:40",
    "source_address": "0x95912225fe944cc96b142e63fad8a31450aaed93"
  }
}

卡片消费

在 JCB 卡片消费状态变化时推送交易金额、商户和状态信息。

项目	值
`api_name`	`jcb_card_transaction`
业务对象	`transaction`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_card_transaction`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`calculated_fee`	`string`	是	计算后的费用
`card_no`	`string`	是	卡号，可能为脱敏卡号
`final_local_amount`	`string`	是	最终本地金额
`id`	`string`	是	交易 ID
`local_amount`	`string`	是	本地交易金额
`local_currency`	`string`	是	本地交易币种
`merchant_city`	`string`	是	商户城市
`merchant_country`	`string`	是	商户国家或地区
`merchant_id`	`string`	是	商户 ID
`merchant_name`	`string`	是	商户名称
`p_created_at`	`string`	是	交易创建时间
`status`	`string`	是	交易状态
`transaction_amount`	`string`	是	交易金额
`transaction_currency`	`string`	是	交易币种
`type`	`string`	是	交易类型

status 可能为 Authorized、Declined、Settled、Reversed。type 可能为 Sales、Refund、Withdrawal。 请求示例

{
  "api_name": "jcb_card_transaction",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "transaction": {
    "calculated_fee": "5",
    "card_no": "356772******6942",
    "final_local_amount": "-0.12",
    "id": "8a2837fe-ae6f-4921-863e-9532cec837f1",
    "local_amount": "-0.12",
    "local_currency": "USD",
    "merchant_city": "",
    "merchant_country": "HK",
    "merchant_id": "666666660057123",
    "merchant_name": "Bindo Simulator Test",
    "p_created_at": "2026-07-24 20:24:52",
    "status": "Authorized",
    "transaction_amount": "-1",
    "transaction_currency": "HKD",
    "type": "Withdrawal"
  }
}

物流信息

在实体卡物流信息变化时通知商户承运方和运单号。

项目	值
`api_name`	`jcb_card_block_express`
业务对象	`jcb_card_express`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_card_block_express`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`express_no`	`string`	是	物流单号
`express_company`	`string`	是	物流公司
`card_no`	`string`	是	卡号，可能为脱敏卡号

请求示例

{
  "api_name": "jcb_card_block_express",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "jcb_card_express": {
    "card_no": "356772******6942",
    "express_company": "顺丰快递",
    "express_no": "SF1234567890"
  }
}

卡对卡转账

在 JCB 卡对卡转账完成后通知商户转账结果。

项目	值
`api_name`	`jcb_card_to_card`
业务对象	`jcb_card_to_card`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_card_to_card`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`from_card_no`	`string`	否	转出卡号，可能为脱敏卡号
`to_card_no`	`string`	否	转入卡号，可能为脱敏卡号
`status`	`string`	否	转账状态
`fail_reason`	`string`	否	失败原因，失败时返回
`amount`	`string`	否	转账金额
`currency`	`string`	否	转账币种
`water_no`	`string`	否	商户侧业务流水号

status 为 success 表示成功，failed 表示失败。商户应使用 water_no 做幂等处理。 请求示例

{
  "api_name": "jcb_card_to_card",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "jcb_card_to_card": {
    "from_card_no": "356772******7135",
    "to_card_no": "356772******6942",
    "status": "success",
    "amount": "1",
    "currency": "USD",
    "water_no": "TRANSFER202607240001"
  }
}

手机号变更

在 JCB 卡绑定手机号变更后通知商户同步新旧手机号。

项目	值
`api_name`	`jcb_mobile_advice`
业务对象	`jcb_card_mob`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_mobile_advice`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`card_no`	`string`	是	卡号，可能为脱敏卡号
`old_mob_no`	`string`	是	原手机号
`old_mob_no_of`	`string`	是	原手机号区号
`new_mob_no`	`string`	是	新手机号
`new_mob_no_of`	`string`	是	新手机号区号

请求示例

{
  "api_name": "jcb_mobile_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "jcb_card_mob": {
    "card_no": "356772******6942",
    "old_mob_no": "13800000000",
    "old_mob_no_of": "86",
    "new_mob_no": "13900000000",
    "new_mob_no_of": "86"
  }
}

邮箱变更

在 JCB 卡绑定邮箱变更后通知商户同步新旧邮箱。

项目	值
`api_name`	`jcb_email_advice`
业务对象	`jcb_card_email`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_email_advice`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`card_id`	`string`	是	平台卡片 ID
`card_no`	`string`	是	卡号，可能为脱敏卡号
`card_status`	`number`	是	平台卡状态
`old_email`	`string`	是	原邮箱
`new_email`	`string`	是	新邮箱

请求示例

{
  "api_name": "jcb_email_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "jcb_card_email": {
    "card_id": "card_123",
    "card_no": "356772******6942",
    "card_status": 1,
    "old_email": "old@example.com",
    "new_email": "new@example.com"
  }
}

卡号变更

在换卡或卡号变更后通知商户新旧卡号映射。

项目	值
`api_name`	`jcb_card_no_advice`
业务对象	`jcb_card_no`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_card_no_advice`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`card_id`	`string`	是	平台卡片 ID
`old_card_no`	`string`	是	原卡号，可能为脱敏卡号
`new_card_no`	`string`	是	新卡号，可能为脱敏卡号
`card_status`	`number`	是	平台卡状态

请求示例

{
  "api_name": "jcb_card_no_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "jcb_card_no": {
    "card_id": "card_456",
    "old_card_no": "356772******6942",
    "new_card_no": "356772******7001",
    "card_status": 1
  }
}

申请资料变更

在 JCB 申请资料变更后通知商户同步持卡人资料。

项目	值
`api_name`	`jcb_apply_edit_advice`
业务对象	`jcb_card_apply_edit`

公共字段

字段	类型	必填	说明
`api_name`	`string`	否	固定为 `jcb_apply_edit_advice`
`app_id`	`string`	否	商户应用 ID

业务对象字段

字段	类型	必填	说明
`water_no`	`string`	是	商户侧业务流水号
`first_name`	`string`	否	名
`last_name`	`string`	否	姓
`en_name`	`string`	否	英文姓名
`birthday`	`string`	否	出生日期
`cert_id`	`string`	否	证件号码
`cert_start_date`	`string`	否	证件有效期开始日期
`cert_end_date`	`string`	否	证件有效期结束日期
`address`	`string`	否	联系地址

请求示例

{
  "api_name": "jcb_apply_edit_advice",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "jcb_card_apply_edit": {
    "water_no": "EDIT202607240001",
    "first_name": "San",
    "last_name": "Zhang",
    "en_name": "ZHANG SAN",
    "birthday": "1990-01-01",
    "cert_id": "A1234567",
    "address": "Hong Kong"
  }
}

TypeScript 类型参考

type JcbApiName =
  | "jcb_card_apply_status"
  | "jcb_card_status_change"
  | "jcb_card_transaction_3ds"
  | "jcb_card_block_transaction"
  | "jcb_card_transaction"
  | "jcb_card_block_express"
  | "jcb_card_to_card"
  | "jcb_mobile_advice"
  | "jcb_email_advice"
  | "jcb_card_no_advice"
  | "jcb_apply_edit_advice";

interface JcbWebhook {
  api_name?: JcbApiName;
  app_id?: string;
  card?: JcbCardApplyStatus;
  jcb_card_status?: JcbCardStatusChange;
  transaction_opt_code?: JcbTransactionOtpCode;
  block_transaction?: JcbBlockTransaction;
  transaction?: JcbCardTransaction;
  jcb_card_express?: JcbExpressAdvice;
  jcb_card_to_card?: JcbCardToCard;
  jcb_card_mob?: JcbMobileAdvice;
  jcb_card_email?: JcbEmailAdvice;
  jcb_card_no?: JcbCardNoAdvice;
  jcb_card_apply_edit?: JcbApplyEditAdvice;
}

interface JcbCardApplyStatus {
  card_no?: string;
  status?: number;
  fail_reason?: string;
  water_no?: string;
}

interface JcbCardStatusChange {
  card_no?: string;
  card_status?: number;
}

interface JcbTransactionOtpCode {
  card_no?: string;
  transaction_amount?: string;
  transaction_currency?: string;
  otp_code?: string;
  created_at?: number;
  expired_at?: number;
  merchant_name?: string;
}

interface JcbBlockTransaction {
  amount: string;
  amount_in_usd: string;
  block_hash: string;
  blockchain: string;
  calculated_fee: string;
  currency: string;
  destination_address: string;
  id: string;
  p_created_at: string;
  source_address: string;
  card_no: string;
}

interface JcbCardTransaction {
  calculated_fee: string;
  card_no: string;
  final_local_amount: string;
  id: string;
  local_amount: string;
  local_currency: string;
  merchant_city: string;
  merchant_country: string;
  merchant_id: string;
  merchant_name: string;
  p_created_at: string;
  status: string;
  transaction_amount: string;
  transaction_currency: string;
  type: string;
}

interface JcbExpressAdvice {
  express_no: string;
  express_company: string;
  card_no: string;
}

interface JcbCardToCard {
  from_card_no?: string;
  to_card_no?: string;
  status?: string;
  fail_reason?: string;
  amount?: string;
  currency?: string;
  water_no?: string;
}

interface JcbMobileAdvice {
  card_no: string;
  old_mob_no: string;
  old_mob_no_of: string;
  new_mob_no: string;
  new_mob_no_of: string;
}

interface JcbEmailAdvice {
  card_id: string;
  card_no: string;
  card_status: number;
  old_email: string;
  new_email: string;
}

interface JcbCardNoAdvice {
  card_id: string;
  old_card_no: string;
  new_card_no: string;
  card_status: number;
}

interface JcbApplyEditAdvice {
  water_no: string;
  first_name?: string;
  last_name?: string;
  en_name?: string;
  birthday?: string;
  cert_id?: string;
  cert_start_date?: string;
  cert_end_date?: string;
  address?: string;
}

成功响应与失败处理

商户完成验签并成功接收回调后返回：

{
  "code": 0,
  "msg": "success"
}

code 必须为数字 0。非 0、网络错误或响应超时会被记录为回调失败。

​接入方式

​处理流程

​回调索引

​申请状态

​卡状态变更

​3DS 验证码

​链上充值

​卡片消费

​物流信息

​卡对卡转账

​手机号变更

​邮箱变更

​卡号变更

​申请资料变更

​TypeScript 类型参考

​成功响应与失败处理

接入方式

处理流程

回调索引

申请状态

卡状态变更

3DS 验证码

链上充值

卡片消费

物流信息

卡对卡转账

手机号变更

邮箱变更

卡号变更

申请资料变更

TypeScript 类型参考

成功响应与失败处理