Step 5 - Handle the payment response

PayTabs Mobile SDKs streamline the integration process with the PayTabs payment gateway by offering a pre-configured payment interface. This interface efficiently manages card data entry, billing and shipping information, and automatically supplements any missing details required to complete the transaction flow.

This article is dedicated to walking you through how to handle the payment response after performing it. Handling the response right will prevent your application from crashing on any unhandled response status or any missing case.

To perform such, you will need to implement the interface CallbackPaymentInterface within your entry point activity/fragment instance and start building your business case as shown in the below example:

import com.payment.paymentsdk.sharedclasses.interfaces.CallbackPaymentInterface
import com.payment.paymentsdk.integrationmodels.PaymentSdkError
import com.payment.paymentsdk.integrationmodels.PaymentSdkTransactionDetails

class MainActivity : ComponentActivity(), CallbackPaymentInterface  {

    override fun onError(error: PaymentSdkError) {
              // Implement according to your business needs
    }

    override fun onPaymentFinish(PaymentSdkTransactionDetails: PaymentSdkTransactionDetails) {
             // Use the checkers here according to your business needs
    }

    override fun onPaymentCancel() {
                 // Implement according to your business needs
    }
}

As you may be noticed in the example, within the activity, you will override our event handlers' functions to handle the payment response accordingly:

onPaymentFinish

Via this event handler, you will handle the payment response. Through the PaymentSdkTransactionDetails object, you will receive the response that should be handled from your side according to your business needs depending on the sent information/parameters as clarified below:

import com.payment.paymentsdk.sharedclasses.interfaces.CallbackPaymentInterface
import com.payment.paymentsdk.integrationmodels.PaymentSdkTransactionDetails
import android.widget.Toast

class MainActivity : ComponentActivity(), CallbackPaymentInterface  {

    override fun onPaymentFinish(PaymentSdkTransactionDetails: PaymentSdkTransactionDetails) {
        
         if (paymentSdkTransactionDetails?.isSuccess) {
            Toast.makeText(
                this,
                "Payment has been completed successfully.",
                Toast.LENGTH_SHORT
            ).show()
        }
         
    }
}

Property	Data type
transactionReference	String
	The unique key for the transaction generated by the PayTabs. This field is required for creating tokenized (recurring) transactions. For more details about the transaction Reference through API integration, please click here.
transactionType	String
	The identification of the type of transaction. To know more about these types, please check our What is the "tran_type" (transaction type)? solution article. To know more about the only types that are supported in this SDK, please check our Enums - Transaction Types solution article. The default passed value is ".sale".
cartID	String
	Indicates the cart/order id at the merchant end to easily relate the transaction to.
cartDescription	String
	Indicates the cart/order description at the merchant end to easily relate the transaction to.
cartCurrency	String
	Indicates the cart currency, which the customer will be charged with. Noting that this currency must be configured first on your PayTabs account to accept payment with.
cartAmount	String
	Indicates the amount of this transaction the customer is about to be charged.
payResponseReturn	String
	Indicates the transaction status value in text name.
paymentResult	PaymentSdkPaymentResult
	Object containing the payment result details.
paymentInfo	PaymentSdkPaymentInfo
	Object containing the payment information details.
redirectUrl	String
errorCode	String
	Transaction error code if exists.
errorMsg	String
	Transaction error message if exists.
token	String
	The sent token for the tokenized payment requests. This field is required for creating tokenized (recurring) transactions. To know more, please check our click here manual.
billingDetails	PaymentSdkBillingDetails
	Indicates the billing details of the customer or card holder.
billingDetails's Nested Parameters Nested Parameter Data Type Min Max Required city STRING 3 128 ✘ countryCode STRING N/A N/A ✘ email STRING N/A N/A ✘ name STRING 3 128 ✘ phone STRING N/A N/A ✘ state STRING 2 2 ✘ addressLine STRING 3 128 ✘ zip STRING N/A N/A ✘
shippingDetails	PaymentSdkShippingDetails
	Indicates the shipping details of the customer.
isSuccess	Boolean
	This aims to check for you whether the payment has been performed successfully which means its status will be either H, P, or A, which indicates that the payment is successfully operated/authenticated and registered on your PayTabs dashboard accordingly to each status clarification. It acts as like as shown below: PaymentSdkTransactionDetails.isAuthorized || PaymentSdkTransactionDetails.isPending || PaymentSdkTransactionDetails.isOnHold
isAuthorized	Boolean
	This aims to check for you whether the payment status is A, which indicates that the payment is successfully operated, authenticated, and registered on your PayTabs dashboard for both PayTabs and the acquirer bank/processor. if the transaction is not successful then you will have to check for the corresponding failure code which you will receive in the transactionDetails?.paymentResult?.responseStatus. It acts as like as shown below: paymentResult?.responseStatus === "A"
isPending	Boolean
	This aims to check for you whether the payment status is P, which indicates that the payment is successfully operated and registered on your PayTabs dashboard, however, its status on the acquirer bank/processer is pending. For example, cash payment such exists in the aman payment method will be marked as pending until the customer pays the transaction at one of the aman machines. It acts as like as shown below: paymentResult?.responseStatus == "P"
