Endpoints

系统为商户提供 2 个接口

orgId 和 merchantId 会在申请开通服务时由服务提供商颁发，无需自行创建

创建收款请求（Pay-In）

POST https://api.please-payment.com/api/PaymentRequest/org/{orgId}/action/SubmitPayInRequest/{merchantId}

创建 Payment Request 并返回 QR Code，供客户扫描并将资金直接转入商户账户。

Request Body

Field	Type	Required	说明
`RefId1`	string	✅	商户提供的 Reference ID（必须唯一）
`RefId2`	string	❌	附加参考字段 2
`RefId3`	string	❌	附加参考字段 3
`PayerName`	string	✅	付款人姓名
`RequestedAmount`	number	✅	金额（必须大于 0，且在商户设定的范围内）
`Currency`	string	✅	货币 —— 目前仅支持 `THB`
`QrProvider`	string	✅	发行 QR 的银行 —— `PP`（PromptPay）或 `SCB`
`Description`	string	❌	交易说明
`CustomerEmail`	string	❌	客户邮箱
`CustomerPhone`	string	❌	客户电话号码
`Tags`	string	❌	用于分组交易的标签

请求示例

{
  "RefId1": "ORDER-20260701-001",
  "PayerName": "Somchai Jaidee",
  "RequestedAmount": 325,
  "Currency": "THB",
  "QrProvider": "PP",
  "Description": "商品付款",
  "RefId2": "CUST-12345"
}

Response

{
  "status": "OK",
  "description": "Success",
  "paymentResponse": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "sessionId": "session-abc123",
    "type": "PayIn",
    "status": "Pending",
    "requestedAmount": 325.00,
    "generatedAmount": 325.52,
    "currency": "THB",
    "qrCode": "00020101021...",
    "qrCodeImage": "data:image/png;base64,...",
    "paymentUrl": "https://...",
    "websocketPath": "/realtime/payment-tx",
    "createdAt": "2026-07-01T10:00:00Z",
    "expireAt": "2026-07-01T10:15:00Z",
    "isQrAvailable": true,
    "payInBankCode": "SCB",
    "payInBankAccountNo": "xxx-xxxxx-x",
    "payInBankAccountName": "公司名称",
    "payInPromptPayId": null,
    "slipUploadUrl": "/payin-slip-upload/org123/3fa85f64-5717-4562-b3fc-2c963f66afa6/a1b2c3d4-..."
  }
}

Response Fields

Field	说明
`id`	Payment Request 的 UUID —— 请保存以便查询
`status`	当前状态（参见支付状态）
`requestedAmount`	请求的金额
`generatedAmount`	实际应支付的金额（可能包含随机小数以便匹配）
`isQrAvailable`	`true` 表示 QR Code 已就绪，可供客户扫描；`false` 表示目标账户不支持 QR（例如未绑定 PromptPay）—— 详见下文
`qrCodeImage`	Base64 格式的 QR Code 图片 —— 可直接在 App 中显示（当 `isQrAvailable` 为 `false` 时为空）
`payInBankCode`	目标银行代码
`payInBankAccountNo`	目标账号
`payInBankAccountName`	目标账户名称
`payInPromptPayId`	目标 PromptPay 号码（如有）
`sessionId`	用于通过 WebSocket 连接以接收实时状态
`websocketPath`	WebSocket 的路径（`/realtime/payment-tx`）
`expireAt`	QR Code 的过期时间
`slipUploadUrl`	回单上传页面的相对路径 —— 不含域名前缀，需自行拼接 `https://merchant.please-payment.com`（详见下文说明）以生成完整 URL，再提供给客户打开回单上传页面，无需登录

重要 —— 应拼接哪个域名： slipUploadUrl 仅为相对路径，需自行拼接 https://merchant.please-payment.com 域名。例如若 slipUploadUrl 为 /payin-slip-upload/org123/xxx/yyy，则完整 URL 应为 https://merchant.please-payment.com/payin-slip-upload/org123/xxx/yyy

QR 与账户信息的展示方式

展示前应始终先检查 isQrAvailable：

场景	展示方式
`isQrAvailable = true`	照常展示 `qrCodeImage` 中的 QR Code 供客户扫描
`isQrAvailable = false`	没有 QR Code —— 展示账户信息（`payInBankCode`、`payInBankAccountNo`、`payInBankAccountName`、`payInPromptPayId`）供客户自行填写转账信息

提示： 建议始终将账户信息（payInBankCode、payInBankAccountNo、payInBankAccountName、payInPromptPayId）与 QR Code 一并展示 —— 部分客户即使有 QR Code 也可能希望手动转账

建议： 将 slipUploadUrl 生成为 QR Code 并展示在支付页面中 —— 客户用手机摄像头扫描后即可直接打开回单上传页面，无需手动输入 URL。适用于普通 Pay-In 和 Pay-In P2P

回单上传页面

当客户打开 Slip Upload URL 时，会看到该 Payment Request 对应的回单上传页面，具有以下功能：

