简体中文

English

简体中文

English

主题

支付方式查询 ​

支付方式查询API允许商户根据商户配置、订单参数和客户位置获取可用的支付方式。此API帮助商户根据具体的交易上下文动态向客户显示合适的支付选项。

集成前置条件 ​

在实施支付方式查询之前，请确保您具备：

  • 有效的 Onerway 商户账户，且已配置支付方式
  • 可访问 Onerway 支付网关 API
  • 可获取客户位置和订单信息
  • 具备动态显示支付方式选项的技术能力
  • 了解支付方式过滤和地区限制

支付方式查询优势

此 API 对于优化支付方式选择至关重要：

  1. 动态支付方式显示：仅显示特定订单金额和货币可用的支付方式
  2. 地理定制：根据客户位置和地区偏好显示支付方式
  3. 平台优化：为网页、移动端和应用平台显示不同的支付方式
  4. 货币特定方式：根据支持的货币过滤支付方式
  5. 实时可用性：获取支付方式可用性和配置的最新信息
  6. 商户配置：遵循商户特定的支付方式设置和限制

API请求参数 ​

POST

关键参数

查询支付方式时，请考虑这些重要参数：

  1. country：必需参数，决定客户地区可用的支付方式
  2. orderAmount和orderCurrency：用于根据最小/最大金额限制过滤支付方式
  3. paymentMode：根据平台（WEB、APP、WAP）过滤方式
  4. subProductType：可选过滤器，用于查询特定支付方式类别

注意

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

appId

String

20

Yes

Yes

Merchant application ID assigned by Onerway for website identification.



country

String

64

Yes

Yes

Customer country code for risk assessment and compliance.




See ISO 3166 for complete list.

merchantNo

String

20

Yes

Yes

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



orderAmount

String

19

Yes

Yes

Transaction amount in the specified currency, formatted as a decimal string.



orderCurrency

String

8

Yes

Yes

Three-letter currency code according to ISO 4217 standard for the transaction amount.



osType

String

16

Conditional

Yes

Operating system type for mobile and app-based transactions.




See

OsTypeEnum

for available options.

paymentMode

String

16

No

Yes

Payment mode indicating the platform or environment for the transaction.




See

PaymentModeEnum

for all available options.

sign

String

/

Yes

No

Digital signature string for request verification and security.




Please refer to Signature for signature generation method.

subProductType

String

16

No

Yes

Optional filter for specific payment method categories.




See

SubProductTypeEnum

for all available options.

响应 ​

NameTypeDescription

respCode

String

Response code from Onerway


respMsg

String

Response message from Onerway


data

Object

Response data. Refer to object data


data ​

NameTypeDescription

productType

String

Payment product type category.



paymentMethod

String

Specific payment method identifier.



paymentMethodDetail

Object

Detailed payment method information and configuration.



See

PaymentMethodDetail

for structure details.

countryCode

String

Country code where this payment method is available.



gatewayName

String

Payment gateway identifier for Google Pay tokenization.



gatewayMerchantId

String

Gateway-specific merchant identifier for Google Pay.


merchantId

String

Google-assigned merchant identifier for production verification.



subCardTypes

Array

Supported card networks for wallet payments.



paymentMethodDetail ​

对于某些支付方式（如Alipay+），提供额外的详细信息：

NameTypeDescription

paymentMethodName

String

Brand name of the payment method.



logos

Array

List of logo information for the payment method.



See

Logos

for logo object structure.

promoNames

Array

List of promotional offer information available for this payment method.



logos ​
NameTypeDescription

logoName

String

Name identifier for the logo.



logoUrl

String

URL of the logo image.



logoPattern

String

Pattern or style identifier for the logo.



logoWidth

String

Width of the logo in pixels (px).



logoHeight

String

Height of the logo in pixels (px).



集成流程 ​

支付方式查询集成流程包含一个简单的请求-响应流程：

在此流程中：

  1. 客户结账：客户到达带有订单详情的支付页面
  2. 参数收集：商户系统收集相关参数（金额、货币、客户国家）
  3. 查询请求：商户向Onerway发送带有订单上下文的查询请求
  4. 方式过滤：Onerway根据商户配置、地理限制和订单参数过滤可用支付方式
  5. 响应处理：Onerway返回带有详细配置的过滤后支付方式
  6. 显示选项：商户向客户显示合适的支付方式

API使用示例 ​

查询美国客户的支付方式 ​

使用此方法获取美国客户特定订单的可用支付方式：

json
{
  "appId": "1727880846378401792",
  "country": "US",
  "merchantNo": "800209",
  "orderAmount": "208.12",
  "orderCurrency": "USD",
  "osType": "",
  "paymentMode": "WEB",
  "sign": "150dfa73f06b3b9eea984896513f2392b0f049b79e8895fc355d5c2e81c6f0e7",
  "subProductType": ""
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": [
    {
      "productType": "LPMS",
      "paymentMethod": "PayPal",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    },
    {
      "productType": "CARD",
      "paymentMethod": "AE",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    },
    {
      "productType": "LPMS",
      "paymentMethod": "Alipay",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    },
    {
      "productType": "CARD",
      "paymentMethod": "VISA",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    },
    {
      "productType": "CARD",
      "paymentMethod": "MASTERCARD",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    },
    {
      "productType": "LPMS",
      "paymentMethod": "ApplePay",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": "merchant.ronhan.pacypay",
      "gatewayMerchantId": null,
      "merchantId": "merchant.ronhan.pacypay",
      "subCardTypes": ["discover", "visa", "masterCard"]
    },
    {
      "productType": "LPMS",
      "paymentMethod": "GooglePay",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": "ronghan",
      "gatewayMerchantId": "BCR2DN6TY7DM5TDU",
      "merchantId": "800096",
      "subCardTypes": ["MASTERCARD", "VISA"]
    },
    {
      "productType": "LPMS",
      "paymentMethod": "Alipay+",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    }
  ]
}

