Token Query

The Token Query API allows merchants to retrieve the list of saved tokens for a customer. These tokens can be used for Card Token payments or subscription billing.

API Request Parameters

POST

Key Parameters

• merchantCustId - Customer's unique identifier in the merchant's system
• subProductType - Specify TOKEN for card binding tokens or SUBSCRIBE for subscription tokens

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:

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

Parameter	Type	Length	Required	Signed	Description
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway, obtained from Onerway dashboard
appId	String	20	Yes	Yes	Merchant application ID. Created by Onerway when merchant registers a website
merchantCustId	String	50	Yes	Yes	Unique customer identifier in merchant system, used to query payment token information (such as card tokenization or subscription payment tokens).
subProductType	String	16	Yes	Yes	Sub-product type for token query: TOKEN - for card tokenization SUBSCRIBE - for subscription tokens.
sign	String	/	Yes	No	Digital signature string for request verification. Please refer to Signature for signature generation method.

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
merchantNo	String	Merchant number. Created by Onerway when the merchant registers
tokenInfos	List	List of token information
└─ id	String	Binding information ID (can be used for unbinding operation)
└─ tokenId	String	Card binding token ID
└─ appId	String	Merchant application ID. Created by Onerway when the merchant registers a website
└─ cardNumber	String	Masked card number
└─ paymentMethod	String	Specific payment method, including card and local payment types
└─ cardBinCountry	String	Card BIN country
└─ year	String	Card expiration year
└─ month	String	Card expiration month

Integration Process

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

In this process:

• Merchant system sends a query request with the customer identifier
• Onerway processes the request and retrieves matching token records
• Onerway returns the list of saved tokens for the specified customer
• Merchant processes the token information (e.g., displays saved cards, initiates token payments)

API Usage Examples

Query Card Binding Tokens

Use this method to retrieve card binding tokens that can be used for token payments:

Request

{
    "appId": "1727880846378401792",
    "merchantCustId": "CustId-677A-1W11",
    "merchantNo": "800209",
    "sign": "dfd653422d7a6e76da73cb5e35098851ef08ff4da31bb55fc96dbba945ad096e",
    "subProductType": "TOKEN"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "merchantNo": "800209",
        "tokenInfos": [
            {
                "id": "1919777298473115649",
                "tokenId": "46273d9b5d809e7bc82d86955789f2e8afb1b90ebc038b762ccd6b86fac4244d",
                "appId": "1727880846378401792",
                "cardNumber": "400000******2701",
                "paymentMethod": "VISA",
                "cardBinCountry": "US",
                "year": "2026",
                "month": "05"
            }
        ]
    }
}

Query Subscription Tokens

Use this method to retrieve subscription tokens that can be used for subscription billing:

Request

{
    "appId": "1727880846378401792",
    "merchantCustId": "CustId-677A-1W11",
    "merchantNo": "800209",
    "sign": "bd50b1402c97ff13226db0842d359f0b08a5b45506decda35da6c81ec890fe34",
    "subProductType": "SUBSCRIBE"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "merchantNo": "800209",
        "tokenInfos": [
            {
                "id": "1919777241157951489",
                "tokenId": "258463e5e5b359a23b2baeed71391fb75f4f45e19ebba6f645ba469a69f6de85",
                "appId": "1727880846378401792",
                "cardNumber": "400000******2701",
                "paymentMethod": "VISA",
                "cardBinCountry": "US",
                "year": "2026",
                "month": "05"
            }
        ]
    }
}

Important

When querying tokens, be sure to specify the correct subProductType:

• Use TOKEN for card binding tokens
• Use SUBSCRIBE for subscription tokens

These token types are stored in separate systems and cannot be used interchangeably.

Common Error Scenarios and Solutions

Common Error Codes

Implementation Best Practices

1. Token Type Separation: Always use the correct subProductType parameter to specify whether you're querying card binding tokens (TOKEN) or subscription tokens (SUBSCRIBE)

2. Secure Token Handling: Store the retrieved token IDs securely and never expose them to the client-side code

3. Token Display: When displaying saved cards to customers, only show the masked card number (cardNumber), expiration date, and card type for verification

4. Error Handling: Implement proper error handling for scenarios where no tokens are found or API errors occur

5. Customer Verification: Ensure proper customer authentication before displaying or using their saved token information

6. Regular Synchronization: Implement a regular process to synchronize token status between your system and Onerway

Merchant Integration Checklist

Before implementing the Token Query API in your production environment, ensure you have:

• Secure token storage mechanism
• Proper error handling for query operations
• User interface to display saved cards (if applicable)
• Clear separation of token types (binding vs. subscription)
• Thorough testing in sandbox environment