isOnHold	Boolean
	This function aims to check for you whether the payment status is H, which indicates that the payment is successfully operated/authenticated and registered on your PayTabs dashboard, however, its status on the acquirer bank/processer is on hold. For example, refunds that are operated manually by the Knet team will be marked as on hold. It acts as like as shown below: paymentResult?.responseStatus == "H"
isProcessed	Boolean
	This function aims to check for you whether the payment has been processed in the first place or not. In some very rare cases, the acquirer bank/protocol doesn't immediately initiate the payment due to several reasons (such as an internal server error on their side), which lead that the transaction itself will be authenticated and registered a while after performing it (up to several hours in some cases), in this case, and as PayTabs didn't receive the response from the acquirer, the object will be returned with null. In such cases You will be notified once the transaction registered on the dashboard ONLY if you configured an IPN, to know more about how to handle IPNs please check our How to configure Instant payment notification (IPN)? solution article.
tran_currency	String
	Indicates the transaction currency, which the customer charged with.
tran_total	String
	Indicates the total amount the customer charged.
serviceId	String
	The transaction service ID.
merchantId	String
	The merchant ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..
profileId	String
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..
trace	String
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..

onResult

Via this event handler, you will handle the query transaction response. Through the TransactionResponseBody object, you will receive the response that should be handled from your side according to your business needs depending on the sent information/parameters as clarified below:

import com.payment.paymentsdk.QuerySdkActivity
import com.payment.paymentsdk.sharedclasses.interfaces.CallbackQueryInterface
import com.payment.paymentsdk.sharedclasses.model.response.TransactionResponseBody
import com.payment.paymentsdk.integrationmodels.PaymentSDKQueryConfiguration

class MainActivity : ComponentActivity(), CallbackQueryInterface  {
    
    fun queryRequest(queryConfigData: PaymentSDKQueryConfiguration) {
        
        QuerySdkActivity.queryTransaction(this, queryConfig, this)
        
    }

     override fun onResult(transactionResponseBody: TransactionResponseBody) {
         
        showToast("Payment result received.")
        
    }
}

Property	Data type
tranRef	String
	The unique key for the transaction generated by the PayTabs. This field is required for creating tokenized (recurring) transactions. For more details about the transaction Reference through API integration, please click here.
tranType	String
	The identification of the type of transaction. To know more about these types, please check our What is the "tran_type" (transaction type)? solution article. To know more about the only types that are supported in this SDK, please check our Enums - Transaction Types solution article. The default passed value is ".sale".
cartId	String
	Indicates the cart/order id at the merchant end to easily relate the transaction to.
cartDescription	String
	Indicates the cart/order description at the merchant end to easily relate the transaction to.
cartAmount	String
	Indicates the amount of this transaction the customer is about to be charged.
paymentResult	PaymentSdkPaymentResult
	Object containing the payment result details.
paymentInfo	PaymentSdkPaymentInfo
	Object containing the payment information details.
returnX	String
redirectUrl	String
token	String
	The sent token for the tokenized payment requests. This field is required for creating tokenized (recurring) transactions. To know more, please check our click here manual.
customerDetails	PaymentSdkBillingDetails
	Indicates the billing details of the customer or card holder.
shippingDetails	PaymentSdkShippingDetails
	Indicates the shipping details of the customer.
tran_currency	String
	Indicates the transaction currency, which the customer charged with.
tran_total	String
	Indicates the total amount the customer charged.
serviceId	String
	The transaction service ID.
merchantId	String
	The merchant ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..
profileId	String
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..
code	Integer
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..
trace	String
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..

onError

Via this event handler function, you will handle your sent request only if the payment doesn't exceed the validation.

import com.payment.paymentsdk.sharedclasses.interfaces.CallbackPaymentInterface
import com.payment.paymentsdk.integrationmodels.PaymentSdkTransactionDetails
import android.widget.Toast

class MainActivity : ComponentActivity(), CallbackPaymentInterface  {

    override fun onError(error: PaymentSdkError) {
        Toast.makeText(this, "${error.msg}", Toast.LENGTH_SHORT).show()
	}
}

Property	Data type
code	Integer
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..
msg	String
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..
trace	String
	The merchant Profile ID you can get from your PayTabs dashboard. For more information please check our How to get your account information from PT Dashboard? solution article..

onCancel

Via this event handler function, you will handle your sent request only if the customer has triggered the cancel event, or in other words, the customer has canceled the payment.

import com.payment.paymentsdk.sharedclasses.interfaces.CallbackPaymentInterface
import com.payment.paymentsdk.integrationmodels.PaymentSdkTransactionDetails
import android.widget.Toast

class MainActivity : ComponentActivity(), CallbackPaymentInterface  {

    override fun onPaymentCancel() {
        Toast.makeText(this, "Payment attempt has been Cancelled", Toast.LENGTH_SHORT).show()
    }
}