## DDPay 支付网关接口对接文档

> 文档名称：DDPay Payment Gateway  
> 版本：1.1.0（文末“Document Version”标注为 1.1.2；文件命名为 v1.1.3）  
> 最后更新：2026-03-20  
> 版权：© 2025 DDPay

## 目录

- 1. 概述（Overview）
- 2. 认证与安全（Authentication & Security）
- 3. API 接口（API Endpoints）
  - 3.1 入金发起（Deposit Initiation）
  - 3.2 出金发起（Payout Initiation）
  - 3.3 入金状态查询（Deposit Status Inquiry）
  - 3.4 出金状态查询（Payout Status Inquiry）
  - 3.5 Webhook 回调（Webhook Notifications）
- 4. 返回码（Response Codes）
- 5. 附录
  - 5.1 入金银行列表（MYR）
  - 5.2 出金银行列表（MYR）
  - 5.3 入金银行列表（THB）

## 1. 概述（Overview）

### 1.1 目的

本文件提供与 DDPay Payment Gateway API 集成的完整技术规范，涵盖：

- 请求/响应字段结构
- 认证机制
- 集成协议（包括签名与回调处理）

### 1.2 术语（Terminology）

| 术语 | 定义 |
|---|---|
| Merchant Account | 允许通过 DDPay 处理交易的已注册商户主体 |
| Client ID | 每个商户在平台注册时分配的唯一标识 |
| API Secret | 用于请求认证与签名校验的保密密钥 |

## 2. 认证与安全（Authentication & Security）

### 2.1 通信协议（Communication Protocol）

- 传输方式：`HTTPS POST` 请求
- Content-Type：`application/json`
- 字符编码：`UTF-8`
- 响应格式：`JSON`

要求：

- 所有 API 通信必须使用安全 HTTPS。
- 发起交易接口由平台提供同步响应；最终交易状态需要通过“状态查询接口”或“状态回调（Webhook）”确认。

### 2.2 请求签名（Request Signing）

DDPay 使用加密签名以保证请求的真实性与数据完整性。签名算法为 **MD5**，流程如下：

1. 收集请求参数（**不包含**签名字段本身）
2. 按参数 key 名进行字典序排序（ASCII 顺序）
3. 将所有 `key=value` 使用字符 `&` 连接（中间用 `&` 分隔）
4. 在末尾追加：`&key=YOUR_API_SECRET`
5. 对得到的字符串执行 `MD5`
6. 将 MD5 哈希结果转为小写
7. 将该哈希值填入签名字段

重要注意：

- **空值或 null 参数值应排除在签名计算之外**。

## 3. API 接口（API Endpoints）

> 生产环境的 Endpoint URL：请联系商户支持获取。

### 3.1 入金发起（Deposit Initiation）

目的：提交一笔新的支付入金请求  

- HTTP Method：`POST`
- Endpoint URL：联系商户支持获取生产地址

#### 请求参数（Request Parameters）

| 参数 | 描述 | 类型 | 必填 | 备注 |
|---|---|---|---|---|
| `client_id` | 商户账号标识 | String | 是 | onboarding 提供 |
| `order_id` | 交易唯一引用号 | String | 是 | 每笔交易必须唯一 |
| `payment_type` | 支付方式选择 | String | 是 | `01`=FPX，`02`=duitnow，`03`=ewallet；其他请咨询获取 |
| `transaction_amount` | 支付金额 | Decimal | 是 | 币种：MYR |
| `payer_name` | 付款账户持有人姓名 | String | 是 | 按银行登记信息 |
| `payer_bank[name]` | 付款银行名称 | String | 是 | 请参考银行列表获取全称 |
| `callback_url` | 异步通知地址 | String | 是 | 必须使用 HTTPS 协议 |
| `redirect_url` | 用户返回地址 | String | 是 | 必须使用 HTTPS 协议 |
| `signature` | 请求认证签名哈希 | String | 是 | 小写字母数字 MD5 |

#### 响应参数（Response Parameters）

| 参数 | 描述 | 类型 | 条件/备注 |
|---|---|---|---|
| `status_code` | 操作结果指示 | Integer | 非 0 表示失败 |
| `status_message` | 可读状态说明 | String | 永远返回 |
| `details` | 失败细节（如适用） | String | 仅失败时适用 |
| `client_id` | 商户标识回显 | String | 成功时回显 |
| `order_id` | 入金订单号回显 | String | 成功时回显，用于关联 |
| `transaction_amount` | 支付金额确认 | Decimal | 成功时在配置币种下返回 |
| `transaction_status` | 当前处理状态 | String | 成功时返回；参考“状态码” |
| `payment_url` | 支付界面 URL | String | 成功时返回，跳转到该 URL 完成支付 |
| `timestamp` | 响应生成时间 | DateTime | ISO 8601 |
| `signature` | 响应校验签名哈希 | String | 成功时返回（使用同方法校验） |

### 3.2 出金发起（Payout Initiation）

目的：提交一笔新的出金请求  

- HTTP Method：`POST`
- Endpoint URL：联系商户支持获取生产地址

