Android SDK to use goSell API.
A library that fully covers payment/authorization/card saving process inside your Android application
-
- Payment Success Callback
- Payment Failure Callback
- Authorization Success Callback
- Authorization Failure Callback
- Card Saving Success Callback
- Card Saving Failure Callback
- Card Tokenized Success Callback
- Saved Cards List Callback
- Session Other Failure Callback
- Invalid Card Details
- Backend Un-known Error
- Invalid Transaction Mode
- Session Is Starting Callback
- Session Has Started Callback
- Session Failed To Start Callback
- Session Cancel Callback
- User Enabled Save CARD
- Asynch_Payment_Callback
- Payment_Initiated_Callback
To use the SDK the following requirements must be met:
- Android Studio 3.3 or newer
- Android SDK Tools 26.1.1 or newer
- Android Platform Version: API 28: Android 9.0 (Pie) revision 6 or later
- **Build gradle:3.5.0
- Clone goSellSDK library from Tap repository
[email protected]:Tap-Payments/goSellSDK-Android.git - Add goSellSDK library to your project settings.gradle file as following
include ':library', ':YourAppName'
- Setup your project to include goSellSDK as a dependency Module.
- File -> Project Structure -> Modules -> << your project name >>
- Dependencies -> click on + icon in the screen bottom -> add Module Dependency
- select goSellSDK library
JitPack is a novel package repository for JVM and Android projects. It builds Git projects on demand and provides you with ready-to-use artifacts (jar, aar).
To integrate goSellSDK into your project add it in your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}Step 2. Add the dependency
dependencies {
implementation 'com.github.Tap-Payments:goSellSDK-Android:2.17.0'
}Regarding to this Issue " Google throws this exception on Activity's onCreate method after v27, their meaning is if an Activity is translucent or floating, its orientation should be relied on parent(background) so, Activity can't make decision on itself. Even if you remove android:screenOrientation="portrait" from the floating or translucent Activity In android Oreo (API 26) you can not change orientation for Activity that offer translucent.
Your Activity that launches the SDK has to set orientation to Portrait, becuase our SDK is just a child to your actvity in case of translucent mode.
First of all, goSellSDK should be set up. In this section secret key and application ID are required.
First of all, goSellSDK should be set up. To set it up, add the following lines of code somewhere in your project and make sure they will be called before any usage of goSellSDK.
Below is the list of properties in goSellSDK class you can manipulate. Make sure you do the setup before any usage of the SDK.
To set it up, add the following line of code somewhere in your project and make sure it will be called before any usage of goSellSDK, otherwise an exception will be thrown. Required.
Java:
GoSellSDK.init(context, "sk_XXXXXXXXXXXXXXXXXXXXXXXX","app_id");Kotlin:
GoSellSDK.init(context, "sk_XXXXXXXXXXXXXXXXXXXXXXXX","app_id")authToken- to authorize your requests.// Secret key (format: "sk_XXXXXXXXXXXXXXXXXXXXXXXX")app_id- replace it using your application ID "Application main package".
Don't forget to import the class at the beginning of the file:
Java:
import company.tap.gosellapi.GoSellSDK;Kotlin:
import company.tap.gosellapi.GoSellSDKSDK mode defines which mode SDK is operating in, either sandbox or production.
SDK Mode is automatically identified in the backend based on the secrete key you defined earlier in setup process.
Localization language of the UI part of the SDK. This is locale identifier.
Make sure it consists only from 2 lowercased letters and is presented in the list of availableLanguages property of goSellSDK class.
Notice: SDK user interface layout direction is behave similar to your App. There is no effect come form the SDK back to your application locale.
goSellSDK should be set up. To set it up, add the following lines of code somewhere in your project and make sure they will be called before any usage of goSellSDK.
Java:
/**
* Integrating SDK.
*/
private void startSDK(){
/**
* Required step.
* Configure SDK with your Secret API key and App Bundle name registered with tap company.
*/
configureApp();
/**
* Optional step
* Here you can configure your app theme (Look and Feel).
*/
configureSDKThemeObject();
/**
* Required step.
* Configure SDK Session with all required data.
*/
configureSDKSession();
/**
* Required step.
* Choose between different SDK modes
*/
configureSDKMode();
/**
* If you included Tap Pay Button then configure it first, if not then ignore this step.
*/
initPayButton();
}
Kotlin:
/**
* Integrating SDK.
*/
private fun startSDK(){
/**
* Required step.
* Configure SDK with your Secret API key and App Bundle name registered with tap company.
*/
configureApp()
/**
* Optional step
* Here you can configure your app theme (Look and Feel).
*/
configureSDKThemeObject()
/**
* Required step.
* Configure SDK Session with all required data.
*/
configureSDKSession()
/**
* Required step.
* Choose between different SDK modes
*/
configureSDKMode()
/**
* If you included Tap Pay Button then configure it first, if not then ignore this step.
*/
initPayButton()
}
Below is the list of properties in goSellSDK class you can manipulate. Make sure you do the setup before any usage of the SDK.
To set it up, add the following line of code somewhere in your project and make sure it will be called before any usage of goSellSDK, otherwise an exception will be thrown. Required.
If you wish to localize the sdk following languages are available English, Arabic , German,Turkish and this has to be passed as below ,if locale not passed then default locale EN will be used.
Java:
/**
* Required step.
* Configure SDK with your Secret API key and App Bundle name registered with tap company.
*/
private void configureApp(){
GoSellSDK.init(this, "sk_test_kovrMB0mupFJXfNZWx6Etg5y","company.tap.goSellSDKExample"); // to be replaced by merchant
GoSellSDK.setLocale("ar");// if you dont pass locale then default locale EN will be used
}Kotlin:
/**
* Required step.
* Configure SDK with your Secret API key and App Bundle name registered with tap company.
*/
private fun configureApp(){
GoSellSDK.init(this, "sk_test_kovrMB0mupFJXfNZWx6Etg5y","company.tap.goSellSDKExample") // to be replaced by merchant
GoSellSDK.setLocale("ar")// if you dont pass locale then default locale EN will be used
}authToken- to authorize your requests.// Secret key (format: "sk_XXXXXXXXXXXXXXXXXXXXXXXX")app_id- replace it using your application ID "Application main package".
Don't forget to import the class at the beginning of the file:
Java:
import company.tap.gosellapi.GoSellSDK;Kotlin:
import company.tap.gosellapi.GoSellSDKTo customize the SDK look and feel you must use ThemeObject and populate it as following:
Java:
private void configureSDKThemeObject() {
ThemeObject.getInstance()
// set Appearance mode [Full Screen Mode - Windowed Mode]
.setAppearanceMode(AppearanceMode.WINDOWED_MODE) // **Required**
.setSdkLanguage("ar") //if you dont pass locale then default locale EN will be used
// Setup header font type face **Make sure that you already have asset folder with required fonts**
.setHeaderFont(Typeface.createFromAsset(getAssets(),"fonts/roboto_light.ttf"))//**Optional**
//Setup header text color
.setHeaderTextColor(getResources().getColor(R.color.black1)) // **Optional**
// Setup header text size
.setHeaderTextSize(17) // **Optional**
// setup header background
.setHeaderBackgroundColor(getResources().getColor(R.color.french_gray_new))//**Optional**
// setup card form input font type
.setCardInputFont(Typeface.createFromAsset(getAssets(),"fonts/roboto_light.ttf"))//**Optional**
// setup card input field text color
.setCardInputTextColor(getResources().getColor(R.color.black))//**Optional**
// setup card input field text color in case of invalid input
.setCardInputInvalidTextColor(getResources().getColor(R.color.red))//**Optional**
// setup card input hint text color
.setCardInputPlaceholderTextColor(getResources().getColor(R.color.black))//**Optional**
// setup Switch button Thumb Tint Color in case of Off State
.setSaveCardSwitchOffThumbTint(getResources().getColor(R.color.gray)) // **Optional**
// setup Switch button Thumb Tint Color in case of On State
.setSaveCardSwitchOnThumbTint(getResources().getColor(R.color.vibrant_green)) // **Optional**
// setup Switch button Track Tint Color in case of Off State
.setSaveCardSwitchOffTrackTint(getResources().getColor(R.color.gray)) // **Optional**
// setup Switch button Track Tint Color in case of On State
.setSaveCardSwitchOnTrackTint(getResources().getColor(R.color.green)) // **Optional**
// change scan icon
.setScanIconDrawable(getResources().getDrawable(R.drawable.btn_card_scanner_normal)) // **Optional**
//Show or hide the scanner
.setCardScannerIconVisible(true) // **Optional**
// setup pay button selector [ background - round corner ]
.setPayButtonResourceId(R.drawable.btn_pay_selector)
// setup pay button font type face
.setPayButtonFont(Typeface.createFromAsset(getAssets(),"fonts/roboto_light.ttf")) // **Optional**
// setup pay button disable title color
.setPayButtonDisabledTitleColor(getResources().getColor(R.color.black)) // **Optional**
// setup pay button enable title color
.setPayButtonEnabledTitleColor(getResources().getColor(R.color.White)) // **Optional**
//setup pay button text size
.setPayButtonTextSize(14) // **Optional**
// show/hide pay button loader
.setPayButtonLoaderVisible(true) // **Optional**
// show/hide pay button security icon
.setPayButtonSecurityIconVisible(true) // **Optional**
// set the text on pay button
.setPayButtonText("PAY BTN CAN BE VERY VERY VERY LONGGGG LONGGGGG") // **Optional**
// setup dialog textcolor and textsize
.setDialogTextColor(getResources().getColor(R.color.black1)) // **Optional**
.setDialogTextSize(17) // **Optional**
;
}Kotlin:
private fun configureSDKThemeObject() {
ThemeObject.getInstance()
// set Appearance mode [Full Screen Mode - Windowed Mode]
.setAppearanceMode(AppearanceMode.WINDOWED_MODE) // **Required**
.setSdkLanguage("ar") //if you dont pass locale then default locale EN will be used
// Setup header font type face **Make sure that you already have asset folder with required fonts**
.setHeaderFont(Typeface.createFromAsset(getAssets(),"fonts/roboto_light.ttf"))//**Optional**
//Setup header text color
.setHeaderTextColor(getResources().getColor(R.color.black1)) // **Optional**
// Setup header text size
.setHeaderTextSize(17) // **Optional**
// setup header background
.setHeaderBackgroundColor(getResources().getColor(R.color.french_gray_new))//**Optional**
// setup card form input font type
.setCardInputFont(Typeface.createFromAsset(getAssets(),"fonts/roboto_light.ttf"))//**Optional**
// setup card input field text color
.setCardInputTextColor(getResources().getColor(R.color.black))//**Optional**
// setup card input field text color in case of invalid input
.setCardInputInvalidTextColor(getResources().getColor(R.color.red))//**Optional**
// setup card input hint text color
.setCardInputPlaceholderTextColor(getResources().getColor(R.color.black))//**Optional**
// setup Switch button Thumb Tint Color in case of Off State
.setSaveCardSwitchOffThumbTint(getResources().getColor(R.color.gray)) // **Optional**
// setup Switch button Thumb Tint Color in case of On State
.setSaveCardSwitchOnThumbTint(getResources().getColor(R.color.vibrant_green)) // **Optional**
// setup Switch button Track Tint Color in case of Off State
.setSaveCardSwitchOffTrackTint(getResources().getColor(R.color.gray)) // **Optional**
// setup Switch button Track Tint Color in case of On State
.setSaveCardSwitchOnTrackTint(getResources().getColor(R.color.green)) // **Optional**
// change scan icon
.setScanIconDrawable(getResources().getDrawable(R.drawable.btn_card_scanner_normal)) // **Optional**
// setup pay button selector [ background - round corner ]
.setPayButtonResourceId(R.drawable.btn_pay_selector)
// setup pay button font type face
.setPayButtonFont(Typeface.createFromAsset(getAssets(),"fonts/roboto_light.ttf")) // **Optional**
// setup pay button disable title color
.setPayButtonDisabledTitleColor(getResources().getColor(R.color.black)) // **Optional**
// setup pay button enable title color
.setPayButtonEnabledTitleColor(getResources().getColor(R.color.White)) // **Optional**
//setup pay button text size
.setPayButtonTextSize(14) // **Optional**
// show/hide pay button loader
.setPayButtonLoaderVisible(true) // **Optional**
// show/hide pay button security icon
.setPayButtonSecurityIconVisible(true) // **Optional**
// set the text on pay button
.setPayButtonText("PAY BTN CAN BE VERY VERY VERY LONGGGG LONGGGGG") // **Optional**
// setup dialog textcolor and textsize
.setDialogTextColor(getResources().getColor(R.color.black1)) // **Optional**
.setDialogTextSize(17) // **Optional**
}SDKSession is the main interface for goSellSDK library from you application, so you can use it to start SDK with pay button or without pay button.
| Property | Type | Description |
|---|---|---|
| payButtonView | PayButtonView | Pay Button View can be used to start SDK |
| paymentDataSource | PaymentDataSource | Payment data source. All input payment information is passed through this protocol. Required. |
| activityListener | Activity | Activity. used as a context to setup sdk. |
| sessionDelegate | Activity | Activity. it is used to notify Merchant application with all SDK Events |
| Property | Type |
|---|---|
| addSessionDelegate | pass your activity that implements SessionDelegate interface . you have to override all methods available through this interface |
| instantiatePaymentDataSource | Payment Data Source Object is the main object that is responsible of holding all data required from our backend to return all payment options [ Debit Cards - Credit Cards ] available for this merchant . |
| setTransactionCurrency | Set the transaction currency associated to your account. Transaction currency must be of type TapCurrency("currency_iso_code"). i.e new TapCurrency("KWD") |
| setTransactionMode | SDK offers different transaction modes such as [ TransactionMode.PURCHASE - TransactionMode.AUTHORIZE_CAPTURE - TransactionMode.SAVE_CARD - TransactionMode.TOKENIZE_CARD] |
| setCustomer | Pass your customer data. Customer must be of type Tap Customer. You can create Tap Customer as following new Customer.CustomerBuilder(customerRefNumber).email("cut_email").firstName("cust_firstName") .lastName("cust_lastName").metadata("").phone(new PhoneNumber("country_code","mobileNo")) .middleName("cust_middleName").build(); |
| setAmount | Set Total Amount. Amount value must be of type BigDecimal i.e new BigDecimal(40) |
| setPaymentItems | ArrayList that contains payment items. each item of this array must be of type PaymentItem. in case of SAVE_CARD or TOKENIZE_CARD you can pass it null |
| setTaxes | ArrayList that contains Tax items. each item of this array must be of type Tax. in case of SAVE_CARD or TOKENIZE_CARD you can pass it null |
| setShipping | ArrayList that contains Shipping items. each item of this array must be of type Shipping. in case of SAVE_CARD or TOKENIZE_CARD you can pass it null |
| setPostURL | POST URL. |
| setPaymentDescription | Payment description. |
| setPaymentMetadata | HashMap that contains any other payment related data. |
| setPaymentReference | Payment reference. it must be of type Reference object or null |
| setPaymentStatementDescriptor | Payment Statement Description |
| isRequires3DSecure | Enable or Disable 3D Secure |
| setReceiptSettings | Identify Receipt Settings. You must pass Receipt object or null |
| setAuthorizeAction | Identify AuthorizeAction. You must pass AuthorizeAction object or null |
| setDestination | Identify Array of destination. You must pass Destinations object or null |
| start | Start SDK Without using Tap Pay button. You must call this method whereever you want to show TAP Payment screen. Also, you must pass your activity as a context |
| setButtonView | If you included TAP PayButton in your activity then you need to configure it and then pass it to SDKSession through this method. |
| setDefaultCardHolderName | Sets default CardHoldername in the field, without the user need to re-type.(OPTIONAL) |
| isUserAllowedToEnableCardHolderName | Lets default CardHoldername in the field,can be editable or not based on user configuration .(OPTIONAL) |
| sdkSession.cancelSession(this); | Merchant can now cancel the session and stop all process initiating the SDK. .(OPTIONAL) |
| setTopUp | Merchant can now send a topUp object while initiating the SDK. .(OPTIONAL) |
Configure SDK Session Example
Java:
/**
* Configure SDK Session
*/
private void configureSDKSession() {
// Instantiate SDK Session
if(sdkSession==null) sdkSession = new SDKSession(); //** Required **
// pass your activity as a session delegate to listen to SDK internal payment process follow
sdkSession.addSessionDelegate(this); //** Required **
// initiate PaymentDataSource
sdkSession.instantiatePaymentDataSource(); //** Required **
// set transaction currency associated to your account
sdkSession.setTransactionCurrency(new TapCurrency("KWD")); //** Required **
// Using static CustomerBuilder method available inside TAP Customer Class you can populate TAP Customer object and pass it to SDK
sdkSession.setCustomer(getCustomer()); //** Required **
// Set Total Amount. The Total amount will be recalculated according to provided Taxes and Shipping
sdkSession.setAmount(new BigDecimal(40)); //** Required **
// Set Payment Items array list
sdkSession.setPaymentItems(new ArrayList<PaymentItem>());// ** Optional ** you can pass empty array list
// Set Taxes array list
sdkSession.setTaxes(new ArrayList<Tax>());// ** Optional ** you can pass empty array list
// Set Shipping array list
sdkSession.setShipping(new ArrayList<>());// ** Optional ** you can pass empty array list
// Post URL
sdkSession.setPostURL(""); // ** Optional **
// Payment Description
sdkSession.setPaymentDescription(""); //** Optional **
// Payment Extra Info
sdkSession.setPaymentMetadata(new HashMap<>());// ** Optional ** you can pass empty array hash map
// Payment Reference
sdkSession.setPaymentReference(null); // ** Optional ** you can pass null
// Payment Statement Descriptor
sdkSession.setPaymentStatementDescriptor(""); // ** Optional **
// Enable or Disable Saving Card
sdkSession.isUserAllowedToSaveCard(true); // ** Required ** you can pass boolean
// Enable or Disable 3DSecure
sdkSession.isRequires3DSecure(true);
//Set Receipt Settings [SMS - Email ]
sdkSession.setReceiptSettings(null); // ** Optional ** you can pass Receipt object or null
// Set Authorize Action
sdkSession.setAuthorizeAction(null); // ** Optional ** you can pass AuthorizeAction object or null
sdkSession.setDestination(null); // ** Optional ** you can pass Destinations object or null
sdkSession.setMerchantID(null); // ** Optional ** you can pass merchant id or null
sdkSession.setPaymentType("WEB"); //** Merchant can customize payment options [WEB/CARD] for each transaction or it will show all payment options granted to him.
sdkSession.setDefaultCardHolderName("TEST TAP"); // ** Optional ** you can pass default CardHolderName of the user .So you don't need to type it.
sdkSession.isUserAllowedToEnableCardHolderName(false); //** Optional ** you can enable/ disable default CardHolderName .
sdkSession.setTopUp(getTopUp()); // ** Optional ** you can pass TopUp object for Merchant.
/**
* Use this method where ever you want to show TAP SDK Main Screen.
* This method must be called after you configured SDK as above
* This method will be used in case of you are not using TAP PayButton in your activity.
*/
sdkSession.start(this);
}Kotlin:
/**
* Configure SDK Session
*/
private void configureSDKSession() {
// Instantiate SDK Session
if(sdkSession==null) sdkSession = new SDKSession() //** Required **
// pass your activity as a session delegate to listen to SDK internal payment process follow
sdkSession.addSessionDelegate(this) //** Required **
// initiate PaymentDataSource
sdkSession.instantiatePaymentDataSource() //** Required **
// set transaction currency associated to your account
sdkSession.setTransactionCurrency(new TapCurrency("KWD")) //** Required **
// Using static CustomerBuilder method available inside TAP Customer Class you can populate TAP Customer object and pass it to SDK
sdkSession.setCustomer(getCustomer()) //** Required **
// Set Total Amount. The Total amount will be recalculated according to provided Taxes and Shipping
sdkSession.setAmount(new BigDecimal(40)) //** Required **
// Set Payment Items array list
sdkSession.setPaymentItems(new ArrayList<PaymentItem>())// ** Optional ** you can pass empty array list
// Set Taxes array list
sdkSession.setTaxes(new ArrayList<Tax>())// ** Optional ** you can pass empty array list
// Set Shipping array list
sdkSession.setShipping(new ArrayList<>())// ** Optional ** you can pass empty array list
// Post URL
sdkSession.setPostURL("") // ** Optional **
// Payment Description
sdkSession.setPaymentDescription("") //** Optional **
// Payment Extra Info
sdkSession.setPaymentMetadata(new HashMap<>())// ** Optional ** you can pass empty array hash map
// Payment Reference
sdkSession.setPaymentReference(null) // ** Optional ** you can pass null
// Payment Statement Descriptor
sdkSession.setPaymentStatementDescriptor("") // ** Optional **
// Enable or Disable Saving Card
sdkSession.isUserAllowedToSaveCard(true) // ** Required ** you can pass boolean
// Enable or Disable 3DSecure
sdkSession.isRequires3DSecure(true)
//Set Receipt Settings [SMS - Email ]
sdkSession.setReceiptSettings(null); // ** Optional ** you can pass Receipt object or null
// Set Authorize Action
sdkSession.setAuthorizeAction(null) // ** Optional ** you can pass AuthorizeAction object or null
sdkSession.setDestination(null) // ** Optional ** you can pass Destinations object or null
sdkSession.setMerchantID(null) // ** Optional ** you can pass merchant id or null
sdkSession.setPaymentType("WEB") //** Merchant can customize payment options [WEB/CARD] for each transaction or it will show all payment options granted to him.
sdkSession.setDefaultCardHolderName("TEST TAP") // ** Optional ** you can pass default CardHolderName of the user .So you don't need to type it.
sdkSession.isUserAllowedToEnableCardHolderName(false) //** Optional ** you can enable/ disable default CardHolderName .
/**
* Use this method where ever you want to show TAP SDK Main Screen.
* This method must be called after you configured SDK as above
* This method will be used in case of you are not using TAP PayButton in your activity.
*/
sdkSession.start(this)
}Configure SDK Transaction Mode
You have to choose only one Mode of the following modes:
Note:- - In case of using PayButton, then don't call sdkSession.start(this); because the SDK will start when user clicks the tap pay button.
Java:
/**
* Configure SDK Theme
*/
private void configureSDKMode(){
/**
* You have to choose only one Mode of the following modes:
* Note:-
* - In case of using PayButton, then don't call sdkSession.start(this); because the SDK will start when user clicks the tap pay button.
*/
/**
* Start using SDK features through SDK main activity (With Tap CARD FORM)
*/
startSDKUI();
}Kotlin:
/**
* Configure SDK Theme
*/
private fun configureSDKMode(){
/**
* You have to choose only one Mode of the following modes:
* Note:-
* - In case of using PayButton, then don't call sdkSession.start(this) because the SDK will start when user clicks the tap pay button.
*/
/**
* Start using SDK features through SDK main activity (With Tap CARD FORM)
*/
startSDKUI()
}If you included Tap Pay Button then configure it first, if not then ignore this step.
Use Tap PayButton
Java:
/**
* Include pay button in merchant page
*/
private void initPayButton() {
payButtonView = findViewById(R.id.payButtonId);
payButtonView.setupFontTypeFace(ThemeObject.getInstance().getPayButtonFont());
payButtonView.setupTextColor(ThemeObject.getInstance().getPayButtonEnabledTitleColor(),
ThemeObject.getInstance().getPayButtonDisabledTitleColor());
//
payButtonView.getPayButton().setTextSize(ThemeObject.getInstance().getPayButtonTextSize());
//
payButtonView.getSecurityIconView().setVisibility(ThemeObject.getInstance().isPayButtSecurityIconVisible()?View.VISIBLE:View.INVISIBLE);
payButtonView.setBackgroundSelector(ThemeObject.getInstance().getPayButtonResourceId());
if(sdkSession!=null){
TransactionMode trx_mode = sdkSession.getTransactionMode();
if(trx_mode!=null){
if (TransactionMode.SAVE_CARD == trx_mode ) {
payButtonView.getPayButton().setText(getString(company.tap.gosellapi.R.string.save_card));
}
else if(TransactionMode.TOKENIZE_CARD == trx_mode ){
payButtonView.getPayButton().setText(getString(company.tap.gosellapi.R.string.tokenize));
}
else {
payButtonView.getPayButton().setText(getString(company.tap.gosellapi.R.string.pay));
}
}else{
configureSDKMode();
}
sdkSession.setButtonView(payButtonView, this, SDK_REQUEST_CODE);
}
}Kotlin:
/**
* Include pay button in merchant page
*/
private void initPayButton() {
payButtonView = findViewById(R.id.payButtonId)
payButtonView.setupFontTypeFace(ThemeObject.getInstance().payButtonFont)
payButtonView.setupTextColor(ThemeObject.getInstance().payButtonEnabledTitleColor,
ThemeObject.getInstance().payButtonDisabledTitleColor)
//
payButtonView.getPayButton().setTextSize(ThemeObject.getInstance().payButtonTextSize)
//
payButtonView.getSecurityIconView().setVisibility(ThemeObject.getInstance().isPayButtSecurityIconVisible?View.VISIBLE:View.INVISIBLE)
payButtonView.setBackgroundSelector(ThemeObject.getInstance().payButtonResourceId)
if(sdkSession!=null){
TransactionMode trx_mode = sdkSession.getTransactionMode();
if(trx_mode!=null){
if (TransactionMode.SAVE_CARD == trx_mode ) {
payButtonView.payButton.text(getString(company.tap.gosellapi.R.string.save_card))
}
else if(TransactionMode.TOKENIZE_CARD == trx_mode ){
payButtonView.payButton.text(getString(company.tap.gosellapi.R.string.tokenize))
}
else {
payButtonView.payButton.text(getString(company.tap.gosellapi.R.string.pay))
}
}else{
configureSDKMode()
}
sdkSession.setButtonView(payButtonView, this, SDK_REQUEST_CODE)
}
}
Java:
/**
* retrieve list of saved cards from the backend.
*/
private void listSavedCards(){
if(sdkSession!=null)
sdkSession.listAllCards("CUSTOMER_ID",this);
} Kotlin:
/**
* retrieve list of saved cards from the backend.
*/
private fun listSavedCards(){
if(sdkSession!=null) sdkSession.listAllCards("CUSTOMER_ID",this)
} To populate TAP Customer object
Java:
private Customer getCustomer() {
return new Customer.CustomerBuilder(null).email("[email protected]").firstName("firstname")
.lastName("lastname").metadata("").phone(new PhoneNumber("965","69045932"))
.middleName("middlename").build();
}Kotlin:
private val customer: Customer
private get() {
val customer = if (settingsManager != null) settingsManager!!.customer else null
val phoneNumber = if (customer != null) customer.phone else PhoneNumber("965", "69045932")
return CustomerBuilder(null).email("[email protected]").firstName("firstname")
.lastName("lastname").metadata("").phone(PhoneNumber(phoneNumber?.countryCode, phoneNumber.number))
.middleName("middlename").build()
}PaymentDataSource is an interface which you should implement somewhere in your code to pass payment information in order to be able to access payment flow within the SDK.
The following table describes its structure and specifies which fields are required for each of the modes.
| Member | Type | Required | Description | ||
|---|---|---|---|---|---|
| Android | Purchase | Authorize | Card Saving | ||
| mode | TransactionMode | false | Mode of the transactions (purchase or authorize). If this property is not implemented, purchase mode is used. | ||
| customer | Customer | true | Customer information. For more details on how to create the customer, please refer to Customer class reference. | ||
| currency | Currency | true | false | Currency of the transaction. | |
| amount | BigDecimal | false | Payment/Authorization amount. Note: In order to have payment amount either amount or items should be implemented. If both are implemented, items is preferred. |
||
| items | ArrayList [PaymentItem] | false | List of items to pay for. Note: In order to have payment amount either amount or items should be implemented. If both are implemented, items is preferred. |
||
| taxes | ArrayList [Tax] | false | You can specify taxation details here. By default, there are no taxes. Note: Specifying taxes will affect total payment/authorization amount. |
||
| shipping | ArrayList [Shipping] | false | You can specify shipping details here. By default, there are no shipping details. Note: Specifying shipping will affect total payment/authorization amount. |
||
| postURL | String | false | The URL which will be called by Tap system notifying that payment has either succeed or failed | ||
| paymentDescription | String | false | Description of the payment. | ||
| paymentMetadata | String | false | Additional information you would like to pass along with the transaction. | ||
| paymentReference | Reference | false | You can keep a reference to the transaction using this property | ||
| paymentStatementDescriptor | String | false | Statement descriptor. | ||
| require3DSecure | Boolean | false | Defines if 3D secure check is required. If not implemented, treated as true. Note: If you disable 3D secure check, it still may occure. Final decision is taken by Tap |
||
| receiptSettings | Receipt | false | Receipt recipient details. | ||
| authorizeAction | AuthorizeAction | false | true | false | Action to perform after authorization succeeds. |
SDK open Interfaces available for implementation through Merchant Project:
- SessionDelegate
public interface SessionDelegate {
void paymentSucceed(@NonNull Charge charge);
void paymentFailed(@Nullable Charge charge);
void authorizationSucceed(@NonNull Authorize authorize);
void authorizationFailed(Authorize authorize);
void cardSaved(@NonNull Charge charge);
void cardSavingFailed(@NonNull Charge charge);
void cardTokenizedSuccessfully(@NonNull Token token);
void sdkError(@Nullable GoSellError goSellError);
void sessionIsStarting();
void sessionHasStarted();
void sessionCancelled();
void sessionFailedToStart();
void invalidCardDetails();
void backendUnknownError();
void invalidTransactionMode();
void invalidCustomerID();
void userEnabledSaveCardOption(boolean saveCardEnabled);
void cardTokenizedSuccessfully(@NonNull Token token,boolean saveCardEnabled);
void asyncPaymentStarted(@NonNull Charge charge);
}- PaymentDataSource
public interface PaymentDataSource {
/**
* Transaction currency. @return the currency
*/
@NonNull TapCurrency getCurrency();
/**
* Customer. @return the customer
*/
@NonNull Customer getCustomer();
/**
* Amount. Either amount or items should return nonnull value. If both return nonnull, then items is preferred. @return the amount
*/
@Nullable BigDecimal getAmount();
/**
* List of items to pay for. Either amount or items should return nonnull value. If both return nonnull, then items is preferred. @return the items
*/
@Nullable ArrayList<PaymentItem> getItems();
/**
* Transaction mode. If you return null in this method, it will be treated as PURCHASE. @return the transaction mode
*/
@Nullable TransactionMode getTransactionMode();
/**
* List of taxes. Optional. Note: specifying taxes will affect total payment amount. @return the taxes
*/
@Nullable ArrayList<Tax> getTaxes();
/**
* Shipping list. Optional. Note: specifying shipping will affect total payment amount. @return the shipping
*/
@Nullable ArrayList<Shipping> getShipping();
/**
* Tap will post to this URL after transaction finishes. Optional. @return the post url
*/
@Nullable String getPostURL();
/**
* Description of the payment. @return the payment description
*/
@Nullable String getPaymentDescription();
/**
* If you would like to pass additional information with the payment, pass it here. @return the payment metadata
*/
@Nullable HashMap<String, String> getPaymentMetadata();
/**
* Payment reference. Implement this property to keep a reference to the transaction on your backend. @return the payment reference
*/
@Nullable Reference getPaymentReference();
/**
* Payment statement descriptor. @return the payment statement descriptor
*/
@Nullable String getPaymentStatementDescriptor();
/**
* Defines if 3D secure check is required. @return the requires 3 d secure
*/
@Nullable boolean getRequires3DSecure();
/**
* Receipt dispatch settings. @return the receipt settings
*/
@Nullable Receipt getReceiptSettings();
/**
* Action to perform after authorization succeeds. Used only if transaction mode is AUTHORIZE_CAPTURE. @return the authorize action
*/
@Nullable AuthorizeAction getAuthorizeAction();
/**
* The Destination array contains list of Merchant desired destinations accounts to receive money from payment transactions
*/
@Nullable
Destinations getDestination();
@Nullable
Merchant getMerchant();
@Nullable
String getPaymentDataType();
/**
* Defines if user wants all cards or specific card types.
*/
@Nullable
CardType getCardType();
/**
* Defines the default cardHolderName. Optional. @return the default CardHolderName
*/
@Nullable String getDefaultCardHolderName();
/**
* Defines if user allowed to edit the cardHolderName. @return the enableEditCardHolderName
* @return
*/
@NonNull boolean getEnableEditCardHolderName();
}SDK open Enums available for implementation through Merchant Project:
- AppearanceMode
public enum AppearanceMode {
/**
* Windowed mode with translucent
*/
@SerializedName("WINDOWED_MODE") WINDOWED_MODE,
/**
* Full screen mode
*/
@SerializedName("FULLSCREEN_MODE") FULLSCREEN_MODE,
}- TransactionMode
public enum TransactionMode {
/**
* Purchase transaction mode.
*/
@SerializedName("PURCHASE") PURCHASE,
/**
* Authorize capture transaction mode.
*/
@SerializedName("AUTHORIZE_CAPTURE") AUTHORIZE_CAPTURE,
/**
* Save card transaction mode.
*/
@SerializedName("SAVE_CARD") SAVE_CARD,
/**
* Tokenize card mode.
*/
@SerializedName("TOKENIZE_CARD") TOKENIZE_CARD,
}- Card Type
public enum CardType {
/**
* Credit card type.
*/
@SerializedName("CREDIT") CREDIT,
/**
* Debit card type.
*/
@SerializedName("DEBIT") DEBIT,
/**
* All card type.
*/
@SerializedName("ALL") ALL
}SDK open Models available for implementation through Merchant Project:
- Customer
public final class Customer implements Serializable {
@SerializedName("id")
@Expose
private String identifier;
@SerializedName("first_name")
@Expose
private String firstName;
@SerializedName("middle_name")
@Expose
private String middleName;
@SerializedName("last_name")
@Expose
private String lastName;
@SerializedName("email")
@Expose
private String email;
@SerializedName("phone")
@Expose
private PhoneNumber phone;
/**
* The Meta data.
*/
@SerializedName("metadata")
String metaData;
}- TapCurrency
public class TapCurrency {
@NonNull
private String isoCode;
/**
* Instantiates a new Tap currency.
*
* @param isoCode the iso code
* @throws CurrencyException the currency exception
*/
public TapCurrency(@NonNull String isoCode) throws CurrencyException {
String code = isoCode.toLowerCase();
if(!LocaleCurrencies.checkUserCurrency(code)) {
throw CurrencyException.getUnknown(code);
}
this.isoCode = code;
}
/**
* Gets iso code.
*
* @return the iso code
*/
@NonNull
public String getIsoCode() {
return isoCode;
}
}-
AuthorizeAction
public final class AuthorizeAction { @SerializedName("type") @Expose private AuthorizeActionType type; @SerializedName("time") @Expose private int timeInHours; /** * Gets default. * * @return the default */ public static AuthorizeAction getDefault() { return new AuthorizeAction(AuthorizeActionType.VOID, 168); } /** * Gets type. * * @return the type */ public AuthorizeActionType getType() { return type; } /** * Gets time in hours. * * @return the time in hours */ public int getTimeInHours() { return timeInHours; } /** * Instantiates a new Authorize action. * * @param type the type * @param timeInHours the time in hours */ public AuthorizeAction(AuthorizeActionType type, int timeInHours) { this.type = type; this.timeInHours = timeInHours; } }
- Destination
public class Destination implements Serializable { @SerializedName("id") @Expose private String id; // Destination unique identifier (Required) @SerializedName("amount") @Expose private BigDecimal amount; // Amount to be transferred to the destination account (Required) @SerializedName("currency") @Expose private String currency; // Currency code (three digit ISO format) (Required) @SerializedName("description") @Expose private String description; // Description about the transfer (Optional) @SerializedName("reference") @Expose private String reference; // Merchant reference number to the destination (Optional) /** * Create an instance of destination * @param id * @param amount * @param currency * @param description * @param reference */ public Destination(String id, BigDecimal amount, TapCurrency currency, String description, String reference) { this.id = id; this.amount = amount; this.currency = (currency!=null)? currency.getIsoCode().toUpperCase():null; this.description =description; this.reference = reference; } /** * * @return Destination unique identifier */ public String getId() { return id; } /** * * @return Amount to be transferred to the destination account */ public BigDecimal getAmount() { return amount; } /** * * @return Currency code (three digit ISO format) */ public String getCurrency() { return currency; } /** * * @return Description about the transfer */ public String getDescription() { return description; } /** * Merchant reference number to the destination * @return */ public String getReference() { return reference; } }
- Destinations
public class Destinations implements Serializable { @SerializedName("amount") @Expose private BigDecimal amount; @SerializedName("currency") @Expose private String currency; @SerializedName("count") @Expose private int count; @SerializedName("destination") @Expose private ArrayList<Destination> destination; /** * @param amount * @param currency * @param count * @param destinations */ public Destinations(@NonNull BigDecimal amount, @NonNull TapCurrency currency, int count, @NonNull ArrayList<Destination> destinations) { this.amount = amount; this.currency = (currency!=null)? currency.getIsoCode().toUpperCase():null; this.count = count; this.destination = destinations; } /** * Total amount, transferred to the destination account * @return */ public BigDecimal getAmount() { return amount; } /** * Tap transfer currency code * @return */ public String getCurrency() { return currency; } /** * Total number of destinations transfer involved * @return */ public int getCount() { return count; } /** * List of destinations object * @return */ public ArrayList<Destination> getDestination() { return destination; } }
- PaymentItem
public class PaymentItem { @SerializedName("name") @Expose private String name; @SerializedName("description") @Expose @Nullable private String description; @SerializedName("quantity") @Expose private Quantity quantity; @SerializedName("amount_per_unit") @Expose private BigDecimal amountPerUnit; @SerializedName("discount") @Expose @Nullable private AmountModificator discount; @SerializedName("taxes") @Expose @Nullable private ArrayList<Tax> taxes; @SerializedName("total_amount") @Expose private BigDecimal totalAmount; }
- Receipt
public final class Receipt implements Serializable { @SerializedName("id") @Expose @Nullable private String id; @SerializedName("email") @Expose private boolean email; @SerializedName("sms") @Expose private boolean sms; /** * Instantiates a new Receipt. * * @param email the email * @param sms the sms */ public Receipt(boolean email, boolean sms) { this.email = email; this.sms = sms; } /** * Gets id. * * @return the id */ public String getId() { return id; } /** * Is email boolean. * * @return the boolean */ public boolean isEmail() { return email; } /** * Is sms boolean. * * @return the boolean */ public boolean isSms() { return sms; } }
- Reference
public final class Reference implements Serializable { @SerializedName("acquirer") @Expose @Nullable private String acquirer; @SerializedName("gateway") @Expose @Nullable private String gateway; @SerializedName("payment") @Expose @Nullable private String payment; @SerializedName("track") @Expose @Nullable private String track; @SerializedName("transaction") @Expose @Nullable private String transaction; @SerializedName("order") @Expose @Nullable private String order; /** * Gets acquirer. * * @return the acquirer */ @Nullable public String getAcquirer() { return acquirer; } /** * Gets gateway. * * @return the gateway */ @Nullable public String getGateway() { return gateway; } /** * Gets payment. * * @return the payment */ @Nullable public String getPayment() { return payment; } /** * Gets track. * * @return the track */ @Nullable public String getTrack() { return track; } /** * Gets transaction. * * @return the transaction */ @Nullable public String getTransaction() { return transaction; } /** * Gets order. * * @return the order */ @Nullable public String getOrder() { return order; } /** * Instantiates a new Reference. * * @param acquirer the acquirer * @param gateway the gateway * @param payment the payment * @param track the track * @param transaction the transaction * @param order the order */ public Reference(@Nullable String acquirer, @Nullable String gateway, @Nullable String payment, @Nullable String track, @Nullable String transaction, @Nullable String order) { this.acquirer = acquirer; this.gateway = gateway; this.payment = payment; this.track = track; this.transaction = transaction; this.order = order; } }
- Shipping
public final class Shipping { @SerializedName("name") @Expose private String name; @SerializedName("description") @Expose @Nullable private String description; @SerializedName("amount") @Expose private BigDecimal amount; /** * Instantiates a new Shipping. * * @param name the name * @param description the description * @param amount the amount */ public Shipping(String name, @Nullable String description, BigDecimal amount) { this.name = name; this.description = description; this.amount = amount; } /** * Gets amount. * * @return the amount */ public BigDecimal getAmount() { return amount; } }
- Tax
public final class Tax { @SerializedName("name") @Expose private String name; @SerializedName("description") @Expose @Nullable private String description; @SerializedName("amount") @Expose private AmountModificator amount; /** * Instantiates a new Tax. * * @param name the name * @param description the description * @param amount the amount */ public Tax(String name, @Nullable String description, AmountModificator amount) { this.name = name; this.description = description; this.amount = amount; } /** * Gets name. * * @return the name */ public String getName() { return name; } /** * Gets description. * * @return the description */ @Nullable public String getDescription() { return description; } /** * Gets amount. * * @return the amount */ public AmountModificator getAmount() { return amount; } }
- CardsList
public class CardsList { private int responseCode; private String object; private boolean has_more; private ArrayList<SavedCard> cards; public CardsList( int responseCode,String object,boolean has_more,ArrayList<SavedCard> data){ this.responseCode = responseCode; this.object = object; this.has_more = has_more; this.cards = data; } /** * Gets Response Code * @return responseCode */ public int getResponseCode(){ return responseCode; } /** * Gets Object type * @return object */ public String getObject() { return object; } /** * Check if customer has more cards * @return has_more */ public boolean isHas_more() { return has_more; } /** * Gets cards. * * @return the cards */ public ArrayList<SavedCard> getCards() { if ( cards == null ) { cards = new ArrayList<>(); } return cards; } }
8.TopUp
public final class TopUp implements Serializable { @SerializedName("id") @Expose String Id; @SerializedName("wallet_id") @Expose String walletId; @SerializedName("created") @Expose @Nullable Long created; @SerializedName("status") @Expose @Nullable String status; @SerializedName("amount") @Expose @Nullable BigDecimal amount; @SerializedName("currency") @Expose @Nullable String currency; @SerializedName("charge") @Expose @Nullable TopchargeModel charge; @SerializedName("customer") @Expose @Nullable TopCustomerModel customer; @SerializedName("reference") @Expose TopUpReference topUpReference; @SerializedName("application") @Expose TopUpApplication application; @SerializedName("response") @Expose @Nullable Response response; @SerializedName("post") @Expose @Nullable TopupPost post; public String getId() { return Id; } public String getWalletId() { return walletId; } @Nullable public Long getCreated() { return created; } @Nullable public BigDecimal getAmount() { return amount; } @Nullable public String getCurrency() { return currency; } @Nullable public TopchargeModel getCharge() { return charge; } @Nullable public TopCustomerModel getCustomer() { return customer; } public TopUpReference getTopUpReference() { return topUpReference; } public TopUpApplication getApplication() { return application; } public MetaData getMetadata() { return metadata; } public Response getResponse() { return response; } @Nullable public TopupPost getPost() { return post; } @SerializedName("metadata") @Expose MetaData metadata; // Constructor is private to prevent access from client app, it must be through inner Builder class only public TopUp(@Nullable String Id , String walletId, @Nullable Long created,@Nullable String status,@Nullable BigDecimal amount , String currency, @Nullable TopchargeModel charge , @Nullable TopCustomerModel customer, @Nullable TopUpReference topUpReference, TopUpApplication topUpApplication, @Nullable Response response, @Nullable TopupPost post,@Nullable MetaData metaData ) { this.Id = Id; this.walletId = walletId; this.created = created; this.status = status; this.amount = amount; this.currency = currency; this.charge = charge; this.customer = customer; this.topUpReference = topUpReference; this.application = topUpApplication; this.response = response; this.post = post; this.metadata = metaData; } } ```
- Destination
SessionDelegate is an interface which you may want to implement to receive payment/authorization/card saving status updates and update your user interface accordingly when payment window closes.
Below are listed down all available callbacks:
Notifies the receiver that payment has succeed.
Java:
- void paymentSucceed(@NonNull Charge charge);Kotlin:
- fun paymentSucceed(charge: Charge)charge: Successful charge object.
Notifies the receiver that payment has failed.
Java:
- void paymentFailed(@Nullable Charge charge);Kotlin:
- fun paymentFailed(charge: Charge?)charge: Charge object that has failed (if reached the stage of charging).
Notifies the receiver that authorization has succeed.
Java:
- void authorizationSucceed(@NonNull Authorize authorize);Kotlin:
- fun authorizationSucceed(authorize: Authorize)authorize: Successful authorize object.
Notifies the receiver that authorization has failed.
Java
- void authorizationFailed(Authorize authorize);Kotlin
- fun authorizationFailed(authorize: Authorize)authorize: Authorize object that has failed (if reached the stage of authorization).
Notifies the receiver that the customer has successfully saved the card.
Java
- void cardSaved(@NonNull Charge charge); // you have to cast Charge object to SaveCard object first to get card info Kotlin
- fun cardSaved(charge: Charge) // you have to cast Charge object to SaveCard object first to get card info Charge: Charge object with the details.
Notifies the receiver that the customer failed to save the card.
Java:
- void cardSavingFailed(@NonNull Charge charge);Kotlin:
- fun cardSavingFailed(charge: Charge)Charge: Charge object with the details (if reached the stage of card saving).
Notifies the receiver that the card has successfully tokenized.
Java
- void cardTokenizedSuccessfully(@NonNull Token token);Kotlin
- fun cardTokenizedSuccessfully(token: Token)token: card token object.
Notifies the receiver that the card has successfully tokenized and user enabled / disabled save card.
Java:
- void cardTokenizedSuccessfully(@NonNull Token token,boolean saveCardEnabled);Kotlin:
- fun cardTokenizedSuccessfully( token:Token, saveCardEnabled:Boolean)token: card token object.
saveCardEnabled: boolean for user enabled/disabled save card.
Notifies the receiver with list of saved cards for a customer. If customer has no cards then you will receive the same response but with empty cards array.
Java:
- void savedCardsList(@NonNull CardsList cardsList);Kotlin:
- fun savedCardsList(cardsList: CardsList)cardsList: CardsList model that holds the response.
Notifies the receiver if any other error occurred.
Java:
- void sdkError(@Nullable GoSellError goSellError);Kotlin:
- fun sdkError(goSellError: GoSellError?)GoSellError: GoSellError object with details of error.
Notifies the client that card data passed are invalid
Java:
- void invalidCardDetails();Kotlin:
- fun invalidCardDetails()Notifies the client that an unknown error has occurred in the backend
Java:
- void backendUnknownError();Kotlin:
- fun backendUnknownError()Notifies the client that Transaction Mode not configured.
Java:
- void invalidTransactionMode();Kotlin:
- fun invalidTransactionMode()Notifies the receiver (Merchant Activity) that the user wants to save his card.
Java:
- void userEnabledSaveCardOption(boolean saveCardEnabled);Kotlin:
- fun userEnabledSaveCardOption(saveCardEnabled: Boolean)Notifies the receiver that session is about to start, but hasn't yet shown the SDK UI. You might want to use this method if you are not using PayButton in your application and want to show a loader before SDK UI appears on the screen.
Java:
- void sessionIsStarting();Kotlin:
- fun sessionIsStarting()Notifies the receiver that session has successfully started and shown the SDK UI on the screen. You might want to use this method if you are not using PayButton in your application and want to hide a loader after SDK UI has appeared on the screen.
Java:
- void sessionHasStarted();Kotlin:
- fun sessionHasStarted()Notifies the receiver that session has failed to start.
Java:
- void sessionFailedToStart();Kotlin:
- fun sessionFailedToStart()Notifies the receiver (Merchant Activity) that the user cancelled payment process, clicked on soft back button, clicked hard back button or clicked Header cancel button.
Java:
- void sessionCancelled();Kotlin:
- fun sessionCancelled()Notifies the receiver (Merchant Activity) that the asynchronous payment has started.
Java:
- void asyncPaymentStarted(@NonNull Charge charge);Java:
- fun asyncPaymentStarted(charge:Charge)Notifies the receiver (Merchant Activity) that the payment of charge has started.
Java:
- void paymentInitiated(@Nullable Charge charge);Java:
- fun paymentInitiated(charge:Charge)Documentation is available at github-pages.
Also documented sources are attached to the library.