Authorization

API Request Parameters

POST

Key Parameters for Authorization

When integrating authorization payments, you need to adjust one key parameter compared to regular Checkout:

1. txnType: Must be set to AUTH for authorization transactions.

Authorization Integration Process

The Onerway authorization process consists of three main phases as illustrated below:

1. Authorization Initiation

In this phase:

• Merchant system sends an authorization request to Checkout API with txnType=AUTH
• Authorization does not immediately capture funds, only reserves them
• Onerway creates a transaction record for the authorization
• The initial authorization status is Unfinished (U)

2. Checkout Process

In this phase:

• Merchant redirects the customer's browser to the Onerway checkout page using the redirectUrl
• Customer selects a payment method and enters payment information
• If 3DS verification is required, the customer completes this step before the authorization is established
• The payment is authorized but funds are not captured until a separate capture request is made

3. Authorization Confirmation

In this phase:

• Synchronized notification: Customer is redirected back to the merchant's website through the returnUrl
• Asynchronous notification (webhook): Onerway sends detailed authorization result data to the notifyUrl
• The webhook contains complete authorization information including transactionId, and status
• Merchant system must respond with transactionId to acknowledge receipt of the webhook
• If no successful response is received, Onerway will retry sending the webhook 3 times

For a complete description of all webhook notification fields received during authorization transactions, please refer to the Webhook Notification Documentation.

Payment Completion Examples

Redirect to Merchant (returnUrl)

https://docs.onerway.com/?transactionId=1914565388776378368&merchantTxnId=4f581f27-fe1a-4a80-8e10-2b3751ffb785&merchantNo=800209&responseTime=2025-04-22%2014:22:51&txnTime=2025-04-22%2014:22:42&txnTimeZone=+08:00&orderAmount=83.00&orderCurrency=USD&status=S&reason=Success

Server Notification (notifyUrl)

{
  "notifyType": "TXN",
  "transactionId": "1914565388776378368", // Required as originTransactionId for capture
  "txnType": "AUTH", 
  "merchantNo": "800209",
  "merchantTxnId": "4f581f27-fe1a-4a80-8e10-2b3751ffb785",
  "responseTime": "2025-04-22 14:22:51",
  "txnTime": "2025-04-22 14:22:42",
  "txnTimeZone": "+08:00",
  "orderAmount": "83.00",
  "orderCurrency": "USD",
  "status": "S",
  "eci": "05",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "ec866293c15c4def1bad161c13f77153d560660065807612547d1c05a5de47bc",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091914565512046706689"
}

4. Capture Process

In this phase:

• Authorization holds funds but does not transfer them
• To complete the payment, merchant must send a separate capture request
• The capture request references the original authorization using originTransactionId
• Funds are transferred only after a successful capture
• Authorizations expire if not captured within the specified time period (typically 5 days)

Important Notes

• Authorization holds funds but does not transfer them: A separate capture request is required to settle the transaction
• Merchants must use Capture API to settle the authorization
• Authorized funds are typically held for 7 days (varies by card issuer) before being automatically released
• Only full capture is supported: Partial capture is not available, you must capture the entire authorized amount
• Always rely on webhook notifications as the definitive source for transaction status
• Multiple webhook notifications may be received; deduplication based on transaction ID is recommended
• Transaction status S indicates success, F indicates failure; refer to TxnStatusEnum for other status codes

API Usage Examples

Authorization Request

