4、还款（Repayment）

4.1 还款接口（Repayment interface）

URL：
https://${domain}/api/pay/order
请将 ${domain} 替换为你的实际服务域名。

请求方式： POST

Content-Type： application/json

接口说明：
该接口用于发起还款请求，包括商户信息、订单详情、用户信息、回调地址等参数。

---

请求参数（Body-parameters）

参数名	类型	限制	必填	说明
mchNo	string	32	true	商户号
appId	string	32	true	应用 ID
mchOrderNo	string	32	true	商户订单号
amount	Long	20	true	还款金额（单位：“分”，最小值 10000，10000等于100泰铢）
subject	string	256	false	商品名称
body	string	512	false	商品描述
notifyUrl	string	256	true	还款结果回调地址
successUrl	string	256	false	还款成功跳转地址
failUrl	string	256	false	还款失败跳转地址
cancelUrl	string	256	false	用户取消还款的跳转地址
expiredTime	Int	11	true	还款有效时间（单位"秒"，例：600）
userName	string	256	true	用户姓名
userEmail	string	256	false	用户邮箱
userPhone	string	32	true	用户手机号 （泰国10位 例：0814911416）
userAddress	string	256	false	用户地址
transAccNo	string	256	false	银行帐户
bankCode	string	32	false	银行编码（code）
sign	string	256	true	签名
reqTime	Int	11	true	请求时间戳（单位秒）

---

请求示例（Request-example）

{
  "mchNo": "M1735112701",
  "appId": "676bb7fefb715596544e2210",
  "mchOrderNo": "PAYIN_TEST_0003",
  "amount": 10000,
  "subject": "test",
  "body": "test",
  "notifyUrl": "http://domain.com/notify",
  "successUrl": "http://domain.com",
  "failUrl": "http://domain.com",
  "cancelUrl": "http://domain.com",
  "expiredTime": 600,
  "userName": "ลำดวนการะพิน",
  "userEmail": "test@gmail.com",
  "userPhone": "0814911416",
  "userAddress": "test",
  "sign": "81091A7D02A78F97E44645C60170D1E6",
  "reqTime": 1739413509
}

TIP

•用户资料真实性：必须提供用户的真实姓名、手机号、邮箱等。缺失或虚假资料将导致还款失败。

•所有字符串类型字段都需要确保它们不超过指定的最大长度。

•amount 单位为"分"，最小值为 10000（即 100 泰铢）。

•sign 按签名算法生成，以保证数据的安全性和完整性。

•使用HTTPS协议发送请求，保证数据传输的安全。

•还款时效：二维码有效期为 10–15 分钟。系统不会发生补单情况，超过有效期后二维码将自动失效。

•字段限制：expiredTime 最大值为 600 秒。

•账单收款地址：收款方账户为公司主体，不使用个人姓名。

•银行账户说明：所指银行账户并非用户的银行卡号，请参考以下示例：

4.2 还款结果（Payment result）

响应格式： application/json

说明：
此接口返回还款结果，包括还款状态、订单信息及签名等字段。

响应字段（Response-fields）

字段名	类型	说明
code	Int	调用结果：0 表示成功（success），其余表示失败（error）
data	Object	包含具体的数据信息
msg	string	结果描述
sign	string	签名，用于验证数据的完整性和真实性

data 对象字段

字段名	类型	说明
codeImgUrl	string	还款地址（二维码图片 code 地址需要转成二维码）
mchOrderNo	string	商户订单号
orderState	Int	还款状态：0-已生成订单、1-正在还款、2-还款成功、3-还款失败、4-已取消、5-已退款、6-订单已关闭
payOrderId	string	商户订单号

repay 对象

字段名	类型	说明
codeImgUrl	string	还款地址（二维码图片 code 地址需要转成二维码）
payUrl	string	跳转还款地址
codeUrl	string	还款地址（二维码图片地址/链接）
formContent	string	表单内容

响应示例（Response-example）

{
  "code": 0,
  "data": {
    "codeImgUrl": "https://www.moneyspace.net/gbprimepay/qr?transactionId=MSTRF180000003838890",
    "mchOrderNo": "PAYIN_TEST_0003",
    "orderState": 1,
    "payOrderId": "P1889871204554084354"
  },
  "msg": "SUCCESS",
  "sign": "5C74AEE2C069A66690501E6AB8FD0B9C"
}

字段说明（Field details）

字段说明

•code：

•类型：Int

•说明：调用结果状态码。

0 表示成功，其余值表示不同的错误码。

•data：

•类型：Object

•说明：包含具体业务数据。

•codeImgUrl：还款二维码图片 code 地址需要转成二维码。
用户可以通过扫描二维码完成还款。

•mchOrderNo：商户自定义订单号。

•orderState：当前订单的还款状态。
具体状态值如上表所示。

•payOrderId：还款系统生成的唯一订单号。

•msg：

•类型：String

•说明：结果的文本描述，成功通常为 "SUCCESS"，失败则为具体错误信息。

•sign：

•类型：String

•说明：用于验证响应数据真实性和完整性的签名。
接收方需要根据相同的签名算法对返回数据进行签名验证。

还款结果处理（Payment results）

•接收到响应后，务必验证 sign 字段，确保数据未被篡改。

•根据 orderState 的值判断当前订单还款状态，并执行相应的业务逻辑处理。

•建议使用 HTTPS 协议以保证数据传输安全。

本说明文档可以帮助开发者理解并正确处理 API 接口响应。若有更多细节或特殊情况需要说明，请提供相关补充信息。

4.3 还款通知（Repayment Notify）

4.3.1、还款通知接口（Repayment Notify interface）

类型（Type）：POST

内容类型（Content-Type）：application/json

接口说明： 本接口用于通知还款结果，包括商户信息、订单状态和用户信息等参数。

Body-parameters:

参数名	类型	说明
amount	BigDecimal	还款金额（单位：“分”，最小值 10000，10000等于100泰铢）
payOrderId	string	应用系统订单 ID
code	Integer	还款状态码（4.success成功 2.error失败）
mchOrderNo	string	商户唯一订单号
subject	string	商品名称
sign	string	验证用签名
reqTime	string	请求时间戳
createdAt	string	订单创建时间戳
state	Integer	还款状态（Payment Status:0-订单生成 1-还款中 2-还款成功 3-还款失败 4-已取消 5-已退款 6-订单关闭）

请求示例（Request-example）：

{
    "amount": 210800,
    "payOrderId": "P1889977259465543682",
    "code": "success",
    "mchOrderNo": "R1655T1737554677110",
    "subject": "",
    "sign": "F83542B538F7DB47EE53D0D2C6B866F4",
    "reqTime": 1739441025205,
    "createdAt": 1739440681615,
    "state": 2
}

4.3.2、成功接收响应（Successfully received the response）

描述: 成功接收，请返回 SUCCESS。

•sign:

•类型: String

•说明: 用于验证响应的真实性和完整性的数据签名。接收方需要基于相同的签名算法对返回的数据进行签名验证。