Transaction Order Query

The Transaction Order Query API allows merchants to retrieve detailed transaction data and order details for transaction status reconciliation, dispute management, and reporting purposes.

API Request Parameters

POST

Key Parameters

Among the request parameters, one of the following must be provided:

• merchantTxnIds - For querying by merchant's transaction IDs
• transactionIds - For querying by Onerway transaction IDs
• startTime and endTime - For querying by time range (maximum 90-day interval)

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
current	String	/	Yes	Yes	Current page number for query results
endTime	String	/	Conditional	Yes	End time for transaction query period.
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway, obtained from Onerway dashboard
merchantTxnIds	String	/	Conditional	Yes	Multiple merchant transaction IDs, separated by commas.
sign	String	/	Yes	No	Digital signature string for request verification. Please refer to Signature for signature generation method.
startTime	String	/	Conditional	Yes	Start time for transaction query period.
transactionIds	String	/	Conditional	Yes	Multiple Onerway transaction IDs, separated by commas.
txnTypes	String	/	No	Yes	Multiple transaction types, separated by commas. See TxnTypeEnum

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
content	List	Transaction information list
└─transactionId	String	Transaction order number created by Onerway, corresponds to merchant's order number
└─merchantTxnId	String	Merchant transaction order number created by the merchant. Different order numbers are considered different transactions
└─merchantTxnOriginalId	String	Original merchant transaction order number, same as the request parameter field
└─txnTime	String	Transaction completion time
└─txnTimeZone	String	Transaction time zone, format: +/-HH:mm
└─txnCompletionTime	String	Transaction completion timestamp
└─originTransactionId	String	Original transaction order number from Onerway. Present for refund, void, and capture transactions
└─productType	String	Product type, please refer to ProductTypeEnum
└─subProductType	String	Sub-product type, please refer to SubProductTypeEnum
└─txnType	String	Transaction type, please refer to TxnTypeEnum
└─status	String	Transaction processing result. Please refer to TxnStatusEnum
└─contractId	String	Subscription contract number: Identifies which subscription it is, an important parameter for completing subscription repurchase
└─tokenId	String	Subscription/card binding token ID, returned for subscription/card binding transactions.
└─userPaymentStatus	String	User payment status true: paid false: unpaid
└─cardType	String	Card type, such as VISA, MASTERCARD, etc.
└─paymentMethod	String	Specific payment method, including card and local payment types
└─orderAmount	String	Order amount in base units.
└─settleRate	String	Exchange rate. Calculation formula: txnAmount = orderAmount * settleRate
└─orderCurrency	String	Transaction order currency. Please refer to ISO 4217 currency codes
└─txnAmount	String	Order amount converted to the settlement currency
└─txnCurrency	String	Settlement currency. Please refer to ISO 4217 currency codes
└─customsDeclarationAmount	String	Amount available for customs declaration
└─customsDeclarationCurrency	String	Currency corresponding to the amount available for customs declaration. Please refer to ISO 4217 currency codes
└─arn	String	ARN (Acquirer Reference Number)
└─appId	String	Merchant application ID. When a merchant registers a website, OnerWay creates an application ID for the merchant
└─website	String	Transaction website
└─cardBinCountry	String	Country of card bin
└─cardNumber	String	Transaction card number (masked)
└─walletTypeName	String	Brand name of the wallet
└─reason	String	Transaction failure reason. Contains details when status is not successful
└─holderName	String	Cardholder name
└─eci	String	Liability shift, parameter required for 3D Secure
└─email	String	Customer email address
└─creditCard	Object	Credit card information. Please refer to CreditCardEnum
└─channelRequestId	String	Unique identifier for the payment channel request
current	String	Current page number, 10 records per page
size	String	Current page size
totalPages	String	Total number of pages
totalElements	String	Total number of records

VerificationResult

Name	Description
version	3ds version
authenticationFlow	3ds flow
chargebackLiability	3ds chargeback liability When transStatus is [N,R], chargebackLiability cannot use UNKNOWN.
transStatus	3ds transaction status
transStatusReason	3ds transaction status reason
eci	eci (Electronic Commerce Indicator)
cvvResult	cvv verification result See CvvResultEnum for all possible result codes.
avsFullResult	avs address verification service result See AvsFullResultEnum for all possible result codes.
cavvResult	3ds authentication return (CAVV)