{
    "billingInformation": "{\"address\":\"6279 Mayfield Road\",\"city\":\"Karolannshire\",\"country\":\"US\",\"email\":\"Delores.Thiel1@gmail.com\",\"firstName\":\"Khalid\",\"identityNumber\":\"86032961732\",\"lastName\":\"Berge\",\"phone\":\"14064876575\",\"postalCode\":\"43936\",\"province\":\"CO\"}",
    "merchantCustId": "CustId-CIZ4-91M9",
    "merchantNo": "800209",
    "merchantTxnId": "4f581f27-fe1a-4a80-8e10-2b3751ffb785",
    "merchantTxnTime": "2025-04-22 14:22:11",
    "orderAmount": "83",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"639 Myrtle Green\",\"city\":\"Ubaldostead\",\"country\":\"US\",\"email\":\"Lucious.Feeney38@gmail.com\",\"firstName\":\"Lorna\",\"identityNumber\":\"42993160796\",\"lastName\":\"Pfannerstill\",\"phone\":\"16320585629\",\"postalCode\":\"83968\",\"province\":\"CO\"}",
    "sign": "b82354f9a98625d413228fb99c1b375c67ff913dee3d4ad65b442b54e2f38157",
    "subProductType": "DIRECT",
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"32\",\"contentLength\":\"16384\",\"javaEnabled\":false,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"tomato\\\",\\\"num\\\":\\\"90\\\",\\\"price\\\":\\\"544.09\\\",\\\"type\\\":\\\"et ad quis laborum\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"lemon\\\",\\\"num\\\":\\\"100\\\",\\\"price\\\":\\\"31.19\\\",\\\"type\\\":\\\"et est minim in\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"aubergine\\\",\\\"num\\\":\\\"65\\\",\\\"price\\\":\\\"585.69\\\",\\\"type\\\":\\\"dolor deserunt minim\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"1800\",\"screenWidth\":\"800\",\"timeZoneOffset\":\"-540\",\"transactionIp\":\"187.178.122.99\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36\"}",
    "txnType": "AUTH"
}

Authorization Response

After sending a authorization request, you will receive a response with important information for redirecting the customer to complete their payment.

Payment Redirect

If the request is successful, merchants need to extract the redirectUrl from the response parameters and redirect the user to that URL.

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1914565388776378368",
        "merchantTxnId": "4f581f27-fe1a-4a80-8e10-2b3751ffb785",
        "merchantNo": "800209",
        "responseTime": "",
        "txnTime": "",
        "orderAmount": "83.00",
        "orderCurrency": "USD",
        "txnAmount": "",
        "txnCurrency": null,
        "txnTimeZone": null,
        "status": "U",
        "reason": null,
        "redirectUrl": "https://sandbox-checkout.onerway.com/checkout?key=d081179063f64621bf024119e03a029f&checkoutDetail=H4sIAAAAAAAAAMVWTXPbNhD9Kx6eLQkESQDUqTLtTDSxnYwkp9N2cgBBUGJKgSwAStF4%2FN%2B74IcsuZq0zaG9aIiH3cW%2B3YeFnj1e1%2FPMm3o%2BxZQxxEISUBYin8bYu%2Fa2UosNV%2Fax8qYMIYziE4xvJTjOUlmeWK6%2BqTZemEfMzzEd5dLno5AzNGLSRyOcBjTy8zylLDp3WxVtPIxwNELhCOMrP5xiPPWDv9r9WimwVU1ZXnsWoEPdpvK0eu%2B1wGxbNcoCxIIxQh2WNFpLJQ6APi1vATNN%2BklXWSNs7387X9wlK9gRXGcOm6sciP%2F27BVAyQ9ZQDAmNGYkJFHEKH61BO%2FP8%2BUMfOuzkMls4Y4qq3X1idsNIBtrazOdTHSlgFAmd1VtsoKvx2lZpWNRaTneFyqr9maspJ1UO6nht5aa26JSo71MRyZLv02Gk%2B8h9IT6uQy5YLkkQgaChmmIfUlZjlNGMszGtVqf8Opb12cMdUj6DdMV9eX6jHKEcRxTwgh%2BQ%2FlhtlzdLXqO%2FwtxlufIRwHhPJNCRrHEWZ75Mag5zXOf0cvEz%2FL%2BO%2FoBCqIIBYyRICBn9G%2Fny%2BTj57vFvyBfc3Go%2BeE7vHsL7HbfcA3CnGVIMCowkzGS1Kck40xgmgsao%2FHX%2BgLXkyS%2FyzREMfwEzGdRDBedvWH6eLdYJvdPN%2F8RVxRikhJK%2FBQz5PsIlJcSyQXJM2ix8C%2F39SzNC2y%2FXHsgI1NYZ1xWgpebyliwTYuyLNR6lmVaGrD29vv92EpjIedtf043DLqZI%2FNcClvs5EOhGuviB6gdMh91JvWDWQ%2BGfWDnq7etkL3ps5cX2gzz88OGl9ACqCA%2FYjdSr6Wr9Kadc54fIhIySiLqZqbc8qJ0bGUJBTXj1aaQpf%2FT2sF9vjXQ4mVSZc47DOKAAMiP7OAix1cP%2FJCDY3a1qLg7X7iRqbvx2HV5VyjRtvij2y6s2%2FvAdVVypcym0C5FY7WUdqCrmm0q9bAqMqksuD32qMcICnBMfBrgtujabm65PU7yr%2FW718IM0D0%2FRV7avhqhi7orZmemZQbpCPukywGCAtjGkV22z4cxfH2MaqpGC5nAGFLSVVJspPi9amz3UHTvYeyHEYng2lPqnsSAMM%2BdYxut2lOOMs8qYcbQJ73nB1f%2BSasXqFx5ko3VXBkuXM6tRB6PUgL9b6FMyXn1h4weoIWlGWzbfiWVyot1o%2FlpAYDtWpozmfUdkftkYPf2xJM471xk0751qtOgk%2Fz7qnS5OsBx%2F6NxPZ96v8Bqx8vGfcNnVpi65Id2ww2UkwDQ%2BR%2Fx3O1%2BwOt4J1tJ%2FVP%2FL90dvVwM2NyAiG8uXOKcl0Z22z8PI6XHoPlz5e5f6cp8hFOQQN88NwPa5dASNz3n2xOFptxIErpROCCigts%2BLHaF3Pf%2FtF6BpBXdjVVnYKerI%2FrSitgJbbg5sJhlu0IMN%2BxPnQozSRQKAAA%3D", 
        "sign": "50f97970bf12bce0c9762628e062bef4131c9a91dc3d7f5518d2e950a307f327",
        "contractId": "",
        "tokenId": null,
        "eci": null,
        "transactionOrderNo": null,
        "periodValue": null,
        "lpmsType": null,
        "qrCode": null,
        "subscriptionManageUrl": null
    }
}

