> ## Documentation Index
> Fetch the complete documentation index at: https://developer.speedpay.hk/llms.txt
> Use this file to discover all available pages before exploring further.

# JCB 回调

> 接收 JCB 申请、卡状态、3DS、交易、物流、卡对卡和资料变更通知。

JCB Webhook 会推送到商户在 SpeedPay 商户平台 API KEY 中配置的 HTTPS 回调地址。所有 JCB 回调使用统一外层结构：`api_name` 标识回调类型，且每次只会填充一个对应的业务对象。

## 请求头

| Header          | 说明                               |
| --------------- | -------------------------------- |
| `Content-Type`  | 固定为 `application/json`           |
| `Authorization` | SpeedPay 使用平台私钥对完整 JSON 请求体生成的签名 |

商户需要使用 SpeedPay 公钥验签。验签通过后再处理业务数据。

## 返回示例

```json theme={null}
{
  "code": 0,
  "msg": "success"
}
```

`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`  |

## Webhook 结构体

```ts theme={null}
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;
}
```

## 字段说明

| 字段                     | 说明                   |
| ---------------------- | -------------------- |
| `app_id`               | 商户应用 ID              |
| `api_name`             | 回调类型                 |
| `water_no`             | 商户侧业务流水号             |
| `card_no`              | 卡号，可能为脱敏卡号           |
| `status`               | 申请、交易或转账状态，按对应业务类型解释 |
| `card_status`          | 平台卡状态，参考卡状态附录        |
| `transaction_opt_code` | 3DS 验证码信息            |
| `block_transaction`    | 链上充值信息               |
| `transaction`          | 卡片消费信息               |
| `jcb_card_to_card`     | 卡对卡转账结果              |
| `jcb_card_no`          | 换卡后的新旧卡号映射           |

## 请求示例

### 申请状态

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

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

### 卡状态变更

```json theme={null}
{
  "api_name": "jcb_card_status_change",
  "app_id": "mc-bEreOeGNrHju78Gyd",
  "jcb_card_status": {
    "card_no": "356772******6942",
    "card_status": 6
  }
}
```

### 3DS 验证码

```json theme={null}
{
  "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"
  }
}
```

### 链上充值

```json theme={null}
{
  "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"
  }
}
```

### 卡片消费

```json theme={null}
{
  "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"
  }
}
```

`status` 可能为 `Authorized`、`Declined`、`Settled`、`Reversed`。`type` 可能为 `Sales`、`Refund`、`Withdrawal`。

### 物流信息

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

### 卡对卡转账

```json theme={null}
{
  "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"
  }
}
```

### 手机号变更

```json theme={null}
{
  "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"
  }
}
```

### 邮箱变更

```json theme={null}
{
  "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"
  }
}
```

### 卡号变更

```json theme={null}
{
  "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
  }
}
```

### 申请资料变更

```json theme={null}
{
  "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"
  }
}
```