PayTabs SDK makes the integration with the PayTabs payment gateway very easy by providing a ready-made payment screen that handles the card entry and, billing & shipping information and completes the missing details.


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 navigate to your "PaymentManagerDelegate" class and start building your business case as shown in the below example:


extension ViewController: PaymentManagerDelegate {
    func paymentManager(didFinishTransaction transactionDetails: PaymentSDKTransactionDetails?, error: Error?) {
       if transactionDetails.isSuccess() {
               // Use the checkers here according to your business needs
          }
        else if let error = error {
               // Use the checkers here according to your business needs
        }
    }
}


As you may be noticed in the example, within the delegate, you will initiate a lambda paymentManager function in which you will pass one of the below protocol methods to handle the payment response through:




didFinishTransaction()


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

  • @ objc func paymentManager(didFinishTransaction transactionDetails: PaymentSDKTransactionDetails?, error: Error?)


PaymentSDKTransactionDetails Properties


PropertyData TypeUsage
tokenStringThe sent token for the tokenized payment requests. This field is required for creating tokenized (recurring) transactions. To know more, please check our sss solution article.
transactionReferenceStringThe unique key for the transaction generated by the PayTabs. 

This field is required for creating tokenized (recurring) transactions.
transactionTypeStringThe identification of the type of transactionTo 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 2.3 Native IOS SDK | Enums solution article.

The default passed value is ".sale".
cartIDStringIndicates the cart/order id at the merchant end to easily relate the transaction to
cartDescriptionStringIndicates the cart/order description at the merchant end to easily relate the transaction to.
cartCurrencyStringIndicates the transaction currency, which the customer will be charged with. Noting that this currency must be configured first on your PayTabs account to accept payment with.
cartAmountStringIndicates the amount of this transaction the customer is about to be charged.
paymentResultPaymentSDK.PaymentResultViewModel ObjectresponseStatusStringIndicates the status of the performed transaction, which will be one from the list clarified in our What is: Response_code vs the Response_status? solution article.
responseCodeStringIndicates the code of the performed transaction, which will be one from the list clarified in our What is: Response_code vs the Response_status? solution article.
responseMessageStringIndicate the message/description of the performed transaction.
transactionTimeString

Indicate the exact time that transaction is completed

acquirerMessageString

Indicates the message sent from the acquirer

acquirerRRNString

Indicates the transaction reference on the acquirer end

paymentInfoPaymentSDK.PaymentInfoViewModel ObjectcardTypeString

Indicates the card type (Credit, Debit, etc.)

cardSchemeStringIndicates the card Scheme (Visa, MasterCard, etc.)
paymentDescriptionStringIndicates the card mask/number ("4000 00## #### 0002")
billingDetails
PaymentSDK.PaymentSDKBillingDetails ObjectnameString

Indicates the customer's/cardholder's valid name

emailStringIndicates the customer's valid email address. Preferred not to pass the same email with every transaction, as blocking any for a fraud attempt will cause blocking your payments at all.
phoneStringIndicates the customer's valid phone number
addressLineStringIndicates the customer's valid address
cityStringIndicates the customer's valid city name.
stateStringIndicates the customer's valid state name. It should be ISO 3166-1 alpha-2 code (two-letter state codes)
countryCodeStringIndicates the customer's valid state name. It should be

ISO 3166-1 alpha-2 code (two-letter state codes)

zipStringIndicates the customer's valid zip code.
shippingDetails
PaymentSDK.PaymentSDKShippingDetails ObjectnameString

Indicates the customer's/cardholder's valid name

emailStringIndicates the customer's valid email address.
phoneStringIndicates the customer's valid phone number
addressLineStringIndicates the customer's valid address
cityStringIndicates the customer's valid city name.
stateStringIndicates the customer's valid state name. It should be ISO 3166-1 alpha-2 code (two-letter state codes)
countryCodeStringIndicates the customer's valid state name. It should be

ISO 3166-1 alpha-2 code (two-letter state codes)


zipStringIndicates the customer's valid zip code.


We also provide within the same PaymentSDKTransactionDetails object multiple checkers that can assist you through your system/business flow, as shown below, which highly recommend using them to handle the response in the PaymentManagerDelegate class:


It worth mentionting, that all the responses and statuses the following checkers relies on are the official supported one listed in our What is: Response_code vs the Response_status? solution article.


isAuthorized()


This function 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?.responseCode attribute.


It acts as like as shown below:

self.paymentResult.responseStatus == "A"

isPending()


This function 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/processor is pending. For example, the cash payment that exists in the Fawry payment method will be marked as pending until the customer pays the transaction at one of the Fawry machines.


It acts as like as shown below:

self.paymentResult.responseStatus == "P"

isOnHold()


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:

self.paymentResult.responseStatus == "H"


isSuccess()


This function 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:

isAuthorized() || isPending() || isOnHold()

isProcessed()


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.


It acts as like as shown below:

paymentResult != nil

didReceievValidation()


Via this protocol method, you will handle your sent request only if the payment doesn't exceed the validation. 

  • @objc optional func paymentManager(didRecieveValidation error: Error?)



didCancelPayment()


Via this protocol method, 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. 

  • @objc optional func paymentManager(didRecieveValidation error: Error?)



didStartPaymentTransaction()


Via this protocol method, you can perform whatever business you need before sending/starting your payment. 

  • @objc optional func paymentManager(didStartPaymentTransaction rootViewController: UIViewController)










⌂ To get familiar with the whole process and the other steps, kindly navigate to our "The Native IOS SDK Integration Manual" solution article. 

 And to navigate to the previous step in the integration process "Step 4 - Accepting the payment" kindly click here.
Or you can navigate to the next step in the integration process " Step 6 - Handle the post-payment responses (notifications)" kindly click here.