Skip to main content

Step 3 - Initiating the payment



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 initiate the payment request payload using the configuration options and parameters that have already been clarified in the previous step, "Step 2 - Configure the integration method".

Then after that, you can easily initiate your payment using one of the following categories supported in this Cordova SDK as listed below:

Which you will need first to be aware of how to Manage Shipping and Billing details among any of the above categories:



Mobile SDKs Workflow​

This Diagram outlines the simplified workflow of the PayTabs Mobile SDK integration, illustrating the sequence of interactions between the key components involved in a mobile payment transaction. The diagram provides a clear and concise representation of the communication flow between the Customer, Mobile Application, PayTabs SDK, PayTabs Gateway, and the Merchant Server.

This will assist you understanding the operational logic and integration touchpoints required to implement a seamless payment experience using the PayTabs Mobile SDK. It highlights the initialization process, user interaction with the payment interface, transaction processing, and post-payment IPN/Callback handling for order status updates.

By following this workflow, merchants can ensure secure, efficient, and user-friendly payment processing within their mobile applications.




Manage Shipping and Billing details​

You will first need to be aware of how to Manage Shipping and Billing details among any of the following payment initiations:



Show Billing/Shipping Information Section​

These are boolean parameters that indicate whether to hide billing/shipping information or not from the payment form screen.

Note that the customer details are still required and MUST be passed. In case any of the details are missing or passed with invalid values, the request will fail, and the SDK will throw an exception.

Be Aware

By default, the billing and shipping info section is disappeared, sets its flag to true to let the SDK internally handle the missing billing & shipping info.

configuration.showBillingInfo = true
configuration.showShippingInfo = true



Force Shipping Information Validation​

This is a boolean parameter that indicates whether to force the customer to provide the shipping information or not.

Be Aware

By default, the validation on shipping info is disabled.

You can set it while you build the configuration as shown below:

configuration.forceShippingInfo = true



Pay with Card​

Implementing this option will enable you to initiate payments targeted to be paid using the supported types of credit cards configured in your profile. You will have the ability to perform a card payment in one of the below ways/options:

Payment With Card
To learn how to set up payment with card, please click here to review the steps.

Payment With Card​

You will need to import the Cordova SDK class in your code first to start, as shown below: 

"cordova": {
    "plugins": {
        "com.PayTabs.cordova.plugin": { }
    }
}

Implementing this option will enable you to initiate payments targeted to be paid using the supported types of credit cards such as Visa, MasterCard, Amex, etc. To be able to do this, please follow the below instructions:

  1. Make sure you import the desire classes as mentioned above.


  2. Configure the billing & shipping information for this payment, noting that the shipping information is optional. To know more about this, please check above Manage Shipping and Billing details and Configuration Options & Parameters manual.


    let billingDetails = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKBillingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

    let shippingDetails = new cordova.plugins.CordovaPaymentPlugin. PaymentSDKShippingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

  3. Then create an object from the PaymentSDKConfiguration and fill it out with your credentials and payment details . To know more about what is the exact values that should be passed here, please check the SDK Configuration Options & Parameters manual.


    let configuration = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKConfiguration();
    configuration.profileID = profileID
    configuration.serverKey = serverKey
    configuration.clientKey = clientKey
    configuration.cartID = cartID
    configuration.currency = "SAR"
    configuration.cartDescription = cartDescription
    configuration.merchantCountryCode = "SA"
    configuration.merchantName = merchantName
    configuration.amount = 0.5
    configuration.billingDetails = billingDetails

  4. Only then you will be ready to start/initiate the payment by passing your PaymentSDKConfiguration object to the startCardPayment function. To know more about this please check the SDK Configuration Options & Parameters manual and Step 5 - Cordova SDK | Handle the payment response manaul.

    cordova.plugins.CordovaPaymentPlugin.startCardPayment(configuration, function (result) {
        if (result["status"] == "success") {
            // Handle transaction details here.
            var transactionDetails = result["data"];
        } else if (result["status"] == "error") {
            // Handle error here the code and message.
        } else if (result["status"] == "event") {
            // Handle events here.
        }
    }, function (error) {
        console.log(error)
    });

    This will make the payment behavior would be like the one below, in which your customers will have to provide their full card details.


Tokenized Card Payment (Recurring)
To learn how to set up recurring payment, please click here to review the steps.

Tokenized Card Payment (Recurring)​