#### 请求参数（Request Parameters）

| 参数 | 描述 | 类型 | 必填 | 备注 |
|---|---|---|---|---|
| `client_id` | 商户账号标识 | String | 是 | onboarding 提供 |
| `bill_number` | 交易唯一引用号 | String | 是 | 每笔出金请求必须唯一 |
| `amount` | 出金金额 | Decimal | 是 | 币种：配置币种 |
| `receiver_name` | 收款账户持有人姓名 | String | 是 | 按银行登记信息 |
| `receiver_account` | 收款账户号/手机号 | String | 是 | 按银行登记信息 |
| `bank[name]` | 银行名称 | String | 是 | 请参考银行列表获取全称 |
| `bank_branch` | 银行支行名称 | String | 是 | 若缺失则默认值为 `N/A` |
| `callback_url` | 异步通知地址 | String | 是 | 必须使用 HTTPS 协议 |
| `signature` | 请求认证签名哈希 | String | 是 | 小写字母数字 MD5 |

#### 响应参数（Response Parameters）

| 参数 | 描述 | 类型 | 条件/备注 |
|---|---|---|---|
| `status_code` | 操作结果指示 | Integer | 非 0 表示失败 |
| `status_message` | 可读状态说明 | String | 永远返回 |
| `details` | 失败细节（如适用） | String | 仅失败时适用 |
| `client_id` | 商户标识回显 | String | 成功时回显 |
| `bill_number` | 出金订单号回显 | String | 成功时回显，用于关联 |
| `transaction_amount` | 出金金额确认 | Decimal | 成功时在配置币种下返回 |
| `transaction_fee` | 出金手续费 | Decimal | 成功时在配置币种下返回 |
| `transaction_total` | 出金总金额 | Decimal | 成功时在配置币种下返回 |
| `transaction_status` | 当前处理状态 | String | 成功时返回；参考“状态码” |
| `timestamp` | 响应生成时间 | DateTime | ISO 8601 |
| `signature` | 响应校验签名哈希 | String | 成功时返回（使用同方法校验） |
| `remark` | 出金备注 | String | 成功时回显（文档描述为 OK 状态下返回） |

### 3.3 入金状态查询（Deposit Status Inquiry）

目的：查询已提交入金的当前状态  

- HTTP Method：`POST`

#### 请求参数（Request Parameters）

| 参数 | 描述 | 类型 | 必填 | 备注 |
|---|---|---|---|---|
| `client_id` | 商户账号标识 | String | 是 |  |
| `order_id` | 入金订单号/交易引用 | String | 是 | 原始订单标识 |
| `query_time` | 请求时间戳 | DateTime | 是 | 格式：`YYYY-MM-DD HH:MM:SS` |
| `signature` | 请求认证签名哈希 | String | 是 |  |

#### 响应参数（Response Parameters）

| 参数 | 描述 | 类型 | 条件/备注 |
|---|---|---|---|
| `status_code` | 查询结果指示 | Integer | 永远返回 |
| `status_message` | 查询结果说明 | String | 永远返回 |
| `client_id` | 商户标识回显 | String | 成功时回显 |
| `order_id` | 订单号回显 | String | 成功时回显 |
| `transaction_amount` | 支付金额 | Decimal | 成功时在配置币种下返回 |
| `transaction_status` | 当前处理状态 | String | 参考“状态码” |
| `timestamp` | 响应时间 | DateTime | 仅返回 ISO 8601 |
| `signature` | 响应校验签名哈希 | String | 成功时返回（使用同方法校验） |

### 3.4 出金状态查询（Payout Status Inquiry）

目的：查询已提交出金的当前状态  

- HTTP Method：`POST`

#### 请求参数（Request Parameters）

| 参数 | 描述 | 类型 | 必填 | 备注 |
|---|---|---|---|---|
| `client_id` | 商户账号标识 | String | 是 |  |
| `bill_number` | 出金引用号 | String | 是 | 原始出金标识 |
| `signature` | 请求认证签名哈希 | String | 是 |  |

#### 响应参数（Response Parameters）

| 参数 | 描述 | 类型 | 条件/备注 |
|---|---|---|---|
| `status_code` | 查询结果指示 | Integer | 永远返回 |
| `status_message` | 查询结果说明 | String | 永远返回 |
| `client_id` | 商户标识回显 | String | 成功时回显 |
| `bill_number` | 出金引用号回显 | String | 成功时回显 |
| `transaction_amount` | 出金金额 | Decimal | 成功时在配置币种下返回 |
| `transaction_fee` | 出金手续费 | Decimal | 成功时在配置币种下返回 |
| `transaction_total` | 出金总金额 | Decimal | 成功时在配置币种下返回 |
| `transaction_status` | 当前处理状态 | String | 参考“状态码” |
| `remark` | 出金备注 | String | 成功时回显 |
| `timestamp` | 响应时间 | DateTime | ISO 8601 |
| `signature` | 响应校验签名哈希 | String | 成功时返回（使用同方法校验） |

### 3.5 Webhook 回调（Webhook Notifications）

目的：接收异步交易状态更新  

说明：

