Configuration Options & Parameters

This article is dedicated to walking you through how to manage the Native Android SDK configuration options.

You will get to know each parameter type and its usage of it so that you can easily configure the SDK to suit your business needs.

PaymentSdkConfigurationDetails

The PaymentSdkConfigurationDetails class can be instantiated using the PaymentSdkConfigBuilder, which follows the builder design pattern to facilitate structured and customizable configuration setup.

Sample Code:

Required configuration methods
All including the optional methods

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

val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode)
    .setCartDescription(cartDesc)
    .setLanguageCode(locale)
    .setMerchantIcon(ResourcesCompat.getDrawable(resources, R.drawable.paytabs, null))
    .setMerchantCountryCode(merchantCountryCode)
    .setCartId(cartId)
    .setTransactionClass(transactionClass)
    .setTransactionType(transType)
    .setBillingData(billingData)
    .setShippingData(shippingData)
    .setCardDiscount(cardDiscount)
    .setPaymentExpiry(120)
    .setAlternativePaymentMethods(alternativePaymentMethods)
    .showBillingInfo(showBillingInfo)
    .showShippingInfo(showShippingInfo)
    .forceShippingInfo(forceShippingInfo)
    .setScreenTitle(screenTitle)
    .setServerIp("1.1.1.1")
    .hideCardScanner(false)
    .setTokenise(tokeniseType, tokenFormat)
    .isDigitalProduct(isDigitalProduct)
    .setCardApproval(cardApproval)
    .linkBillingNameWithCard(true)
    .build()

Methods used via this object:

startCardPayment
start3DSecureTokenizedCardPayment
startTokenizedCardPayment
startSamsungPayment
startAlternativePaymentMethods

Properties:

Required Properties
Optional Properties

Parameter	Data Type	Validation Rule		Required
profileID	INT	Accept only valid profile number.		✔
	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..
	`val profileId = "PROFILE_ID" val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .build()`
serverKey	STRING	Accepts only a valid Server Key of your profile		✔
	This a unique identifiers, used to authenticate your integration.
	`val serverKey = "SERVER_KEY" val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .build()`
clientKey	STRING	Accepts only a valid client Key of your profile		✔
	This a unique identifiers, used to authenticate your integration.
	`val clientKey = "CLIENT_KEY" val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .build()`
amount	DOUBLE	Min: 0.01	Max: 9999999999.99	✔
	Indicates the amount of the transaction the customer is about to be charged. Both min and max values are subjected to the merchant transaction limits.
	`val amount = 20.0 val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .build()`
currencyCode	STRING	Valid string from the following list: `SAR` `AED` `BHD` `EGP` `EUR` `GBP` `HKD` `IDR` `INR` `IQD` `JOD` `JPY` `KWD` `MAD` `OMR` `PKR` `QAR` `USD` Accepts both upper/lower case characters		✔
	Indicates the transaction currency, which the customer will be charged with. To know more about this parameter please click here.
	`val currency = "SAR" val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .build()`
merchantCountryCode	STRING	Country ISO Alpha-2 charachters code		✔
	Indicates the merchant country code, where the merchant run there business.
	`var merchantCountryCode = "SA" val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .build()`
cartId	STRING	Min: 1	Max: 64	✔
	Indicates the cart/order id at the merchant end, to easily relate the PayTabs transaction to. To know more about this parameter please click here.
	`val cartId = "Order1001" val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .setCartId(cartId) .build()`
cartDescription	STRING	Min: 1	Max: 128	✔
	Indicates the cart/order description at the merchant end, to easily relate the PayTabs transaction to. To know more about this parameter please click here.
	`var cartDesc = "cart description" val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .setCartDescription(cartDesc) .build()`
billingDetails	OBJECT			✔
	Indicates the customer details for this payment. If provided, the payment page will be prefilled with the provided data. To know more about this parameter please click here.
	`var billingData = PaymentSdkBillingDetails( city = "Jeddah", countryCode = "sA", email = "[email protected]", name = "Technical Support", phone = "+966 55 xxxxxx6", state = "Makkah", addressLine = "address street", zip = "24211" ) val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .setBillingData(billingData) .build()`
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	OBJECT			✔
	Indicates the customer shipping details for this payment. If provided, the payment page will be prefilled with the provided data..
	`var billingData = PaymentSdkShippingDetails( city = "Jeddah", countryCode = "sA", email = "[email protected]", name = "Technical Support", phone = "+966 55 xxxxxx6", state = "Makkah", addressLine = "address street", zip = "24211" ) val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .setShippingData(shippingData) .build()`