Integration Process

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

In this process:

• Merchant system sends a query request with appropriate filter parameters
• Onerway processes the request and retrieves matching transaction records
• Onerway returns paginated transaction data to the merchant
• Merchant processes the transaction data for reconciliation or reporting purposes

API Usage Examples

Query by Time Range

Use this method when you need to retrieve all transactions within a specific time period:

Request

{
    "current": "1",
    "endTime": "2025-05-12 13:52:49",
    "merchantNo": "800209",
    "merchantTxnIds": null,
    "sign": "07181c0e41d46066ac6eba6ddfbf9534d530f3d53fb120b143839bf659191b9f",
    "startTime": "2025-05-11 13:52:49",
    "transactionIds": null,
    "txnTypes": null
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "content": [
            {
                "transactionId": "1921458908934045696",
                "merchantTxnId": "5ddbee02-908f-44f9-a7a8-ac1c391f00b7",
                "merchantTxnOriginalId": null,
                "txnTime": "2025-05-11 14:54:37",
                "txnTimeZone": "+08:00",
                "txnCompletionTime": "2025-05-11 14:54:55",
                "originTransactionId": null,
                "productType": "CARD",
                "subProductType": "TOKEN",
                "txnType": "SALE",
                "status": "S",
                "contractId": null,
                "tokenId": "f7d54297b989d2acf4eb6791213cf2bd9d2c842ea05b0a91c8dd85f4f9e4915b",
                "userPaymentStatus": null,
                "cardType": "VISA",
                "paymentMethod": "VISA",
                "orderAmount": "500.00",
                "settleRate": "1",
                "orderCurrency": "USD",
                "txnAmount": "500.00",
                "txnCurrency": "USD",
                "customsDeclarationAmount": null,
                "customsDeclarationCurrency": null,
                "arn": null,
                "appId": "1727880846378401792",
                "website": "localhost",
                "cardBinCountry": "US",
                "cardNumber": "400000******2701",
                "walletTypeName": null,
                "reason": null,
                "holderName": "CL BRW2",
                "eci": "05",
                "email": "Tyrell.Wyman@gmail.com",
                "creditCard": {
                    "holderName": "CL BRW2",
                    "year": "2026",
                    "month": "05",
                    "verificationResult": {
                        "version": "V2_2",
                        "authenticationFlow": null,
                        "authenticationCode": "258001",
                        "chargebackLiability": "MERCHANT",
                        "transStatus": null,
                        "transStatusReason": null,
                        "eci": "05",
                        "cvvResult": null,
                        "avsFullResult": null,
                        "cavvResult": "AJkBBkhgQQAAAE4gSEJydQAAAAA="
                    },
                    "cardType": "VISA",
                    "productCategory": null,
                    "cardNumber": "400000******2701"
                },
                "channelRequestId": "8002091921458915405602817"
            },
            // ...
        ],
        "current": "1",
        "size": 10,
        "totalPages": 2,
        "totalElements": 14
    }
}

Query by Transaction ID

Use this method when you need to retrieve a specific transaction by its Onerway transaction ID:

Request

