Possible Gateway Responses

This guide provides a comprehensive overview of the transaction statuses and response codes you may encounter when integrating with the UPayments Gateway. These responses are categorized by payment method (KNET vs. Credit Card) and include technical reasons for each state.

Transaction Status Overview

The result or status field in your API response or Webhook payload will indicate the final outcome of the transaction.

Status	Payment Method	Meaning
CAPTURED	KNET / Credit Card	The transaction was successful, and funds have been secured.
NOT CAPTURED	KNET	The transaction was not completed, often due to incorrect card details or a timeout.
CANCELED	KNET	The customer explicitly clicked the "Cancel" button on the KNET gateway page.
FAILED	Credit Card	The transaction was rejected by the issuing bank or risk engine.
PENDING	Credit Card	The transaction is awaiting a 3D Secure (3DS) challenge or additional verification.
APPROVED	Credit Card	For Authorization transactions, the transaction has been successfully authorized but may require a capture API call step to become "CAPTURED".
VOIDED	Credit Card	An authorized (APPROVED) transaction has been cancelled before the capture process was initiated

Common Status Scenarios and Reasons

1. KNET (Local Debit Cards)

CAPTURED:
- Reason: The customer successfully completed the payment on the KNET portal.
- Automation: If a successful result is not immediate, a system CRON job runs every 13 minutes to verify the status with KNET and update it to CAPTURED.
NOT CAPTURED:
- Reason: Customer entered incorrect card details (e.g., wrong PIN or expiration).
- Reason: The system failed to receive a success confirmation from KNET within the monitoring window.
CANCELED:
- Reason: The customer clicked "Cancel" on the KNET page.

2. Credit Cards (Mastercard / Visa / Digital Wallets)

FAILED:
- Reason (Decline): The bank rejected the charge (e.g., Response Code 05: Do not honour).
- Reason (Expired): The card has passed its expiration date (Response Code 54: Expired card).
- Reason (Risk): UPayments or Bank Issuer's or Payment Gateway's risk engine rejected the transaction due to rule violations, such as MSO_3D_SECURE (failed authentication) or MSO_IP_COUNTRY restrictions.

Gateway Response Codes & Explanations

For common error response codes, when a transaction is not successful, the gateway provides specific codes to help diagnose the failure, for more details go to Full Error Code page

Gateway Code	Result	Explanation
00	Successful	Transaction Approved.
05	Fail	Do Not Honour: Failed security check or frozen/depleted funds.
14	Fail	Invalid Card Number: The credit card number does not exist.
51	Fail	Insufficient Funds: Customer lacks the balance to complete the charge.
54	Fail	Expired Card: Customer should use an alternate card.
61	Fail	Exceeds Withdrawal Limit: Transaction exceeds the customer's card limit.
72	Fail	UNSPECIFIED_FAILURE: Temporary bank system error.
82	Fail	CVV Validation Error: Incorrect security code entered.
94	Fail	Duplicate Transaction: Transmission appears to be a duplicate.
AA	Fail	PG_UNSPECIFIED_FAILURE: General system error.
BB	Fail	ACQUIRER_SYSTEM_ERROR: The bank's system is temporarily unavailable.

Integration Best Practices

Webhook as Source of Truth: Always rely on your notificationUrl (webhook) to receive the final terminal status, as it captures the result even if the customer closes their browser before redirection.
Status Inquiry Fallback: Use the Get Payment Status API to reconcile transactions if a webhook is delayed or not received.
Handling "Processing" (NULL Result): If the result is NULL Pending or ProcessingDo not treat it as a failure, wait for the system CRON job to finalize the status (up to 13 minutes for KNET).