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 Native Android 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.

configData.showBillingInfo = true
configData.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:

var forceShippingInfo = true

PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currency)
    .forceShippingInfo(forceShippingInfo)
    .build()



A boolean parameter that Indicates whether to add the billing name to be the same as the cardholder's name or not.

Be Aware

By default, the billing name is linked with card holder name, if you set its flag to false the billing name and the card holder name will be seperated

configData.linkBillingNameWithCardHolderName = 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 Native Android SDK class in your code first to start, as shown below: 

import com.payment.paymentsdk.PaymentSdkActivity
import com.payment.paymentsdk.PaymentSdkConfigBuilder
import com.payment.paymentsdk.integrationmodels.PaymentSdkConfigurationDetails
import com.payment.paymentsdk.integrationmodels.PaymentSdkBillingDetails
import com.payment.paymentsdk.integrationmodels.PaymentSdkShippingDetails

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.


    val billingData = PaymentSdkBillingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

    val shippingData = PaymentSdkShippingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

  3. Then create an object from the PaymentSdkConfigurationDetails using the builder class PaymentSdkConfigBuilder 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.


    val configData = PaymentSdkConfigBuilder(
        profileId = profileId,
        serverKey = serverKey,
        clientKey = clientKey,
        amount = amount,
        currencyCode = currency
    )
        .setMerchantCountryCode("SA")
        .setCartId(cartId)
        .setCartDescription(cartDesc)
        .setBillingData(billingData)    
        .setShippingData(shippingData)
        .build()

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

    PaymentSdkActivity.startCardPayment(
        context = this,
        ptConfigData = configData,
        callback = this
    )

    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 tokenFormat with the preferred type and format that suits your business needs within your PaymentSdkConfigurationDetails, as shown below.


    val tokeniseType = PaymentSdkTokenise.USER_OPTIONAL
    val tokenFormat = PaymentSdkTokenFormat.Hex32Format()

    PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currency)
        .setTokenise(tokeniseType, tokenFormat)
        .build()
    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.


    val billingData = PaymentSdkBillingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

    val shippingData = PaymentSdkShippingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

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


    val tokeniseType = PaymentSdkTokenise.USER_OPTIONAL
    val tokenFormat = PaymentSdkTokenFormat.Hex32Format()

    val configData = PaymentSdkConfigBuilder(
        profileId = profileId,
        serverKey = serverKey,
        clientKey = clientKey,
        amount = amount,
        currencyCode = currency
    )
        .setMerchantCountryCode("SA")
        .setCartId(cartId)
        .setCartDescription(cartDesc)
        .setBillingData(billingData)    
        .setShippingData(shippingData)
        .setTokenise(tokeniseType, tokenFormat)
        .build()

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

    PaymentSdkActivity.startCardPayment(
        context = this,
        ptConfigData = configData,
        callback = this
    )

    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 PaymentSdkConfigurationDetails object along with the token and the transaction reference (saved from the previous step).

    PaymentSdkActivity.startTokenizedCardPayment(
        context = this,
        ptConfigData = configData,
        token = token,
        transactionRef = transactionReference,
        callback = this
    )

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 tokenFormat with the preferred type and format that suits your business needs within your PaymentSdkConfigurationDetails, as shown below.


    val tokeniseType = PaymentSdkTokenise.USER_OPTIONAL
    val tokenFormat = PaymentSdkTokenFormat.Hex32Format()

    PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currency)
        .setTokenise(tokeniseType, tokenFormat)
        .build()
    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.


    val billingData = PaymentSdkBillingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

    val shippingData = PaymentSdkShippingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

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


    val tokeniseType = PaymentSdkTokenise.USER_OPTIONAL
    val tokenFormat = PaymentSdkTokenFormat.Hex32Format()

    val configData = PaymentSdkConfigBuilder(
        profileId = profileId,
        serverKey = serverKey,
        clientKey = clientKey,
        amount = amount,
        currencyCode = currency
    )
        .setMerchantCountryCode("SA")
        .setCartId(cartId)
        .setCartDescription(cartDesc)
        .setBillingData(billingData)    
        .setShippingData(shippingData)
        .setTokenise(tokeniseType, tokenFormat)
        .build()

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

    PaymentSdkActivity.startCardPayment(
        context = this,
        ptConfigData = configData,
        callback = this
    )

    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 PaymentSdkConfigurationDetails 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"
    val cardMask = paymentSdkTransactionDetails.paymentInfo?.paymentDescription
    // Card Schema, could be found within the paymentInfo object under the cardScheme parameter
    // For example "Visa"
    val cardScheme = paymentSdkTransactionDetails.paymentInfo?.cardScheme


    PaymentSdkActivity.start3DSecureTokenizedCardPayment(
        context = this,
        ptConfigData = configData,
        savedCardInfo = PaymentSDKSavedCardInfo(cardMask!!, cardScheme!!),
        token = token,
        callback = this
    )

    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 Native Android SDK class in your code first to start, as shown below: 

import com.payment.paymentsdk.PaymentSdkActivity
import com.payment.paymentsdk.PaymentSdkConfigBuilder
import com.payment.paymentsdk.integrationmodels.PaymentSdkConfigurationDetails
import com.payment.paymentsdk.integrationmodels.PaymentSdkBillingDetails
import com.payment.paymentsdk.integrationmodels.PaymentSdkShippingDetails

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.


    val billingData = PaymentSdkBillingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

    val shippingData = PaymentSdkShippingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

  4. Then create an object from the PaymentSdkConfigurationDetails using the builder class PaymentSdkConfigBuilder 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.


    val configData = PaymentSdkConfigBuilder(
        profileId = profileId,
        serverKey = serverKey,
        clientKey = clientKey,
        amount = amount,
        currencyCode = currency
    )
        .setMerchantCountryCode("SA")
        .setCartId(cartId)
        .setCartDescription(cartDesc)
        .setBillingData(billingData)    
        .setShippingData(shippingData)
        .build()

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


    startSamsungPayment(
        this, 
        configData, 
        *SAMSUNG PAY TOKEN*,
        callback=this
    )


Pay with Alternative Payment Methods (APMs)​

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

import com.payment.paymentsdk.PaymentSdkActivity
import com.payment.paymentsdk.PaymentSdkConfigBuilder
import com.payment.paymentsdk.integrationmodels.PaymentSdkConfigurationDetails
import com.payment.paymentsdk.integrationmodels.PaymentSdkBillingDetails
import com.payment.paymentsdk.integrationmodels.PaymentSdkShippingDetails

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.


    val billingData = PaymentSdkBillingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

    val shippingData = PaymentSdkShippingDetails(
        city = "Jeddah",
        countryCode = "SA", //2-digit ISO country code
        email = "[email protected]",
        name = "Technical Support",
        phone = "+966 55 xxxxxx6",
        state = "Makkah",
        addressLine = "address street",
        zip = "24211"
    )

  3. Then create an object from the PaymentSdkConfigurationDetails using the builder class PaymentSdkConfigBuilder 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.


    val configData = PaymentSdkConfigBuilder(
        profileId = profileId,
        serverKey = serverKey,
        clientKey = clientKey,
        amount = amount,
        currencyCode = currency
    )
        .setMerchantCountryCode("SA")
        .setCartId(cartId)
        .setCartDescription(cartDesc)
        .setBillingData(billingData)    
        .setShippingData(shippingData)
        .build()

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


    startAlternativePaymentMethods(
        context = this, 
        ptConfigData =  configData, 
        callback=this
    )

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.