{
    "current": "1",
    "endTime": "2025-05-12 13:52:49",
    "merchantNo": "800209",
    "merchantTxnIds": null,
    "sign": "f62e37c34867c7497075ee852f0225915015f0d6c8e238d6590dac48f4383360",
    "startTime": "2025-05-11 13:52:49",
    "transactionIds": "1921486705937219584",
    "txnTypes": null
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "content": [
            {
                "transactionId": "1921486705937219584",
                "merchantTxnId": "6b38115b-f2a2-446e-aaa7-7fbaa106adf4",
                "merchantTxnOriginalId": null,
                "txnTime": "2025-05-11 16:45:04",
                "txnTimeZone": "+08:00",
                "txnCompletionTime": "2025-05-11 16:50:01",
                "originTransactionId": "1921486031321169920",
                "productType": "CARD",
                "subProductType": "DIRECT",
                "txnType": "CAPTURE",
                "status": "S",
                "contractId": null,
                "tokenId": null,
                "userPaymentStatus": null,
                "cardType": "VISA",
                "paymentMethod": "VISA",
                "orderAmount": "54.00",
                "settleRate": "1",
                "orderCurrency": "USD",
                "txnAmount": "54.00",
                "txnCurrency": "USD",
                "customsDeclarationAmount": null,
                "customsDeclarationCurrency": null,
                "arn": null,
                "appId": "1727880846378401792",
                "website": "localhost",
                "cardBinCountry": "US",
                "cardNumber": "400000******2701",
                "walletTypeName": null,
                "reason": null,
                "holderName": null,
                "eci": null,
                "email": "Ignacio94@gmail.com",
                "creditCard": {
                    "holderName": null,
                    "year": null,
                    "month": null,
                    "verificationResult": {
                        "version": null,
                        "authenticationFlow": null,
                        "authenticationCode": null,
                        "chargebackLiability": null,
                        "transStatus": null,
                        "transStatusReason": null,
                        "eci": null,
                        "cvvResult": null,
                        "avsFullResult": null,
                        "cavvResult": null
                    },
                    "cardType": "VISA",
                    "productCategory": null,
                    "cardNumber": "400000******2701"
                },
                "channelRequestId": "8002091921486708126392321"
            }
        ],
        "current": "1",
        "size": 10,
        "totalPages": 1,
        "totalElements": 1
    }
}

Query by Transaction Type

Use this method when you need to retrieve transactions of a specific type (e.g., refunds):

Request

{
    "current": "1",
    "endTime": "2025-05-25 00:00:00",
    "merchantNo": "800209",
    "merchantTxnIds": null,
    "sign": "fb4ebe96e500606d7f9ea72ce5089c939817f6d1fc14fe0298d5e8cd30f83adb",
    "startTime": "2025-03-24 00:00:00",
    "transactionIds": "",
    "txnTypes": "REFUND"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "content": [
            {
                "transactionId": "1904841040222093312",
                "merchantTxnId": "2f956308-b20a-42ca-be0a-abe897834f05",
                "merchantTxnOriginalId": null,
                "txnTime": "2025-03-26 18:21:08",
                "txnTimeZone": "+08:00",
                "txnCompletionTime": null,
                "originTransactionId": "1904840655646359552",
                "productType": "CARD",
                "subProductType": "DIRECT",
                "txnType": "REFUND",
                "status": "P",
                "contractId": null,
                "tokenId": null,
                "userPaymentStatus": null,
                "cardType": "VISA",
                "paymentMethod": "VISA",
                "orderAmount": "1.00",
                "settleRate": null,
                "orderCurrency": "USD",
                "txnAmount": null,
                "txnCurrency": null,
                "customsDeclarationAmount": null,
                "customsDeclarationCurrency": null,
                "arn": null,
                "appId": "1727880846378401792",
                "website": "localhost",
                "cardBinCountry": "US",
                "cardNumber": "400000******2701",
                "walletTypeName": null,
                "reason": null,
                "holderName": null,
                "eci": null,
                "email": "Aurelio.Abernathy85@gmail.com",
                "creditCard": null,
                "channelRequestId": "8002091904841043610828801"
            }
        ],
        "current": "1",
        "size": 10,
        "totalPages": 1,
        "totalElements": 1
    }
}

Important

When querying by transaction type, both startTime and endTime are required parameters.
The maximum time range allowed is 90 days.

Common Error Scenarios and Solutions

Common Error Codes

Implementation Best Practices

1. Paginated Queries
   For large data sets, implement pagination logic to handle multiple pages of results using the current parameter

2. Efficient Querying
   Use the most specific parameters available for your use case:

   • Query by transaction IDs when looking up specific transactions
   • Query by merchant transaction IDs when reconciling with your own system
   • Query by time range only when necessary for batch processing

3. Data Synchronization
   Implement a regular synchronization process to reconcile transaction status between your system and Onerway

4. Error Handling
   Implement proper handling for API errors, including retry logic for temporary failures

5. Transaction Statuses
   Pay special attention to the transaction status field to identify successful, pending, and failed transactions

Merchant Integration Checklist

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

• Secure data storage for transaction records
• Proper error handling mechanisms
• Pagination handling for large result sets
• Data reconciliation processes
• Thorough testing in sandbox environment