上传回单图片 —— 从手机相机或相册中选择图片
回单参考号 —— 输入回单参考号（字母数字）的前 4 位和后 4 位，用于匹配及重复检测
备注 —— 可选的附加说明字段
重复回单检测 —— 若系统中已存在相同参考号的回单，会自动发出警告

Upload Payment Slip

上传转账回单

Select a payment slip image to upload

Tap to select image

JPG, PNG, WebP

Slip Reference (Optional)

—

First 4 digits Last 4 digits

Note (Optional)

⚠️

发现重复回单！

若发现相同参考号，系统会显示警告，并提供继续上传或取消的选项

客户无需登录即可使用此页面 —— URL 中已内嵌 token，并在 24 小时后过期

即使 HTTP status code 为 200，仍需检查 response body 中的 status 字段 —— 若为 "OK" 则表示成功，其他值表示出现错误（参见错误处理）

创建 P2P 收款请求（Pay-In P2P）

POST https://api.please-payment.com/api/PaymentRequest/org/{orgId}/action/SubmitPayInRequestP2P/{merchantId}

创建 Peer-to-Peer（P2P） 类型的 Pay-In Request —— 系统会自动将其与待处理的 Pay-Out Request 匹配，并让客户将资金直接转入收款方账户（而不是通过系统的 QR Code 转账）。

什么是 P2P？ 与资金先进入商户账户再转出不同，P2P 让付款人直接转账给收款人 —— 系统负责匹配与确认交易。

Request Body

Field	Type	Required	说明
`RefId1`	string	✅	商户提供的 Reference ID（必须唯一）
`RefId2`	string	❌	附加参考字段 2
`RefId3`	string	❌	附加参考字段 3
`PayerName`	string	✅	付款人姓名
`RequestedAmount`	number	✅	金额（必须大于 0，且在商户设定的范围内）
`Currency`	string	✅	货币 —— 目前仅支持 `THB`
`QrProvider`	string	✅	`PP` 或 `SCB`（系统内部用于匹配）
`Description`	string	❌	交易说明

请求示例

{
  "RefId1": "P2P-ORDER-20260701-001",
  "PayerName": "Somchai Jaidee",
  "RequestedAmount": 1000,
  "Currency": "THB",
  "QrProvider": "PP"
}

Response

{
  "status": "OK",
  "description": "Success",
  "paymentResponse": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "PayIn",
    "status": "Pending",
    "requestedAmount": 1000.00,
    "generatedAmount": 1000.00,
    "currency": "THB",
    "qrCode": null,
    "qrCodeImage": "",
    "isQrAvailable": false,
    "payInBankCode": "KBANK",
    "payInBankAccountNo": "012-3-45678-9",
    "payInBankAccountName": "收款方账户名称",
    "payInPromptPayId": "0812345678",
    "slipUploadUrl": "/payin-slip-upload/org123/3fa85f64-5717-4562-b3fc-2c963f66afa6/a1b2c3d4-..."
  }
}

与普通 Pay-In 的区别

	普通 Pay-In	Pay-In P2P
`isQrAvailable`	`true`（多数情况）	`false`（多数情况）—— P2P 账户通常未绑定 PromptPay
`qrCodeImage`	QR Code 图片	当 `isQrAvailable = false` 时为空（`""`）
`payInBankAccountName`	商户账户	收款方账户（来自匹配的 Pay-Out Request）
转账方式	扫描 QR Code	直接转账至 response 中指定的账户（需自行填写账户信息）
`slipUploadUrl`	✅	✅（非常重要 —— 客户必须上传回单作为凭证）

重要： 对于 P2P —— isQrAvailable 通常为 false，因为目标账户可能未绑定 PromptPay。此时必须展示账户信息（payInBankCode、payInBankAccountNo、payInBankAccountName、payInPromptPayId），以便客户自行填写转账，同时展示 slipUploadUrl 以便上传转账凭证。

重要 —— 应拼接哪个域名： slipUploadUrl 与普通 Pay-In 一样为相对路径，需自行拼接 https://merchant.please-payment.com，例如 https://merchant.please-payment.com/payin-slip-upload/org123/xxx/yyy（完整说明参见上文 Response Fields）

建议： 将 slipUploadUrl 生成为 QR Code，与目标账户信息一并展示 —— 客户转账后扫描 QR 即可直接打开回单上传页面，无需手动输入 URL（示例参见上方回单上传页面）

错误 ERROR_NO_P2P_ACCOUNT_MATCH： 若系统中没有待处理的 Pay-Out Request，将返回此错误 —— 表示当前没有可匹配的交易。

创建付款请求（Pay-Out）

POST https://api.please-payment.com/api/PaymentRequest/org/{orgId}/action/SubmitPayOutRequest/{merchantId}

创建将资金转出至目标账户的请求。

Request Body

