Payments

简体中文

English

简体中文

English

主题

支付链接（Payment Link） ​

支付链接（Payment Link）是一种托管支付链接产品。商户通过 API 创建一个可分享的支付链接，并将链接发送给买家或嵌入到自己的业务流程中。买家打开链接后，在 Onerway 托管的收银台页面完成支付。

适合以下场景：

  • 无需完整开发收银台页面，只需要快速生成一次性支付链接。
  • 通过邮件、客服、社交渠道或订单详情页向买家发送支付入口。
  • 需要在后台查询支付链接的访问、支付次数和成功支付金额。
  • 需要停用不再使用的支付链接。

接口列表 ​

操作Endpoint说明
创建支付链接POST /v1/txn/paymentLink/add创建支付链接并返回 id 和 linkUrl。
查询支付链接列表POST /v1/txn/paymentLink/list按状态、关键词或创建时间分页查询支付链接。
更新支付链接状态POST /v1/txn/paymentLink/updateStatus启用或停用指定支付链接。

创建支付链接 ​

POST

使用该接口创建一个支付链接。创建成功后，响应会返回支付链接 ID 和可供买家访问的支付链接。

请求参数 ​

注意

  • 所有 JSON 字段必须在提交前进行字符串化处理
  • 嵌套对象必须序列化为 JSON 字符串格式
  • JSON 字段不能包含未转义的特殊字符
  • JSON 中的数组应该正确格式化
  • JSON 字符串字段示例：
json
{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}
ParameterTypeLengthRequiredSignedDescription

merchantNo

String

20

Yes

Yes

Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.



linkName

String

/

No

Yes

Display name of the Payment Link. Use a clear name that helps identify the link in list queries and merchant operations.

amount

BigDecimal

/

Yes

Yes

Payment amount in the specified currency.



currency

String

8

Yes

Yes

Three-letter currency code according to ISO 4217.



defaultCountry

String

/

Yes

Yes

Default country or region code used by the Payment Link checkout page.



itemName

String

/

Yes

Yes

Product or service name shown to the buyer on the Payment Link checkout page.

description

String

/

No

Yes

Product or service description shown with the Payment Link. Keep it concise and buyer-facing.

collectEmail

Boolean

/

No

Yes

Whether the Payment Link checkout page should collect the buyer email address.

collectName

Boolean

/

No

Yes

Whether the Payment Link checkout page should collect the buyer name.

sign

String

/

Yes

No

Digital signature string for request verification and security.




Please refer to Signature for signature generation method.

响应参数 ​

NameTypeDescription

respCode

String

Response code from Onerway


respMsg

String

Response message from Onerway


data

Object

Response data. Refer to object data


data ​

NameTypeDescription

id

String

Payment Link ID.


linkUrl

String

Payment Link checkout URL.


API 使用示例 ​

json
{
  "merchantNo": "800209",
  "linkName": "Membership Renewal",
  "amount": 99.99,
  "currency": "USD",
  "defaultCountry": "US",
  "itemName": "Membership",
  "description": "Annual membership renewal",
  "collectEmail": true,
  "collectName": true,
  "sign": "a1b2c3d4e5f6..."
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "id": "100",
    "linkUrl": "https://pay.example.com/payment-link/pl_100"
  }
}

查询支付链接列表 ​

POST

使用该接口分页查询支付链接。可按启用状态、关键词和创建时间筛选。

请求参数 ​

注意

  • 所有 JSON 字段必须在提交前进行字符串化处理
  • 嵌套对象必须序列化为 JSON 字符串格式
  • JSON 字段不能包含未转义的特殊字符
  • JSON 中的数组应该正确格式化
  • JSON 字符串字段示例：
json
{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}
ParameterTypeLengthRequiredSignedDescription

merchantNo

String

20

Yes

Yes

Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.



linkStatus

Integer

/

No

Yes

Payment Link status filter. 1 means enabled and 0 means disabled. Omit this field to query all links.

keywords

String

/

No

Yes

Keyword filter. Supports fuzzy matching by Payment Link ID or item name.

startTime

String

/

No

Yes

Start time for filtering Payment Links by creation time.



endTime

String

/

No

Yes

End time for filtering Payment Links by creation time.



current

Long

/

No

Yes

Page number for list queries.



size

Long

/

No

Yes

