mojiahui/webman-buildadmin
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1ba6ddd24ec08b3ed123f124ffa502d5cefaf332
webman-buildadmin/docs/DDPay Payment Gateway_v1.1.3_zh.md
zhenhui c7fc754573 1.配置新版支付模块-菜单和接口都已重构 
2.优化充值提现页面
3.菜单翻译问题
4.备份数据库
2026-04-30 11:37:46 +08:00

320 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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
Reference in New Issue View Git Blame Copy Permalink