Refund

The Refund API allows merchants to process refunds for previously completed transactions. The refund can be processed as a full refund of the original transaction amount or as a partial refund.

Refund Audit Process

All refund requests go through an audit process by Onerway staff before being submitted to the payment network. This audit helps prevent fraud and ensure compliance with payment network rules.

API Request Parameters

POST

Key Parameters

• merchantTxnId - Unique refund identifier assigned by merchant
• originTransactionId - Original transaction ID to be refunded
• refundAmount - Amount to be refunded
• refundType - Type of refund operation (0 for standard refund)

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
merchantTxnId	String	64	Yes	Yes	Unique transaction identifier for each customer payment. Must be unique for each transaction request.
originTransactionId	String	20	Conditional	Yes	Original transaction ID from Onerway
refundAmount	String	19	Yes	Yes	Refund transaction amount
refundType	String	1	Yes	Yes	Refund type: 0 – Apply for refund 1 – Cancel refund application
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
data	String	The refund transaction ID generated by Onerway. This ID can be used to query the refund status.

Integration Process

The refund processing integration consists of the following steps:

In this process:

• Merchant system sends a refund request with the original transaction ID and refund amount
• Onerway processes the request and initiates the refund
• Onerway returns the refund transaction ID in the synchronous response
• The refund request is submitted for manual review by Onerway staff
• If approved, the refund is submitted to the payment network and a TXN webhook notification is sent
• If rejected (e.g., if merchant wants to cancel the refund request), a REFUND_AUDIT webhook notification is sent
• Merchant system acknowledges receipt of the webhook notification

API Usage Examples

Process Standard Refund

Use this method to refund a previously completed transaction:

Request

{
    "merchantNo": "800209",
    "merchantTxnId": "R-b20e9b40-4479-4ab7-aa40-69463f7dea44",
    "originTransactionId": "1925119178365603842",
    "refundAmount": "45",
    "refundType": "0",
    "sign": "09baac34498807d965fa7876f06d5c5211fd1ec1208cb43ecbfc63d73dc5b8a7"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": "1925487587804712960" // Onerway refund transaction ID
}

Webhook Notification

{
    "notifyType": "TXN", 
    "transactionId": "1925487587804712960", 
    "txnType": "REFUND", 
    "merchantNo": "800209",
    "merchantTxnId": "R-b20e9b40-4479-4ab7-aa40-69463f7dea44",
    "originMerchantTxnId": "TX_dS420AER_66088",
    "responseTime": "2025-05-22 17:43:12",
    "txnTime": "2025-05-22 17:43:09",
    "txnTimeZone": "+08:00",
    "orderAmount": "45.00",
    "orderCurrency": "USD",
    "status": "S", // S for Success
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "4cc2ffbe2f0177a7e1eda4f724db42d5018a8bb47b5478371724498b8b0e428f",
    "paymentMethod": "VISA",
    "channelRequestId": "8002091925487592405602305"
}

Refund Audit Notification

{
    "notifyType": "REFUND_AUDIT", 
    "transactionId": "1925739837181530114", 
    "merchantNo": "800209",
    "merchantTxnId": "R-b20e9b40-4479-4ab7-aa40-69463f7dea45",
    "originMerchantTxnId": "TX_zvKa3GX7_59496",
    "responseTime": "2025-05-23 10:26:06",
    "txnTimeZone": "+08:00",
    "orderAmount": "45.00",
    "orderCurrency": "USD",
    "status": "F", // F for Failed/Rejected
    "sign": "d01abdaf733086272252ea1548644bef007e50aaa18329d737a8d103e5f4efa7"
}

Important Notes

1. For refund requests, a recommended convention is to prefix the merchantTxnId with "R-" to easily identify refund transactions
2. The refundAmount must be less than or equal to the original transaction amount
3. The webhook notification will be sent to the same webhook endpoint configured for transaction notifications
4. Both synchronous response and webhook notification should be handled for complete refund processing
5. All refund requests go through an audit process by Onerway staff
6. Only after the audit is approved will the refund be submitted to the payment network
7. If merchants wish to cancel a refund request, it will be rejected during the audit and a REFUND_AUDIT notification with status F will be sent

Common Error Scenarios and Solutions

Implementation Best Practices

1. Unique Refund Identifiers: Use a consistent format for refund transaction IDs, such as adding an "R-" prefix to your merchantTxnId for refunds

2. Idempotent Processing: Implement idempotent refund processing to prevent duplicate refunds if your system retries the refund request

3. Refund Status Tracking:

   • Store both the original transaction ID and the refund transaction ID for tracking
   • Implement a robust webhook handler to update refund statuses in your system
   • Have a reconciliation process to verify refund status for any webhook failures
   • Be prepared to handle both TXN notifications for successful refunds and REFUND_AUDIT notifications for rejected refunds

4. User Communication:

   • Notify customers when their refund is initiated
   • Set expectations about when funds will be available (typically 5-7 business days)
   • Provide refund transaction IDs in customer communications for reference
   • Have a communication plan for when refunds are rejected during audit

5. Partial Refunds:

   • Keep track of the remaining refundable amount for each transaction
   • Validate that the sum of all partial refunds doesn't exceed the original amount
   • Use separate merchant transaction IDs for each partial refund attempt

6. Security Considerations:

   • Implement proper access controls for refund operations
   • Validate the original transaction belongs to the requesting merchant
   • Verify webhook signatures to prevent fraud

Merchant Integration Checklist

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

• Proper signature generation implementation
• Unique refund transaction ID generation
• Webhook endpoint for receiving refund notifications
• Handling for both TXN and REFUND_AUDIT notification types
• Refund status tracking system
• Customer notification mechanism for refund status
• Error handling and retry mechanisms
• Reconciliation process for refund verification
• Access controls for refund operations
• Testing completed in sandbox environment