To enable tokenization (for recurring or any other services that depend on auto-detection from the customers instead of saving credit card details), please follow the below instructions:

  1. Request a token in creating any payment request by passing the tokeniseType along with the tokeniseFormat with the preferred type and format that suits your business needs within your PaymentSDKConfiguration, as shown below.


    configuration.tokeniseType = cordova.plugins.CordovaPaymentPlugin.TokeniseType.userOptinoal
    configuration.tokeniseFormat = cordova.plugins.CordovaPaymentPlugin.TokeniseFromat.hex32
    Be Aware
    To know more about these parameters and what are the available values you can pass please check the "2.3 Native Android SDK | Enums" manual.

  2. Configure the billing & shipping information for this payment, noting that the shipping information is optional. To know more about this, please check above Manage Shipping and Billing details and Configuration Options & Parameters manual.


    let billingDetails = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKBillingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

    let shippingDetails = new cordova.plugins.CordovaPaymentPlugin. PaymentSDKShippingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

  3. Then create an object from the PaymentSDKConfiguration and fill it out with your credentials and payment details don't forget to set "tokeniseType", and "tokeniseFormat". To know more about what is the exact values that should be passed here, please check the SDK Configuration Options & Parameters manual.


    let configuration = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKConfiguration();
    configuration.profileID = profileID
    configuration.serverKey = serverKey
    configuration.clientKey = clientKey
    configuration.cartID = cartID
    configuration.currency = "SAR"
    configuration.cartDescription = cartDescription
    configuration.merchantCountryCode = "SA"
    configuration.merchantName = merchantName
    configuration.amount = 0.5
    configuration.billingDetails = billingDetails

    configuration.tokeniseType = cordova.plugins.CordovaPaymentPlugin.TokeniseType.userOptinoal
    configuration.tokeniseFormat = cordova.plugins.CordovaPaymentPlugin.TokeniseFromat.hex32

  4. Only then you will be ready to start/initiate the payment by passing your PaymentSDKConfiguration object to the startCardPayment function. To know more about this please check the SDK Configuration Options & Parameters manual and Step 5 - Cordova SDK | Handle the payment response manaul.

    cordova.plugins.CordovaPaymentPlugin.startCardPayment(configuration, function (result) {
        if (result["status"] == "success") {
            // Handle transaction details here.
            var transactionDetails = result["data"];
        } else if (result["status"] == "error") {
            // Handle error here the code and message.
        } else if (result["status"] == "event") {
            // Handle events here.
        }
    }, function (error) {
        console.log(error)
    });

    This will make the payment behavior would be like the one below, in which your customers will have to provide their full card details.


  5. After the customer complete a successful authorized payment, you will receive the token along with the transaction reference (that generated this token) within your interface/class in which you handled the payment response. You will need to save them for future usage.


  6. Then perform any further recurring transaction according to your business needs by repeating steps 2, 3, and 4 from this order steps, then directly start the tokenized card payment via the startTokenizedCardPayment function by passing the PaymentSDKConfiguration object along with the token and the transaction reference (saved from the previous step).

    cordova.plugins.CordovaPaymentPlugin.startTokenizedCardPayment(
        configuration,
        "Token",
        "TransactionReference",
        function (result) {
            if (result["status"] == "success") {
                // Handle transaction details here.
                var transactionDetails = result["data"];
                console.log("responseCode:" + transactionDetails.paymentResult.responseCode)
                console.log("transactionTime:" + transactionDetails.paymentResult.transactionTime)
                console.log("responseMessage:" + transactionDetails.paymentResult.responseMessage)
                console.log("transactionReference:" + transactionDetails.transactionReference)
                console.log("token:" + transactionDetails.token)
            } else if (result["status"] == "error") {
                // Handle error here the code and message.
            } else if (result["status"] == "event") {
                // Handle events here.
            }
        },
        function (error) {
            console.log(error)
        });

Tokenized Card Payments (Requiring a CVV)
To learn how to set up payment with only requiring a CVV, please click here to review the steps.

Tokenized Card Payments (Requiring a CVV)​