shippingDetails'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	✔

Parameter	Data Type	Validation Rule		Required
cardDiscount	List<PaymentSdkCardDiscount>			✘
	To enables merchants to provide tailored discounts to their customers based on specific card BIN ranges. This feature is designed to enhance customer loyalty and engagement by allowing merchants to offer discounts either as a fixed amount or a percentage off the total purchase. To know more about this parameter please click here.
	`val cardDiscount = listOf( PaymentSdkCardDiscount( // List of card prefixes from 4 to 10 digits discountCards = listOf("40001"), // Discount percentage or value discountValue = 10.0, // Discount description discountTitle = "● 10% discount on VISA cards starting with 40001", // Discount type: percentage or value isPercentage = true ) ) val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .setCardDiscount(cardDiscount) .build()`
cardDiscount's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
`discountCards`	List<String>	N/A	N/A	✔
	Provide a list of card prefixes strings (usually first 4, can be up to first 10 prefixes digits) that will be used to determine if the discount should be applied to the transaction.).

`discountValue`	DECIMAL	0.01	9999999999.99	✔
	The actual discount should be deducted from the `amount`, could be a value or percentage according to the `isPercentage` value

`discountTitle`	STRING	N/A	N/A	✔
	Description of the discount that will be displayed for the customer on the hosted payment page.

`isPercentage`	BOOLEAN	N/A	N/A	✔
	Determines whether the discount is a percentage or a value.

cardApproval	PaymentSdkCardApproval			✘
	Allow you to collects approval of the customer card details via an API, before proceed with payment process.
	`val cardApproval = PaymentSdkCardApproval( validationUrl = "https://yourdomain.com/validate", binLength = 8, blockIfNoResponse = false ) val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .setCardApproval(cardApproval) .build()`
cardApproval's Nested Parameters
Nested Parameter	Data Type	Min	Max	Required
`validationUrl`	String	N/A	N/A	✔
	Provide a list of card prefixes strings (usually first 4, can be up to first 10 prefixes digits) that will be used to determine if the discount should be applied to the transaction.).

`binLength`	INTEGER	0.01	9999999999.99	✔
	The actual discount should be deducted from the `amount`, could be a value or percentage according to the `isPercentage` value

`blockIfNoResponse`	Boolean	N/A	N/A	✔
	Description of the discount that will be displayed for the customer on the hosted payment page.

PaymentSDKQueryConfiguration

The PaymentSDKQueryConfiguration class can be instantiated directly. This allows for straightforward creation and usage in methods where configuration is passed explicitly.

Sample Code:

Required configuration methods
All including the optional methods

val queryConfig = PaymentSDKQueryConfiguration(
    serverKey = serverKey,
    clientKey = clientKey,
    merchantCountryCode = merchantCountryCode,
    profileID = profileId,
    transactionReference = transactionReference
)

Methods used via this object:

queryTransaction

Properties:

Required Properties

Parameter	Data Type	Validation Rule	Required
profileID	INT	Accept only valid profile number.	✔
	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..
	`val profileId = "PROFILE_ID" undefined`
serverKey	STRING	Accepts only a valid Server Key of your profile	✔
	This a unique identifiers, used to authenticate your integration.
	`val serverKey = "SERVER_KEY" undefined`
clientKey	STRING	Accepts only a valid client Key of your profile	✔
	This a unique identifiers, used to authenticate your integration.
	`val clientKey = "CLIENT_KEY" undefined`
merchantCountryCode	STRING	Country ISO Alpha-2 charachters code	✔
	Indicates the merchant country code, where the merchant run there business.
	`var merchantCountryCode = "SA" undefined`

PaymentSdkConfigurationDetails​

Sample Code:​

Methods used via this object:​

Properties:​

profileID​

serverKey​

clientKey​

amount​

currencyCode​

merchantCountryCode​

cartId​

cartDescription​

billingDetails​

shippingDetails​

cardDiscount​

cardApproval​

PaymentSDKQueryConfiguration​

Sample Code:​

Methods used via this object:​

Properties:​

profileID​

serverKey​

clientKey​

merchantCountryCode​

PaymentSdkConfigurationDetails

Sample Code:

Methods used via this object:

Properties:

profileID

serverKey

clientKey

amount

currencyCode

merchantCountryCode

cartId

cartDescription

billingDetails

shippingDetails

cardDiscount

cardApproval

PaymentSDKQueryConfiguration

Sample Code:

Methods used via this object:

Properties:

profileID

serverKey

clientKey

merchantCountryCode