- 平台通过 `callback_url` 在交易状态变化时向你系统发送 `POST` 通知
- 通知发送范围：成功与失败交易都会发送
- 格式：通过 `HTTPS POST` 发送 `JSON`
- 重试机制：如果未收到确认，最多重试 6 次
- 你需要的响应：返回纯文本 `{"status":"ok"}` 并确保 HTTP 状态码为 `200`

#### 通知负载（Notification Payload）

| 参数 | 描述 | 类型 | 必填 | 备注 |
|---|---|---|---|---|
| `client_id` | 商户标识 | String | 是 |  |
| `order_id` | 交易引用号 | String | 是 |  |
| `transaction_status` | 最终状态 | String | 是 | 参考状态码 |
| `timestamp` | 通知时间 | DateTime | 是 |  |
| `transaction_amount` | 支付金额 | Decimal | 是 | 配置币种下返回 |
| `signature` | 通知校验签名哈希 | String | 是 | 处理前必须校验签名 |

#### 集成要求（Implementation Requirements）

- 在处理 webhook 之前先验证签名
- 收到后应立刻响应纯文本 `{"status":"ok"}`（HTTP 200）
- 使用 HTTPS endpoint，并确保 SSL 证书有效

## 4. 返回码（Response Codes）

### 4.1 入金状态值（Deposit Status Values）

| 状态码 | 描述 | 最终状态 | 是否需要操作 | 处理建议 |
|---|---|---|---|---|
| `pending` | 交易正在处理中 | 否 | 否 | 无需调用轮询接口或等待通知 |
| `completed` | 交易成功 | 是 | 是 | 履约订单/服务（fulfill order/service） |
| `failed` | 交易失败 | 是 | 是 | 通知客户，可选允许重试（allow retry） |

> 文档中 `transaction_status` 建议参考本节状态码定义。

## 5. 附录（Appendices）

### 5.1 入金银行列表（MYR）

- `pbb` : Public Bank
- `br` : Bank Rakyat
- `alb` : Alliance Bank
- `mbb` : Maybank2U
- `bi` : Bank Islam
- `bm` : Bank Muamalat
- `afb` : Affin Bank
- `rhb` : RHB Bank
- `ocbc` : OCBC Bank
- `scb` : Standard Chartered
- `hlb` : Hong Leong Bank
- `uob` : UOB Bank
- `cimb` : CIMB Clicks
- `amb` : AmBank
- `bsn` : Bank Simpanan Nasional
- `hsbc` : HSBC Bank
- `cob` : Bank of China

### 5.2 出金银行列表（MYR）

> 与入金 MYR 银行列表一致

- `pbb` : Public Bank
- `br` : Bank Rakyat
- `alb` : Alliance Bank
- `mbb` : Maybank2U
- `bi` : Bank Islam
- `bm` : Bank Muamalat
- `afb` : Affin Bank
- `rhb` : RHB Bank
- `ocbc` : OCBC Bank
- `scb` : Standard Chartered
- `hlb` : Hong Leong Bank
- `uob` : UOB Bank
- `cimb` : CIMB Clicks
- `amb` : AmBank
- `bsn` : Bank Simpanan Nasional
- `hsbc` : HSBC Bank
- `cob` : Bank of China
- `tng` : Touch & Go

### 5.3 入金银行列表（THB）

- `105` : BANK OF THAILAND
- `106` : BANGKOK BANK PUBLIC COMPANY LTD.
- `107` : KASIKORNBANK PUBLIC COMPANY LIMITED
- `108` : KRUNG THAI BANK PUBLIC COMPANY LTD.
- `109` : TMB THANACHART BANK PUBLIC COMPANY LIMITED
- `110` : SIAM COMMERCIAL BANK PUBLIC COMPANY LTD.
- `111` : CITIBANK, N.A.
- `112` : STANDARD CHARTERED BANK (THAI) PUBLIC COMPANY LIMITED
- `113` : CIMB THAI BANK PUBLIC COMPANY LIMITED
- `114` : UNITED OVERSEAS BANK (THAI) PUBLIC COMPANY LIMITED
- `115` : BANK OF AYUDHYA PUBLIC COMPANY LTD.
- `116` : GOVERNMENT SAVINGS BANK
- `117` : THE GOVERNMENT HOUSING BANK
- `118` : BANK FOR AGRICULTURE AND AGRICULTURAL COOPERATIVES
- `119` : BANK OF CHINA (THAI) PUBLIC COMPANY LIMITED
- `120` : ISLAMIC BANK OF THAILAND
- `121` : KIATNAKIN PHATRA BANK PUBLIC COMPANY LIMITED
- `122` : INDUSTRIAL AND COMMERCIAL BANK OF CHINA (THAI) PUBLIC COMPANY LIMITED
- `123` : LAND AND HOUSES BANK PUBLIC COMPANY LIMITED
- `158` : TISCO BANK PUBLIC COMPANY LIMITED
- `357` : RHB BANK BERHAD
- `358` : INDIAN OVERSEA BANK
- `359` : ANZ BANK (THAI) PUBLIC COMPANY LIMITED