To enable tokenization (for recurring or any other services that depend on auto-detection from the customers instead of saving credit card details), please follow the below instructions:

  1. Request a token in creating any payment request by passing the tokeniseType along with the tokeniseFormat with the preferred type and format that suits your business needs within your PaymentSDKConfiguration, as shown below.


    configuration.tokeniseType = cordova.plugins.CordovaPaymentPlugin.TokeniseType.userOptinoal
    configuration.tokeniseFormat = cordova.plugins.CordovaPaymentPlugin.TokeniseFromat.hex32
    Be Aware
    To know more about these parameters and what are the available values you can pass please check the "2.3 Cordova SDK | Enums" manual.

  2. Configure the billing & shipping information for this payment, noting that the shipping information is optional. To know more about this, please check above Manage Shipping and Billing details and Configuration Options & Parameters manual.


    let billingDetails = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKBillingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

    let shippingDetails = new cordova.plugins.CordovaPaymentPlugin. PaymentSDKShippingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

  3. Then create an object from the PaymentSDKConfiguration and fill it out with your credentials and payment details don't forget to set "tokeniseType", and "tokeniseFormat". To know more about what is the exact values that should be passed here, please check the SDK Configuration Options & Parameters manual.


    let configuration = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKConfiguration();
    configuration.profileID = profileID
    configuration.serverKey = serverKey
    configuration.clientKey = clientKey
    configuration.cartID = cartID
    configuration.currency = "SAR"
    configuration.cartDescription = cartDescription
    configuration.merchantCountryCode = "SA"
    configuration.merchantName = merchantName
    configuration.amount = 0.5
    configuration.billingDetails = billingDetails

    configuration.tokeniseType = cordova.plugins.CordovaPaymentPlugin.TokeniseType.userOptinoal
    configuration.tokeniseFormat = cordova.plugins.CordovaPaymentPlugin.TokeniseFromat.hex32

  4. Only then you will be ready to start/initiate the payment by passing your PaymentSDKConfiguration object to the startCardPayment function. To know more about this please check the SDK Configuration Options & Parameters manual and Step 5 - Cordova SDK | Handle the payment response manaul.

    cordova.plugins.CordovaPaymentPlugin.startCardPayment(configuration, function (result) {
        if (result["status"] == "success") {
            // Handle transaction details here.
            var transactionDetails = result["data"];
        } else if (result["status"] == "error") {
            // Handle error here the code and message.
        } else if (result["status"] == "event") {
            // Handle events here.
        }
    }, function (error) {
        console.log(error)
    });

    This will make the payment behavior would be like the one below, in which your customers will have to provide their full card details.


  5. After the customer complete a successful authorized payment, you will receive the token along with the transaction reference (that generated this token) within your interface/class in which you handled the payment response. You will need to save them for future usage.


  6. Then perform any further recurring (Requiring a CVV) transaction according to your business needs by repeating steps 2, 3, and 4 from this order steps, then you have the option to start the tokenized card payment via the start3DSecureTokenizedCardPayment function by passing the PaymentSDKConfiguration object along with the token and the PaymentSDKSavedCardInfo, which includes the masked card and the card type (saved from the previous step).


    // Masked Card Number, could be found within the paymentInfo object under the paymentDescription parameter
    // For Example "4111 11## #### 1111"

    // Card Schema/Type, could be found within the paymentInfo object under the cardScheme parameter
    // For example "Visa"
    let cardInfo = new PaymentSDKSavedCardInfo("Card mask", "cardType")

    cordova.plugins.CordovaPaymentPlugin.start3DSecureTokenizedCardPayment(
        configuration,
        cardInfo,
        "token",
        function (result) {
            if (result["status"] == "success") {
                // Handle transaction details here.
                var transactionDetails = result["data"];
            } else if (result["status"] == "error") {
                // Handle error here the code and message.
            } else if (result["status"] == "event") {
                // Handle events here.
            }
        }, function (error) {
            console.log(error)
        });

    This will make the payment behavior would be like the one below, in which your customers will have to provide only their CVVs instead of the whole card details:



    Payment Page Require CVV



Payment With SamsungPay​

You will need to import the Cordova SDK class in your code first to start, as shown below: 

"cordova": {
    "plugins": {
        "com.PayTabs.cordova.plugin": { }
    }
}

Implementing this option will enable you to initiate payments targeted to be paid using the supported types of credit cards such as Visa, MasterCard, Amex, etc. To be able to do this, please follow the below instructions:

  1. First, start by following the guide steps to configure SamsungPay, to know how you can configure SamsungPay with PayTabs.

  2. Make sure you import the desire classes as mentioned above.


  3. Configure the billing & shipping information for this payment, noting that the shipping information is optional. To know more about this, please check above Manage Shipping and Billing details and Configuration Options & Parameters manual.


    let billingDetails = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKBillingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

    let shippingDetails = new cordova.plugins.CordovaPaymentPlugin. PaymentSDKShippingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

  4. Then create an object from the PaymentSDKConfiguration and fill it out with your credentials and payment details . To know more about what is the exact values that should be passed here, please check the SDK Configuration Options & Parameters manual.


    let configuration = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKConfiguration();
    configuration.profileID = profileID
    configuration.serverKey = serverKey
    configuration.clientKey = clientKey
    configuration.cartID = cartID
    configuration.currency = "SAR"
    configuration.cartDescription = cartDescription
    configuration.merchantCountryCode = "SA"
    configuration.merchantName = merchantName
    configuration.amount = 0.5
    configuration.billingDetails = billingDetails

  5. Only then you will be ready to start/initiate the payment by passing your PaymentSDKConfiguration object along with and the token you got from the SamsungPay integration guide in step 1 in this manual to the function. To know more about this please check the SDK Configuration Options & Parameters manual and Step 5 - Cordova SDK | Handle the payment response manaul.


    configuration.samsungToken = "token"