Page size for list queries.



sign

String

/

Yes

No

Digital signature string for request verification and security.




Please refer to Signature for signature generation method.

响应参数 ​

NameTypeDescription

respCode

String

Response code from Onerway


respMsg

String

Response message from Onerway


data

Object

Response data. Refer to object data


data ​

NameTypeDescription

records

Array

Payment Link records on the current page. See records for field details.

total

String

Total number of records.

size

String

Page size returned by the query.

current

String

Current page number returned by the query.

records ​

NameTypeDescription

id

String

Payment Link ID.

linkUrl

String

Payment Link checkout URL.

merchantNo

String

Merchant number assigned by Onerway.

linkName

String

Display name of the Payment Link.

amount

String

Payment Link amount.

currency

String

Payment Link currency. See ISO 4217.

defaultCountry

String

Default country or region code configured for the Payment Link.

itemName

String

Product or service name.

description

String

Product or service description.

linkStatus

Integer

Payment Link status. 1 means enabled and 0 means disabled.

createTime

String

Creation time. Format: yyyy-MM-dd HH:mm:ss.

visitCount

String

Number of visits to the Payment Link.

payCount

String

Number of successful payments completed through the Payment Link.

successAmount

String

Total successful payment amount collected through the Payment Link.

API 使用示例 ​

json
{
  "merchantNo": "800209",
  "linkStatus": 1,
  "keywords": "Membership",
  "startTime": "2026-05-01 00:00:00",
  "endTime": "2026-05-25 23:59:59",
  "current": 1,
  "size": 10,
  "sign": "a1b2c3d4e5f6..."
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "records": [
      {
        "id": "100",
        "linkUrl": "https://pay.example.com/payment-link/pl_100",
        "merchantNo": "800209",
        "linkName": "Membership Renewal",
        "amount": "99.99",
        "currency": "USD",
        "defaultCountry": "US",
        "itemName": "Membership",
        "description": "Annual membership renewal",
        "linkStatus": 1,
        "createTime": "2026-05-25 10:00:00",
        "visitCount": "20",
        "payCount": "5",
        "successAmount": "499.95"
      }
    ],
    "total": "1",
    "size": "10",
    "current": "1"
  }
}

更新支付链接状态 ​

POST

使用该接口启用或停用指定支付链接。停用后，买家不应再继续使用该链接完成支付。

请求参数 ​

注意

  • 所有 JSON 字段必须在提交前进行字符串化处理
  • 嵌套对象必须序列化为 JSON 字符串格式
  • JSON 字段不能包含未转义的特殊字符
  • JSON 中的数组应该正确格式化
  • JSON 字符串字段示例：
json
{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}
ParameterTypeLengthRequiredSignedDescription

id

Long

/

Yes

Yes

Payment Link ID returned by the create or list API.

linkStatus

Boolean

/

Yes

Yes

Target Payment Link status. true enables the link and false disables it.

merchantNo

String

20

Yes

Yes

Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.



sign

String

/

Yes

No

Digital signature string for request verification and security.




Please refer to Signature for signature generation method.

响应参数 ​

NameTypeDescription

respCode

String

Response code from Onerway


respMsg

String

Response message from Onerway


data

Object

Response data. Refer to object data


更新成功时，data 通常为 null。

API 使用示例 ​

json
{
  "id": 100,
  "linkStatus": false,
  "merchantNo": "800209",
  "sign": "a1b2c3d4e5f6..."
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": null
}

常见响应码 ​

响应码响应描述场景
20000Success请求成功。
50134Too many requests创建或查询接口触发频率限制。
55058Payment link not found.更新状态时，指定支付链接不存在。
55059Payment link does not belong to this merchant.更新状态时，指定支付链接不属于当前商户。

还可能返回签名校验、IP 白名单、权限校验或下游系统映射后的其他错误码，具体以实际响应为准。

最佳实践 ​

  1. 创建支付链接后保存返回的 id，用于后续查询和状态管理。
  2. 向买家展示或发送 linkUrl 前，确认订单金额、币种和商品信息准确。
  3. 使用 linkStatus=false 停用不再使用或已过期的链接。
  4. 不要只依赖页面访问次数判断支付结果；请结合支付链接列表中的支付统计、交易查询或 webhook 结果进行对账。

相关文档链接 ​