Field	Type	Required	说明
`RefId1`	string	✅	商户提供的 Reference ID（必须唯一）
`RefId2`	string	❌	附加参考字段 2
`RefId3`	string	❌	附加参考字段 3
`RequestedAmount`	number	✅	金额（必须大于 0）
`QrProvider`	string	✅	必须为 `PP`（Pay-Out 仅支持 PromptPay）
`BankCode`	string	✅	目标银行代码，例如 `SCB`、`KBANK`、`BAY` —— 查看所有支持的代码
`BankAccountNo`	string	✅	目标账号
`BankAccountName`	string	✅	目标账户名称
`PromptPayId`	string	❌	目标 PromptPay 号码
`AccountType`	string	❌	账户类型：`Native` 或 `PromptPay`

目标账户信息：必须始终发送 BankCode+BankAccountNo+BankAccountName（见支持的银行代码），即使通过 PromptPay 转账也是如此 —— 如果同时知道目标的 PromptPay 号码，可以额外发送 PromptPayId+AccountType；也可以用 PayinBankAccountId（系统中的 ID）代替以上全部信息

建议： 若已知目标账户的 PromptPay 号码，建议一并发送 PromptPayId —— 通过 PromptPay 转账可让系统处理更快，收款方也能更快收到款项

请求示例（银行账户转账）

{
  "RefId1": "PAYOUT-20260701-001",
  "RequestedAmount": 500,
  "QrProvider": "PP",
  "BankCode": "KBANK",
  "BankAccountNo": "0123456789",
  "BankAccountName": "Somchai Jaidee",
  "AccountType": "Native"
}

请求示例（PromptPay 转账）

{
  "RefId1": "PAYOUT-20260701-002",
  "RequestedAmount": 200,
  "QrProvider": "PP",
  "PromptPayId": "0812345678",
  "AccountType": "PromptPay"
}

Response

{
  "status": "OK",
  "description": "Success",
  "paymentResponse": {
    "id": "7bc95f12-3a21-4f89-c4ed-1d852a77bfc8",
    "type": "PayOut",
    "status": "Pending",
    "requestedAmount": 500.00,
    "currency": "THB",
    "createdAt": "2026-07-01T10:05:00Z"
  }
}

创建提现请求（Withdrawal）

POST https://api.please-payment.com/api/PaymentRequest/org/{orgId}/action/SubmitWithdrawalRequest/{merchantId}

当 商户本身 需要将资金提现到自己的账户时使用此接口 —— 区别于普通 Pay-Out（将资金转给商户的客户）。系统内部会创建与 Pay-Out 完全相同的请求，只是标记为提现，以便在报表中与普通 Pay-Out 区分开来。

Request body、手续费计算方式、Response 格式和 Webhook 都与创建付款请求（Pay-Out）完全一致 —— 唯一的区别是接口路径（使用 SubmitWithdrawalRequest 而非 SubmitPayOutRequest）。上文关于 Pay-Out 的所有说明同样适用于此接口。

Request Body

与创建付款请求（Pay-Out）相同 —— RefId1、RefId2、RefId3、RequestedAmount、QrProvider，以及目标账户信息（BankCode+BankAccountNo+BankAccountName，或 PromptPayId+AccountType，或 PayinBankAccountId）。

请求示例

{
  "RefId1": "WITHDRAW-20260701-001",
  "RequestedAmount": 500,
  "QrProvider": "PP",
  "BankCode": "KBANK",
  "BankAccountNo": "0123456789",
  "BankAccountName": "Somchai Jaidee",
  "AccountType": "Native"
}

Response

{
  "status": "OK",
  "description": "Success",
  "paymentResponse": {
    "id": "7bc95f12-3a21-4f89-c4ed-1d852a77bfc8",
    "type": "PayOut",
    "status": "Pending",
    "requestedAmount": 500.00,
    "currency": "THB",
    "createdAt": "2026-07-01T10:05:00Z"
  }
}

Webhook： 没有新的事件类型 —— 提现请求仍会触发与 Webhooks 中说明相同的 PaymentOut.Success / PaymentOut.Rejected 事件，payload 字段也完全一致。

Endpoints

Endpoints

创建收款请求（Pay-In）#

Request Body#

请求示例#

Response#

Response Fields#

QR 与账户信息的展示方式#

回单上传页面#

创建 P2P 收款请求（Pay-In P2P）#

Request Body#

请求示例#

Response#

与普通 Pay-In 的区别#

创建付款请求（Pay-Out）#

Request Body#

请求示例（银行账户转账）#

请求示例（PromptPay 转账）#

Response#

创建提现请求（Withdrawal）#

Request Body#

请求示例#

Response#

创建收款请求（Pay-In）

Request Body

请求示例

Response

Response Fields

QR 与账户信息的展示方式

回单上传页面

创建 P2P 收款请求（Pay-In P2P）

Request Body

请求示例

Response

与普通 Pay-In 的区别

创建付款请求（Pay-Out）

Request Body

请求示例（银行账户转账）

请求示例（PromptPay 转账）

Response

创建提现请求（Withdrawal）

Request Body

请求示例

Response