Payment With ApplePay​

You will need to import the Cordova SDK class in your code first to start, as shown below: 

"cordova": {
    "plugins": {
        "com.PayTabs.cordova.plugin": { }
    }
}

Implementing this option will enable you to initiate payments targeted to be paid using the supported types of credit cards such as Visa, MasterCard, Amex, etc. To be able to do this, please follow the below instructions:

  1. First, start by following the guide steps to configure ApplePay, to know how you can configure ApplePay certificate with PayTabs.

  2. Make sure you import the desire classes as mentioned above.


  3. Configure the billing & shipping information for this payment, noting that the shipping information is optional. To know more about this, please check above Manage Shipping and Billing details and Configuration Options & Parameters manual.


    let billingDetails = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKBillingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

    let shippingDetails = new cordova.plugins.CordovaPaymentPlugin. PaymentSDKShippingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

  4. Then create an object from the PaymentSDKConfiguration and fill it out with your credentials and payment details . To know more about what is the exact values that should be passed here, please check the SDK Configuration Options & Parameters manual.


    let configuration = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKConfiguration();
    configuration.profileID = profileID
    configuration.serverKey = serverKey
    configuration.clientKey = clientKey
    configuration.cartID = cartID
    configuration.currency = "SAR"
    configuration.cartDescription = cartDescription
    configuration.merchantCountryCode = "SA"
    configuration.merchantName = merchantName
    configuration.amount = 0.5
    configuration.billingDetails = billingDetails

  5. Only then you will be ready to start/initiate the payment by passing your PaymentSDKConfiguration object along with and the token you got from the SamsungPay integration guide in step 1 in this manual to the startApplePayPayment function. To know more about this please check the SDK Configuration Options & Parameters manual and Step 5 - Cordova SDK | Handle the payment response manaul.


    cordova.plugins.CordovaPaymentPlugin.startApplePayPayment(configuration, function (result) {
        if (result["status"] == "success") {
            // Handle transaction details here.
            var transactionDetails = result["data"];
        } else if (result["status"] == "error") {
            // Handle error here the code and message.
        } else if (result["status"] == "event") {
            // Handle events here.
        }
    }, function (error) {
        console.log(error)
    });


Pay with Alternative Payment Methods (APMs)​

You will need to import the Cordova SDK class in your code first to start, as shown below: 

"cordova": {
    "plugins": {
        "com.PayTabs.cordova.plugin": { }
    }
}

Implementing this option will enable you to initiate payments targeted to be paid using the supported types of credit cards such as Visa, MasterCard, Amex, etc. To be able to do this, please follow the below instructions:

  1. Make sure you import the desire classes as mentioned above.


  2. Configure the billing & shipping information for this payment, noting that the shipping information is optional. To know more about this, please check above Manage Shipping and Billing details and Configuration Options & Parameters manual.


    let billingDetails = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKBillingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

    let shippingDetails = new cordova.plugins.CordovaPaymentPlugin. PaymentSDKShippingDetails(
        name = "Technical Support",
        email = "[email protected]",
        phone = "+966 55 xxxxxx6",
        addressLine = "Address street",
        city = "Jeddah",
        state = "Makkah",
        countryCode = "SA", // ISO alpha 2
        zip = "24211")

  3. Then create an object from the PaymentSDKConfiguration and fill it out with your credentials and payment details . To know more about what is the exact values that should be passed here, please check the SDK Configuration Options & Parameters manual.


    let configuration = new cordova.plugins.CordovaPaymentPlugin.PaymentSDKConfiguration();
    configuration.profileID = profileID
    configuration.serverKey = serverKey
    configuration.clientKey = clientKey
    configuration.cartID = cartID
    configuration.currency = "SAR"
    configuration.cartDescription = cartDescription
    configuration.merchantCountryCode = "SA"
    configuration.merchantName = merchantName
    configuration.amount = 0.5
    configuration.billingDetails = billingDetails

  4. Only then you will be ready to start/initiate the payment by passing your PaymentSDKConfiguration object to the startAlternativePaymentMethod function. To know more about this please check the SDK Configuration Options & Parameters manual and Step 5 - Cordova SDK | Handle the payment response manaul.


    cordova.plugins.CordovaPaymentPlugin.startAlternativePaymentMethod(configuration, function (result) {
        if (result["status"] == "success") {
            // Handle transaction details here.
            var transactionDetails = result["data"];
        } else if (result["status"] == "error") {
            // Handle error here the code and message.
        } else if (result["status"] == "event") {
            // Handle events here.
        }
    }, function (error) {
        console.log(error)
    });

We are glad to be always in help. We aim to serve you better each time. As such, please spare a minute to share feedback about your recent experience with PayTabs Developers , on Trustpilot, or Google Reviews.