Authorization Capture

Authorization Capture is used to complete a previously authorized transaction by transferring the reserved funds from the customer's account to the merchant's account. When a transaction is authorized using the Direct Authorization API, SDK Authorization, or Checkout Authorization, the funds are only reserved on the customer's card. The capture operation actually transfers those funds.

API Request Parameters

POST

Key Parameters for Capture

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

1. txnType: Must be set to CAPTURE for capture 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 Capture Integration Process

The Authorization Capture process is the final step in the authorization-capture flow:

In this process:

1. Capture Request: Merchant system sends a capture 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

Capture Timeframe

Authorizations are typically valid for 7 days. You must capture within this timeframe or the authorization will expire and the funds will be released.

API Usage Examples

Standard Capture Request

Request

{
    "merchantNo": "800209",
    "merchantTxnId": "6b38115b-f2a2-446e-aaa7-7fbaa106adf4",
    "originTransactionId": "1921486031321169920", // Original authorization transactionId
    "sign": "45dbfe36cb30dea43af6a2e88f723ace32f5ff71218201bb552d1185bfafc8ca",
    "txnType": "CAPTURE" // Must be CAPTURE for capture transactions
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1921486705937219584", // New transaction ID for the capture
        "responseTime": "2025-05-11 16:45:07",
        "txnTime": null,
        "txnTimeZone": "+08:00",
        "orderAmount": "54.00",
        "orderCurrency": "USD",
        "txnAmount": "54.00",
        "txnCurrency": "USD",
        "status": "P", // Pending status for the capture
        "redirectUrl": null,
        "contractId": null,
        "tokenId": null,
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "subscriptionManageUrl": null,
        "sign": "e3b4b41029d52d5abf07d7b78b58cf7840207a9bf7bb7e82f16ae6b2177aba86"
    }
}

Webhook (notifyUrl)

{
    "notifyType": "TXN",
    "transactionId": "1921486705937219584",
    "txnType": "CAPTURE",
    "merchantNo": "800209",
    "merchantTxnId": "6b38115b-f2a2-446e-aaa7-7fbaa106adf4",
    "responseTime": "2025-05-11 16:50:01",
    "txnTime": "2025-05-11 16:45:05",
    "txnTimeZone": "+08:00",
    "orderAmount": "54.00",
    "orderCurrency": "USD",
    "status": "S", // Success status for completed capture
    "cardBinCountry": "US",
    "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
    "sign": "74204385718b9327a8a3f3af03d16fd5130b2b9673277730aad4f627e2d32f19",
    "paymentMethod": "VISA",
    "channelRequestId": "8002091921486708126392321"
}

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 1: Duplicate Capture 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 captured
2. Implement proper transaction status tracking to avoid duplicate capture attempts
3. If funds are needed, consider creating a new authorization and capture

Implementation Best Practices

Capture Best Practices

1. Transaction Management:

   • Store the original authorization transactionId securely for later capture
   • Track authorization expiration dates to ensure timely captures
   • Implement proper error handling for failed captures

2. Capture Timing:

   • Capture as soon as goods are shipped or services provided
   • Be aware of the authorization validity period (typically 7 days)
   • Consider implementing automated reminder systems for pending authorizations

3. Transaction Tracking:

   • Maintain comprehensive records linking authorizations to their captures
   • Implement status tracking to prevent duplicate capture attempts
   • Create reconciliation processes to ensure all authorizations are either captured or voided

4. Webhook Handling:

   • Implement robust webhook processing to reliably receive capture 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 captures
   • Implement alerting for expired authorizations
   • Create customer service processes for handling capture failures

6. Partial Captures:

   • Note that partial captures are not supported; the entire authorized amount must be captured
   • If you need to capture less than the full amount, consider voiding the original authorization and creating a new one

7. User Experience:

   • Consider notifying customers when their payment has been captured
   • Provide clear transaction records showing both authorization and capture dates
   • Design your system to handle the delay between authorization and capture

Business Logic Considerations

1. Order Fulfillment Flow:

   • Align capture timing with your order fulfillment process
   • Consider automating captures based on order status changes
   • Ensure proper coordination between inventory, fulfillment, and payment systems

2. Reconciliation Practices:

   • Regularly reconcile authorized, captured, and voided transactions
   • Implement automated alerts for authorizations approaching expiration
   • Create reports to track authorization-to-capture conversion rates

3. Risk Management:

   • Monitor authorization-to-capture timeframes as potential fraud indicators
   • Implement appropriate security measures for storing authorization references
   • Consider implementing additional verification before capturing high-value transactions

Merchant Integration Checklist

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

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