Chargeback Query

Important Note

Before using this API, you must contact Onerway to obtain chargeback query permissions.

The Chargeback Query API allows merchants to retrieve information about chargebacks that have occurred on their transactions. A chargeback happens when a cardholder disputes a transaction with their card issuer and requests a refund due to issues such as fraud, product quality, or non-delivery of goods.

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
• originTransactionIds - For querying by Onerway's original transaction IDs
• chargebackIds - For querying by chargeback IDs
• importTimeStart and importTimeEnd - For querying by time range when Onerway received the chargeback

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
merchantTxnIds	String	/	Conditional	Yes	Multiple merchant transaction IDs, separated by commas.
originTransactionIds	String	/	Conditional	Yes	Multiple Onerway original transaction IDs, separated by commas
chargebackIds	String	/	Conditional	Yes	Multiple Onerway chargeback IDs, separated by commas
importTimeStart	String	/	Conditional	Yes	Start time when Onerway received the chargeback transaction. Format: yyyy-MM-dd HH:mm:ss
importTimeEnd	String	/	Conditional	Yes	End time when Onerway received the chargeback transaction. Format: yyyy-MM-dd HH:mm:ss
current	String	/	Yes	Yes	Current page number for query results
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
content	List	List of chargeback information
└─ merchantNo	String	Merchant number assigned by Onerway
└─ chargebackId	String	Chargeback transaction ID created by Onerway
└─ importTime	String	Time when Onerway received the chargeback transaction Format: yyyy-MM-dd HH:mm:ss
└─ merchantTxnId	String	Merchant transaction ID of the original transaction
└─ originTransactionId	String	Original transaction ID from Onerway
└─ txnAmount	String	Original transaction amount in settlement currency
└─ txnCurrency	String	Currency of the original transaction See ISO 4217
└─ txnTime	String	Time when the original transaction was completed Format: yyyy-MM-dd HH:mm:ss
└─ paymentMethod	String	Payment method used in the original transaction
└─ chargebackAmount	String	Amount of the chargeback
└─ chargebackCurrency	String	Currency of the chargeback amount See ISO 4217
└─ chargebackDate	String	Date when the chargeback occurred Format: yyyy-MM-dd
└─ chargebackStatus	String	Status of the chargeback See ChargebackStatusEnum
└─ chargebackReason	String	Reason for the chargeback
└─ chargebackArn	String	Acquirer Reference Number (ARN)
└─ appealDueTime	String	Deadline for submitting appeal materials Format: yyyy-MM-dd HH:mm:ss
└─ chargebackCode	String	Chargeback reason code
current	String	Current page number
size	String	Page size
totalPages	String	Total number of pages
totalElements	String	Total number of records

Integration Process

The Chargeback 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 chargeback records
• Onerway returns paginated chargeback data to the merchant
• Merchant processes the chargeback data for dispute management

API Usage Examples

Query by Time Range

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

Request

{
    "chargebackIds": null,
    "current": "1",
    "importTimeEnd": "2024-07-24 00:00:00",
    "importTimeStart": "2024-07-23 00:00:00",
    "merchantNo": "800209",
    "merchantTxnIds": "",
    "originTransactionIds": "",
    "sign": "a78bfa309daf6c1ae444ad87eed54cc5bd38a822e7360c04a6a11c3e70ca49c0"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "content": [
            {
                "merchantNo": "800209",
                "chargebackId": "1815647844296949760",
                "importTime": "2024-07-23 15:19:14",
                "merchantTxnId": "1721712864000",
                "originTransactionId": "1815621472153370624",
                "txnAmount": "20.00",
                "txnCurrency": "USD",
                "txnTime": "2024-07-23 13:36:59",
                "paymentMethod": "MASTERCARD",
                "chargebackAmount": "10.00",
                "chargebackCurrency": "USD",
                "chargebackDate": "2024-07-23",
                "chargebackReason": "1111",
                "chargebackArn": "1111",
                "chargebackCode": "111",
                "appealDueTime": "2024-07-26 15:19:14",
                "chargebackStatus": "NEW"
            },
            {
                "merchantNo": "800209",
                "chargebackId": "1815648032830914560",
                "importTime": "2024-07-23 15:19:59",
                "merchantTxnId": "355243001534",
                "originTransactionId": "1815582133184757760",
                "txnAmount": "30.00",
                "txnCurrency": "USD",
                "txnTime": "2024-07-23 10:58:25",
                "paymentMethod": "VISA",
                "chargebackAmount": "10.00",
                "chargebackCurrency": "USD",
                "chargebackDate": "2024-07-23",
                "chargebackReason": "111",
                "chargebackArn": "1111",
                "chargebackCode": "111",
                "appealDueTime": "2024-07-26 15:19:59",
                "chargebackStatus": "NEW"
            }
        ],
        "current": "1",
        "size": 10,
        "totalPages": 1,
        "totalElements": 2
    }
}

Query by Transaction ID

Use this method when you need to check if a specific transaction has been charged back:

Request

{
    "chargebackIds": null,
    "current": "1",
    "importTimeEnd": "",
    "importTimeStart": "",
    "merchantNo": "800209",
    "merchantTxnIds": "1721712864000",
    "originTransactionIds": "",
    "sign": "998f65fd59278bbed706bfaaca92a7ce6a0c3e9151dcfce9868560dff56f60e6"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "content": [
            {
                "merchantNo": "800209",
                "chargebackId": "1815647844296949760",
                "importTime": "2024-07-23 15:19:14",
                "merchantTxnId": "1721712864000",
                "originTransactionId": "1815621472153370624",
                "txnAmount": "20.00",
                "txnCurrency": "USD",
                "txnTime": "2024-07-23 13:36:59",
                "paymentMethod": "MASTERCARD",
                "chargebackAmount": "10.00",
                "chargebackCurrency": "USD",
                "chargebackDate": "2024-07-23",
                "chargebackReason": "1111",
                "chargebackArn": "1111",
                "chargebackCode": "111",
                "appealDueTime": "2024-07-26 15:19:14",
                "chargebackStatus": "NEW"
            }
        ],
        "current": "1",
        "size": 10,
        "totalPages": 1,
        "totalElements": 1
    }
}

Important

• The maximum time range for queries is 90 days
• At least one filter parameter (merchantTxnIds, originTransactionIds, chargebackIds, or time range) must be provided
• You must first contact Onerway to obtain permissions for chargeback query

Common Error Scenarios and Solutions

Implementation Best Practices

1. Regular Monitoring: Implement a routine process to check for new chargebacks daily or weekly to identify and address issues promptly

2. Transaction Linking: Link chargeback data with your original transaction records to facilitate investigation and response

3. Appeal Management: Track appeal deadlines (appealDueTime) carefully as chargebacks must be contested within the specified timeframe

4. Evidence Collection: Maintain organized records of transaction evidence (shipping confirmations, customer communications, etc.) for quick access when responding to chargebacks

5. Risk Analysis: Analyze chargeback patterns to identify high-risk transaction types, products, or customer segments

6. Notification System: Implement automated alerts for new chargebacks to ensure timely responses

7. Documentation: Keep detailed records of all chargeback resolutions, including evidence submitted and the outcome

Merchant Integration Checklist

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

• Requested and received chargeback query permissions from Onerway
• Secure storage for chargeback data
• Process for linking chargebacks to original transactions
• Alert system for new chargebacks
• Clear workflow for processing and appealing chargebacks
• Regular monitoring schedule
• Thorough testing in sandbox environment