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

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

All including the optional methods

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

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	✔

Optional Properties

Parameter	Data Type	Validation Rule		Required
screenTitle	STRING			✘
	The title that'll be shown on the payment form screen under the logo.
	merchantName	STRING			✘
The name of the merchant will be shown to the customer on the SamsungPay wallet screen.
hideCardScanner	Boolean			✘
	Indicates whether to show the camera card scanner button from the payment form screen or not.
	linkBillingNameWithCard	Boolean			✘
Indicates whether to add the billing name to be the same as the cardholder's name or not.
isDigitalProduct	Boolean			✘
	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. using only the customer name and email in case your products/services are not physical and don't need to be shipped to the customers. Note that the digital product mode is not universally compatible with all processors. Therefore, it is advisable to seek guidance from your Relationship Manager (RM) to determine if it is suitable for your specific processor.
	setPaymentExpiry	STRING			✘
Option to set expiry timeout in seconds for the card payment screen. Set to zero to deactivate the timeout feature, and less than 60 seconds will not affect. If the merchant presses the "PAY NOW" button the timeout will stop and the customer will proceed without expiration.
showBillingInfo	BOOLEAN			✘
	Indicates whether to hide billing information or not from the payment form screen. Noting 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.
	setCardDiscount	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()
setCardDiscount'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.
showShippingInfo	BOOLEAN			✘
	Indicates whether to show the shipping information or not from the payment form screen.
	tokeniseType	TokeniseType			✘
The tokenization format the generated token should follow.
tokenFormat	TokenFormat			✘
	This indicates the type of tokenization used.
	alternativePaymentMethods	AlternativePaymentMethod			✘
Used to add another payment method in the payment form screen (such as Aman, StcPay, OmanNet, .. etc) or not. For more information please check the related section on this from here.
token	STRING			✘
	The customer's saved card token which has to be passed within the transaction. This field is required for creating tokenized (recurring) transactions.
	transactionReference	STRING			✘
Indicates the Transaction Reference on the PayTabs side check details on [Response Parameters | tran_ref]
val configData = PaymentSdkConfigBuilder(profileId, serverKey, clientKey, amount, currencyCode) .build()

---

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

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

All including the optional methods

---

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