Authorization Reversal

Authorization Reversal (also known as VOID) is used to cancel a previously authorized transaction, releasing the reserved funds on the customer's card. When a transaction is authorized using the Direct Authorization API, SDK Authorization, or Checkout Authorization, the funds are reserved on the customer's card. The reversal operation cancels this reservation before it is captured.

When to Use Reversal

Authorization Reversal should be used when:

• A customer cancels an order after authorization but before capture
• An item is out of stock after authorization
• An authorization was created in error
• You no longer intend to capture the funds

API Request Parameters

POST

Key Parameters for Reversal

When performing a reversal operation, you need to include these key parameters:

1. txnType: Must be set to VOID for reversal transactions.
2. originTransactionId: The transactionId of the original authorization transaction.

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
txnType	String	16	Yes	Yes	Transaction type. See TxnTypeEnum
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
transactionId	String	Transaction order number created by Onerway
responseTime	String	Interface response time Format: yyyy-MM-dd HH:mm:ss
txnTime	String	Transaction completion time Format: yyyy-MM-dd HH:mm:ss
txnTimeZone	String	Transaction time zone Format: +/-HH:mm
orderAmount	String	Order amount
orderCurrency	String	Transaction order currency Refer to ISO 4217 currency codes
txnAmount	String	Order amount after conversion to settlement currency
txnCurrency	String	Settlement currency Refer to ISO 4217 currency codes
status	String	Transaction processing result Refer to TxnStatusEnum
redirectUrl	String	Redirection URL for 3D Secure verification
contractId	String	Subscription contract number
tokenId	String	Payment token
eci	String	Electronic Commerce Indicator
periodValue	String	Installment payment number of periods
codeForm	String	Code form for specific payment methods See CodeFormEnum
presentContext	String	Context information for presentation layer
actionType	String	Action type for the transaction See ActionTypeEnum
subscriptionManageUrl	String	Subscription management URL
sign	String	Signature string Refer to the Signature interface

Authorization Reversal Integration Process

The Authorization Reversal process cancels an authorization and releases the hold on the customer's funds:

In this process:

1. Reversal Request: Merchant system sends a reversal request with the original authorization's transactionId
2. Initial Response: Onerway returns an initial response with status (typically P for pending)
3. Webhook Notification: The final result is sent via webhook to the merchant's notifyUrl
4. Acknowledgment: Merchant system acknowledges receipt of the webhook

Reversal Limitations

An authorization can only be reversed if:

• It has not already been captured
• It has not already been reversed
• It has not expired

API Usage Examples

Standard Reversal Request

Request

{
    "merchantNo": "800209",
    "merchantTxnId": "507df80b-243a-459b-bd76-bee35e7f0328",
    "originTransactionId": "1921498484000030720", // Original authorization transactionId
    "sign": "80b2e30442e6296e1dfcf6794f0479b4691177cfdd1f37576cbf141afec570a3",
    "txnType": "VOID" // Must be VOID for reversal transactions
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1921498535157956608", // New transaction ID for the reversal
        "responseTime": "2025-05-11 17:32:06",
        "txnTime": null,
        "txnTimeZone": "+08:00",
        "orderAmount": "10.00",
        "orderCurrency": "USD",
        "txnAmount": "10.00",
        "txnCurrency": "USD",
        "status": "P", // Pending status for the reversal
        "redirectUrl": null,
        "contractId": null,
        "tokenId": null,
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "subscriptionManageUrl": null,
        "sign": "9d49c16e4341ea7f920c9bd249771618dd4f41c91eb3b2eb80b5ed32182bf9b1"
    }
}

Webhook (notifyUrl)

{
    "notifyType": "TXN",
    "transactionId": "1921498535157956608",
    "txnType": "VOID",
    "merchantNo": "800209",
    "merchantTxnId": "507df80b-243a-459b-bd76-bee35e7f0328",
    "responseTime": "2025-05-11 17:35:02",
    "txnTime": "2025-05-11 17:32:05",
    "txnTimeZone": "+08:00",
    "orderAmount": "10.00",
    "orderCurrency": "USD",
    "status": "S", // Success status for completed reversal
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "2fe73005baa11e3823a4b641393e2c7b79ee7d80b850c5185cdb3b11c6ee3170",
    "paymentMethod": "VISA",
    "channelRequestId": "8002091921498536260804609"
}

Common Error Scenarios and Solutions

Common Error Codes

Error Code	Description	Solution
13032	Capture or void has been carried out and cannot be launched again	Verify that the authorization has not already been captured or voided
70002	Unknown decline	Contact Onerway support

Scenario: Duplicate Reversal Attempt

{
    "respCode": "13032",
    "respMsg": "Capture or void has been carried out and cannot be launched again",
    "data": null
}

Solution

1. Check your system records to verify if the authorization has already been reversed or captured
2. Implement proper transaction status tracking to avoid duplicate reversal attempts
3. If the authorization was already captured, consider processing a refund instead

Implementation Best Practices

Reversal Best Practices

1. Transaction Management:

   • Store the original authorization transactionId securely for potential reversal
   • Track authorization status to prevent attempting to reverse already captured or voided transactions
   • Implement proper error handling for failed reversals

2. Reversal Timing:

   • Reverse authorizations as soon as you know they will not be captured
   • Implement automated processes to reverse abandoned authorizations
   • Consider customer-initiated cancellation workflows that trigger reversals

3. Transaction Tracking:

   • Maintain comprehensive records linking authorizations to their reversals
   • Implement status tracking to prevent duplicate reversal attempts
   • Create reconciliation processes to ensure all abandoned authorizations are reversed

4. Webhook Handling:

   • Implement robust webhook processing to reliably receive reversal results
   • Verify webhook signatures to ensure authenticity
   • Respond with the transactionId upon successful webhook processing to prevent retries
   • Implement idempotent webhook processing to handle potential duplicates

5. Error Handling:

   • Design appropriate retry mechanisms for failed reversals
   • Implement fallback procedures for reversal failures
   • Create customer service processes for handling reversal failures

6. User Experience:

   • Consider notifying customers when their authorization has been reversed
   • Provide clear transaction records showing authorization reversal
   • Ensure customers understand that reversed funds may take time to become available in their accounts

Business Logic Considerations

1. Order Cancellation Flow:

   • Align reversal timing with your order cancellation process
   • Consider automating reversals based on order status changes
   • Ensure proper coordination between inventory, order management, and payment systems

2. Reconciliation Practices:

   • Regularly reconcile authorized, captured, and reversed transactions
   • Implement automated alerts for unresolved authorizations
   • Create reports to track authorization status

3. Risk Management:

   • Monitor reversal rates as potential fraud or customer satisfaction indicators
   • Implement appropriate security measures for storing authorization references
   • Consider analyzing reversal patterns to improve business processes

Merchant Integration Checklist

Before going live with Authorization Reversal integration, ensure you have:

• Proper storage of authorization transactionId values
• Webhook handling and verification for reversal results
• Transaction status tracking to prevent duplicate reversals
• Error handling mechanisms for reversal failures
• Reconciliation process for authorizations and reversals
• Thorough testing in sandbox environment with full authorization-reversal flow
• Customer notification process for cancelled authorizations