Payment Methods Query

The Payment Methods Query API allows merchants to retrieve available payment methods based on merchant configuration, order parameters, and customer location. This API helps merchants dynamically display appropriate payment options to customers based on their specific transaction context.

Integration Prerequisites

Before implementing Payment Methods Query, ensure you have:

A valid Onerway merchant account with payment methods configured
Access to the Onerway payment gateway API
Customer location and order information available
Technical capability to dynamically display payment method options
Understanding of payment method filtering and regional restrictions

Payment Methods Query Benefits

This API is essential for optimizing payment method selection:

Dynamic Payment Method Display: Show only payment methods available for specific order amounts and currencies
Geographic Customization: Display payment methods based on customer location and regional preferences
Platform Optimization: Show different payment methods for web, mobile, and app platforms
Currency-Specific Methods: Filter payment methods based on supported currencies
Real-time Availability: Get up-to-date information about payment method availability and configuration
Merchant Configuration: Respect merchant-specific payment method settings and restrictions

API Request Parameters

POST

Key Parameters

When querying payment methods, consider these important parameters:

country: Required parameter that determines which payment methods are available in the customer's region
orderAmount and orderCurrency: Used to filter payment methods based on minimum/maximum amount limits
paymentMode: Filters methods based on platform (WEB, APP, WAP)
subProductType: Optional filter to query specific payment method categories

Note

All JSON fields must be stringified before submission
Nested objects must be serialized to JSON string format
JSON fields must not contain unescaped special characters
Arrays in JSON should be properly formatted
Example of JSON string field:

json

{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Length	Required	Signed	Description
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.

Response

Name	Type	Description
respCode	String	Response code from `Onerway`
respMsg	String	Response message from `Onerway`
data	Object	Response data. Refer to object data

data

Name	Type	Description
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

For certain payment methods (such as Alipay+), additional detailed information is provided:

Name	Type	Description
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

Name	Type	Description
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).

Integration Process

The Payment Methods Query integration process consists of a simple request-response flow:

In this process:

Customer Checkout: Customer reaches the payment page with order details
Parameter Collection: Merchant system collects relevant parameters (amount, currency, customer country)
Query Request: Merchant sends query request to Onerway with order context
Method Filtering: Onerway filters available payment methods based on merchant configuration, geographic restrictions, and order parameters
Response Processing: Onerway returns filtered payment methods with detailed configuration
Display Options: Merchant displays appropriate payment methods to customer

API Usage Examples

Query Payment Methods for US Customer

Use this method to get available payment methods for a US customer with a specific order:

RequestResponse

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
    }
  ]
}

Query Payment Methods with Alipay+ Details

For regions where Alipay+ is available, the response includes detailed logo and promotional information:

RequestResponse

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
    }
  ]
}

Query Payment Methods for Mobile App

Use this method to get payment methods optimized for mobile app integration:

RequestResponse

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
    }
  ]
}

Common Error Scenarios

Invalid Country Code

Error: No payment methods returned for country
Cause: The country parameter contains an invalid or unsupported country code
Solution: Verify the country code is in ISO 3166-1 alpha-2 format and supported by your merchant configuration

Unsupported Currency

Error: Empty payment method list for currency
Cause: The orderCurrency is not supported in the specified country or by the merchant
Solution: Check your merchant configuration for supported currencies in the target country

Invalid Signature

Error: Request signature validation failed
Cause: The sign parameter is incorrect or generated with wrong parameters
Solution: Verify your signature generation process and ensure all parameters are included

Merchant Configuration Error

Error: No payment methods configured
Cause: Your merchant account is not properly configured for the requested country or payment methods
Solution: Contact Onerway support to verify your merchant configuration and enable required payment methods

Implementation Best Practices

Cache Results Appropriately: Payment method configurations change infrequently, so consider caching results for short periods (5-15 minutes) to improve performance
Handle Empty Results: Always check if the data array is empty and provide fallback options or error messaging
Validate Parameters: Ensure all required parameters are present and valid before making the API call
Error Handling: Implement proper error handling for network failures and API errors
Display Optimization: Use the provided logo URLs and payment method names for consistent branding
Gateway Configuration: For GooglePay and ApplePay, use the provided gatewayName, merchantId, and subCardTypes for proper integration
Payment Method Details: Handle paymentMethodDetail appropriately - it contains valuable information for Alipay+ but may be null for other methods
Supported Card Types: For wallet payments, use the subCardTypes array to determine which card brands are supported

Merchant Integration Checklist

Before implementing the Payment Methods Query API:

Checkout

Credit Card Payment

Alternative Methods(SDK-based)

Order Management

Native SDK

Android SDK

Card Processing APIs (PCI Required)

Transaction Management (No PCI Required)

Alternative Methods(API-based)

Ethoca

RDR

Payment Methods Query

Integration Prerequisites

API Request Parameters

Response

data

paymentMethodDetail

logos

Integration Process

API Usage Examples

Query Payment Methods for US Customer

Query Payment Methods with Alipay+ Details

Query Payment Methods for Mobile App

Common Error Scenarios

Invalid Country Code

Unsupported Currency

Invalid Signature

Merchant Configuration Error

Implementation Best Practices

Merchant Integration Checklist

Android SDK

Payment Methods Query ​

Integration Prerequisites ​

API Request Parameters ​

Response ​

data ​

paymentMethodDetail ​

logos ​

Integration Process ​

API Usage Examples ​

Query Payment Methods for US Customer ​

Query Payment Methods with Alipay+ Details ​

Query Payment Methods for Mobile App ​

Common Error Scenarios ​

Invalid Country Code ​

Unsupported Currency ​

Invalid Signature ​

Merchant Configuration Error ​

Implementation Best Practices ​

Merchant Integration Checklist ​

Payment Methods Query

Integration Prerequisites

API Request Parameters

Response

data

paymentMethodDetail

logos

Integration Process

API Usage Examples

Query Payment Methods for US Customer

Query Payment Methods with Alipay+ Details

Query Payment Methods for Mobile App

Common Error Scenarios

Invalid Country Code

Unsupported Currency

Invalid Signature

Merchant Configuration Error

Implementation Best Practices

Merchant Integration Checklist