Implementation Best Practices

Checkout Authorization Best Practices

1. Transaction Configuration:

   • Set txnType: 'AUTH' for authorization transactions
   • Configure a valid and accessible returnUrl in your request for user redirection after payment
   • Set up a secure notifyUrl endpoint to receive webhook notifications
   • Use consistent format for merchantTxnId to facilitate tracking and reconciliation

2. Redirect Management:

   • Securely store the transactionId before redirecting customers to the checkout page
   • Implement proper error handling for the redirect process
   • Create a user-friendly return page that can handle both success and failure scenarios
   • Consider implementing a session timeout handling mechanism for abandoned payment flows

3. Webhook Processing:

   • Verify webhook signatures to ensure authenticity of notifications
   • Implement idempotent webhook processing to handle potential duplicate notifications
   • Process webhooks asynchronously to avoid timeout issues
   • Always respond with the transaction ID upon successful webhook processing

4. Authorization Management:

   • Store the transactionId from webhook notifications for subsequent capture
   • Track authorization expiration dates (typically 7 days)
   • Implement a systematic approach to determine when to capture each authorization
   • Use the Capture API to complete the payment when appropriate

5. User Experience:

   • Clearly communicate to customers that their payment is an authorization only
   • Provide clear status updates when the authorization and subsequent capture are completed
   • Design user interfaces that properly explain the two-step payment process
   • Display appropriate messages during the checkout process to set correct expectations

6. Security Considerations:

   • Implement HTTPS for all communication endpoints
   • Use proper session management for the payment flow
   • Validate all input data before processing
   • Monitor for unusual payment patterns or potential fraud indicators

7. Reconciliation and Reporting:

   • Maintain proper records of authorizations and captures for reconciliation
   • Implement a systematic approach to match authorizations with captures
   • Track uncaptured authorizations to prevent funds being held unnecessarily
   • Regularly reconcile authorization and capture transactions

8. Error Handling:

   • Implement graceful error handling for network issues, timeouts, and server errors
   • Design clear error messages for customers when payment issues occur
   • Create logging mechanisms to track and troubleshoot authorization issues
   • Develop retry mechanisms for failed authorization captures

By following these best practices, merchants can effectively implement the checkout authorization flow while providing a positive customer experience and maintaining security.