查询包含Alipay+详情的支付方式 ​

对于Alipay+可用的地区，响应包含详细的标志和促销信息：

json
{
  "appId": "1727880846378401792",
  "country": "SG",
  "merchantNo": "800209",
  "orderAmount": "50.00",
  "orderCurrency": "SGD",
  "osType": "",
  "paymentMode": "WEB",
  "sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "subProductType": ""
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": [
    {
      "productType": "LPMS",
      "paymentMethod": "Alipay+",
      "paymentMethodDetail": {
        "paymentMethodName": "Alipay+",
        "logos": [
          {
            "logoName": "Alipay+",
            "logoUrl": "https://cdn.marmot-cloud.com/storage/2025/01/03/63fd35e2-c575-459d-9d7d-b941cff1c91e.png",
            "logoPattern": "P1-WEB-01",
            "logoWidth": "912",
            "logoHeight": "120"
          }
        ],
        "promoNames": [
          "{\\"en_US\\":\\"A+ Cashier Promotion Test\\",\\"fil_PH\\":\\"A+ Cashier Promotion Test\\"}"
        ]
      },
      "countryCode": "SG",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    },
    {
      "productType": "CARD",
      "paymentMethod": "VISA",
      "paymentMethodDetail": null,
      "countryCode": "SG",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    },
    {
      "productType": "CARD",
      "paymentMethod": "MASTERCARD",
      "paymentMethodDetail": null,
      "countryCode": "SG",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    }
  ]
}

查询移动应用的支付方式 ​

使用此方法获取为移动应用集成优化的支付方式：

json
{
  "appId": "1727880846378401792",
  "country": "US",
  "merchantNo": "800209",
  "orderAmount": "25.99",
  "orderCurrency": "USD",
  "osType": "IOS",
  "paymentMode": "APP",
  "sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "subProductType": ""
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": [
    {
      "productType": "LPMS",
      "paymentMethod": "ApplePay",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": "merchant.ronhan.pacypay",
      "gatewayMerchantId": null,
      "merchantId": "merchant.ronhan.pacypay",
      "subCardTypes": ["discover", "visa", "masterCard"]
    },
    {
      "productType": "LPMS",
      "paymentMethod": "GooglePay",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": "ronghan",
      "gatewayMerchantId": "BCR2DN6TY7DM5TDU",
      "merchantId": "800096",
      "subCardTypes": ["MASTERCARD", "VISA"]
    },
    {
      "productType": "CARD",
      "paymentMethod": "VISA",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    },
    {
      "productType": "CARD",
      "paymentMethod": "MASTERCARD",
      "paymentMethodDetail": null,
      "countryCode": "US",
      "gatewayName": null,
      "gatewayMerchantId": null,
      "merchantId": null,
      "subCardTypes": null
    }
  ]
}

常见错误场景 ​

无效国家代码 ​

错误：该国家未返回支付方式
原因：country 参数包含无效或不支持的国家代码
解决方案：验证国家代码采用 ISO 3166-1 alpha-2 格式且您的商户配置支持

不支持的货币 ​

错误：该货币的支付方式列表为空
原因：指定国家或商户不支持 orderCurrency
解决方案：检查您的商户配置中目标国家支持的货币

无效签名 ​

错误：请求签名验证失败
原因：sign 参数不正确或使用错误参数生成
解决方案：验证您的签名生成过程并确保包含所有参数

商户配置错误 ​

错误：未配置支付方式
原因：您的商户账户未正确配置请求的国家或支付方式
解决方案：联系 Onerway 支持以验证您的商户配置并启用所需的支付方式

实施最佳实践 ​

  1. 适当缓存结果：支付方式配置变化不频繁，考虑短期缓存结果（5-15分钟）以提高性能
  2. 处理空结果：始终检查数据数组是否为空，并提供备用选项或错误消息
  3. 验证参数：在进行API调用之前确保所有必需参数都存在且有效
  4. 错误处理：为网络故障和API错误实施适当的错误处理
  5. 显示优化：使用提供的标志URL和支付方式名称以保持品牌一致性
  6. 网关配置：对于GooglePay和ApplePay，使用提供的gatewayName、merchantId和subCardTypes进行正确集成
  7. 支付方式详情：适当处理paymentMethodDetail - 它包含Alipay+的有价值信息，但对其他方式可能为null
  8. 支持的卡类型：对于钱包支付，使用subCardTypes数组确定支持哪些卡品牌

商户集成清单 ​

在实施支付方式查询API之前：

  • 验证商户账户已为目标国家配置
  • 确认每个目标市场的支持货币
  • 测试不同国家和货币组合的API响应
  • 为所有错误场景实施适当的错误处理
  • 为支付方式数据设置适当的缓存策略
  • 验证与您的支付流程的集成
  • 测试不同的paymentMode值（WEB、APP、WAP）
  • 验证标志URL可访问且显示正确（特别是Alipay+）
  • 测试GooglePay和ApplePay集成的网关配置
  • 确保签名生成和验证正常工作