Ksher 开时支付

Ksher API 文档

本文档仅供已签约 / 洽谈中的机构客户查阅，请输入访问口令。

口令不正确
未获取口令？请联系您的客户经理。
← 返回机构业务介绍
⚠️ 本文档为机密材料，仅限已授权的机构客户内部使用，请勿外传或公开分享。

Ksher API 文档

面向机构客户的跨境资金 API，覆盖 B2B 收款与跨境分发（开时优享汇 · Ksher PrimePay）两条业务线。

1概述

Ksher 机构业务 API，覆盖 B2B 收款与跨境分发（开时优享汇 · Ksher PrimePay）两条业务线。所有接口均为 POST 请求，Content-Type: application/json。

测试环境 Base URL

B2B 收款https://uat-openapi.ksher.cn
跨境分发（KPP）https://uat-openapi.ksher.cn/new
生产环境地址、鉴权方案与接入凭证由 Ksher 在开通时单独提供，本文档不含鉴权细节。

2接入流程

从商务洽谈到正式上线，共四步。

01
商务洽谈与方案确认
明确业务场景、覆盖币种与接入范围，确认整体方案。
02
开通与授权
由 Ksher 完成机构开通，并提供接入所需的凭证与联调支持。
03
沙箱联调
在 UAT 环境完成全链路联调测试。
04
上线
切换生产环境地址，正式发布。

3请求与响应规范

所有接口共用同一套响应外层结构。

字段类型必填说明
codeString是成功返回 SUCCESS
messageString是接口调用信息描述
dataObject否调用成功时返回的业务内容
timestampString是ISO8601 格式
响应示例
{
  "code": "SUCCESS",
  "message": "success",
  "data": {
    "merchant_id": "xxx",
    "source_currency": "JPY",
    "target_currency": "CNY",
    "base_currency": "JPY",
    "reference_rate": "0.04268308",
    "expiration_date": "2026-06-16T07:15:00.000Z"
  },
  "timestamp": "2026-06-16T15:03:32+08:00"
}
后续接口的响应字段均在 data 内，外层 code / message / timestamp 不再重复列出。

4API 接口

两条业务线的接口清单。切换下方标签查看对应业务线的全部接口，所有接口均为 POST 请求。

Base URL：https://uat-openapi.ksher.cn（UAT）。以下接口均为 POST。
商户注册 Registration
POST
Merchant Registration
商户注册
/global/v2/merchant/registration/create
POST
Merchant Registration Query
注册结果查询
/global/v2/merchant/registration/query
回调
Merchant Registration Notification
注册结果回调
回调地址由商户在注册接口的 callback_url 提供
虚拟账户 Virtual Account
POST
Virtual Account Opening
VA 开户
/global/v2/virtual_account/opening
POST
Virtual Account Opening Query
VA 开户查询
/global/v2/virtual_account/query
回调
Virtual Account Opening Notification
VA 开户回调
回调地址由开户申请中的 callback_url 提供
来账 Incoming Payment
回调
Incoming Payment Notification
资金到账通知
商户提供的到账通知 URL
POST
Incoming Payment Query
来账查询
/global/v2/incoming_payment/query
余额 Merchant Balance
POST
Merchant Balance Query
余额查询
/global/v2/balance/query
POST
Merchant Balance Detail
余额动账明细
/global/v2/balance/detail
来账退款 Incoming Refund
POST
Incoming Refund
发起退款
/global/v2/incoming/refund/apply
POST
Incoming Refund Query
退款查询
/global/v2/incoming/refund/query
回调
Incoming Refund Notification
退款结果回调
商户提供的回调 URL
贸易订单 Trade Orders
POST
Order Create
创建订单
/global/v2/trade/order/create
POST
Order Query
订单查询
/global/v2/order/query
POST
Order Update
更新订单
/global/v2/trade/order/update
POST
Order Associate
订单关联
/global/v2/trade/order/associate
POST
Order Associate Query
关联查询
/global/v2/trade/order/associated/query
POST
Order Associate Resubmit
关联重提
/global/v2/trade/order/associated/resubmit
POST
Order Associate Revoke
撤销关联
/global/v2/trade/order/associated/revoke
回调
Order Associate Notification
关联结果回调
商户提供的回调 URL
POST
Logistics Update
物流信息更新
/global/v2/trade/logistics/update
汇款 Remittance
POST
Remittance Initiate
发起汇款
POST
Remittance Query
汇款查询
回调
Remittance Notification
汇款结果回调
外汇 FX
POST
FX Rate Query
实时汇率查询
/global/v2/fx/rate/query
POST
FX Rate Quotation
汇率报价
/global/v2/fx/rate/quotation
POST
FX Rate Order
锁汇下单
/global/v2/fx/rate/order
POST
FX Order Query
换汇订单查询
/global/v2/fx/order/query
回调
FX Rate Order Notification
换汇结果回调
/global/v2/fx/order/notification

5错误码

全局错误码

Code说明
SYSTEM_ERRORSystem Error
PARAMETER_ERROR请求头 / 请求体校验失败，业务参数校验失败
INVALID_SIGNATURE签名校验失败
INVALID_REQUEST重复请求，鉴权失败
BUSINESS_ERROR业务执行失败

付款 / 换汇相关错误码

Code说明
UNKNOWN_EXCEPTION系统异常，请稍后重试
MERCHANT_NOT_EXIST换汇下单的商户不存在
MERCHANT_ERROR非法的商户编号
CONFIRM_ORDER_MERCHANT_MISMATCH下单商户与费用计算商户不一致
TRANSACTION_EXPIRED汇率报价时间已过期，交易超时失败
PARAM_ILLEGAL买卖币种信息缺失 / 下单币种与汇率报价币种不匹配
UNCLEAR_TRANSACTION_AMOUNT卖出或买入金额四舍五入后 ≤ 0，视为无金额参数
AMOUNT_LESS_THAN_LIMIT交易金额低于最小限额
AMOUNT_MORE_THAN_LIMIT交易金额超过最大限额
RATE_CHANGE_OVER_THRESHOLD汇率波动风险，交易失败
RATE_NOT_FOUND未匹配到有效汇率
DATA_DUPLICATE_ERROR重复交易
FEE_CALCULATE_ERROR手续费计算失败

6附录

金额系数

所有金额均为 Integer 类型，按最小单位传参。使用方式：金额 / 金额系数 = 元

金额系数适用币种
100 USDCNYTHBSGDMYRPHPHKDEURGBP
1 VNDIDRJPYKRW
示例：用户输入 0.01 USD → 0.01 × 100 = 1 → 传参 1。

时间格式

除特殊说明外，所有时间字段均为 ISO8601 格式。

时间示例
2023-10-20T16:19:57+08:00
© Ksher 开时支付 · 机构业务 API 文档（机密）
生产环境地址、鉴权方案与接入凭证请通过客户经理获取。