Payment status changes as customers complete actions in your checkout flow. Your integration can inspect the payment status to determine results and take appropriate business actions.
status field in synchronous responses.| Method | Best for | Reliability |
|---|---|---|
| Client callback | Showing immediate feedback to users | Low—don't use for order fulfillment |
| API response | Direct API integrations | Medium—depends on client-side polling |
| Return URL | Redirect-based flows | Medium—requires polling |
| Webhooks | Order fulfillment and backend processing | High—recommended |
When using the onPaymentCompleted callback, the returned status indicates the payment result. Use this status only to display results to users—don't update your order system based on client-side status alone.
onPaymentCompleted: function (result) {
const { respCode, respMsg, data: txnInfo } = result
if (respCode === '20000') {
switch (txnInfo.status) {
case 'S':
// Show success message to user
// Query Order API for final confirmation before fulfillment
break
case 'R':
// 3DS verification required
window.location.href = txnInfo.redirectUrl
break
default:
// Handle unexpected status
break
}
} else {
// Show error: respMsg contains the failure reason
console.error('Payment failed:', respMsg)
}
}
| Status | What happened | Expected integration |
|---|---|---|
S | Payment succeeded | Query the Order Query APIPayments API for final status. If confirmed, update your order and notify the customer. |
F | Payment failed | Query the Order Query APIPayments API for final status. Create a new payment to allow retry. |
R | 3DS (3-D Secure) authentication required | Redirect the customer to the 3DS challenge page using txnInfo.redirectUrl. |
If you don't use onPaymentCompleted, you have two options to check payment status.
When calling the Direct APIPayments API, the response includes the payment status. Use this to update your order or execute subsequent business logic.
| Status | What happened | Expected integration |
|---|---|---|
S | Payment succeeded | Notify the customer and update your order. This is a final status. |
F | Payment failed | Notify the customer and update your order. Create a new payment to allow retry. This is a final status. |
R | Redirect required | Redirect the customer to the provided URL—either a 3DS (3-D Secure) challenge page or a local payment method page. |
P | Payment processing | Notify the customer that payment is processing. Poll the Order Query APIPayments API until you receive a final status. |
Include the returnUrl parameter with your order reference when calling the API. After payment completes, Onerway redirects to this URL with your order reference. Use the reference to poll the Order Query APIPayments API for final status.
Learn more about configuring return URLs.
Onerway sends webhook events to your server when a payment reaches a final status. Use webhooks for order fulfillment—don't rely on client-side processing because customers can leave the page before fulfillment initiates.
To receive webhooks, include the notifyUrl parameter when creating a payment request.
Onerway sends a POST request to your notifyUrl with a JSON payload:
{
"notifyType": "TXN",
"transactionId": "1920061365985615872",
"txnType": "SALE",
"merchantNo": "800209",
"merchantTxnId": "6a28ac11-d98c-4323-84a7-426b9322c4f7",
"responseTime": "2025-05-07 18:21:21",
"txnTime": "2025-05-07 18:21:17",
"txnTimeZone": "+08:00",
"orderAmount": "100.00",
"orderCurrency": "USD",
"status": "S",
"cardBinCountry": "US",
"reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
"sign": "345f09b2240dcd2084605c28024b4d6fe7da4f84e59a7268b92bb66a36c433b3",
"paymentMethod": "VISA"
}
| Status | What happened | Expected integration |
|---|---|---|
S | Payment succeeded | Notify the customer and update your order. |
F | Payment failed | Notify the customer. Create a new payment to allow retry. |
After processing the webhook, return only the transactionId value in your response body. This confirms successful receipt to Onerway.
transactionId for deduplication.For complete webhook parameters and examples, see the Transaction Webhooks API referencePayments API.
When processing webhooks, verify the signature to ensure the request came from Onerway.
originTransactionId, originMerchantTxnId, customsDeclarationAmount, customsDeclarationCurrency, paymentMethod, walletTypeName, periodValue, tokenExpireTime, sign. All other parameters—including any new parameters added in the future—are included.Learn more about handling webhook signaturesPayments API.
Some payment methods—like and —can't return results immediately. For these methods:
status: Rstatus: P (Pending).