mojiahui/webman-buildadmin
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3a2af4d7c2189984eac7bb671e0318dae8ba5ebd
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

12 KiB
Raw Blame History

DDPay 支付网关接口对接文档

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

目录

    1. 概述（Overview）
    1. 认证与安全（Authentication & Security）
    1. 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）
    1. 返回码（Response Codes）
    1. 附录
    • 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