paytabs-ionic-native v1.0.4
paytabs-ionic-native
PayTabs Ionic Native library is a wrapper for the native PayTabs Android and iOS SDKs, It helps you integrate with PayTabs seamlessly.
Library Support:
- iOS
- Android
Install
npm install paytabs-ionic-native@latest --save --force
npx cap sync
Follow the below steps to complete the installation
- iOS
- Navigate to the iOS folder and run the following command:
pod install
Usage
- Import
import 'paytabs-ionic-native';
import { PaymentSDKBillingDetails, PaymentSDKShippingDetails, PaymentSDKConfiguration, PayTabsIonic } from 'paytabs-ionic-native';
Pay with Card
- Configure the billing & shipping info, the shipping info is optional
let billingDetails: PaymentSDKBillingDetails = {
name: 'John Smith',
email: 'email@domain.com',
phone: '+201111111111',
addressLine: 'Address line',
city: 'Dubai',
state: 'Dubai',
countryCode: 'AE',
zip: '1234'
};
const shippingDetails: PaymentSDKShippingDetails = {
name: 'John Smith',
email: 'email@domain.com',
phone: '+201111111111',
addressLine: 'Address line',
city: 'Dubai',
state: 'Dubai',
countryCode: 'AE',
zip: '1234'
};
- Create object of
PaymentSDKConfiguration
and fill it with your credentials and payment details.
let configuration: PaymentSDKConfiguration = {
profileID: '*profile ID*',
serverKey: '*server key*',
clientKey: '*client key*',
cartID: '12345',
currency: 'USD',
cartDescription: 'Flowers',
merchantCountryCode: 'ae',
merchantName: 'Flowers Store',
amount: 20,
screenTitle: 'Pay with Card',
billingDetails,
shippingDetails,
};
Options to show billing and shipping info
configuration.showBillingInfo = true
configuration.showShippingInfo = true
- Start payment by calling
startCardPayment
method and handle the transaction details
const result = await PayTabsIonic.startCardPayment(configuration);
then you can handle the result like that:
this.handleResult(result);
handleResult(result
:
any
)
{
if (result.status == 'success') {
// Handle transaction details here.
const transactionDetails = result.data;
console.log('responseCode: ' + transactionDetails.paymentResult.responseCode);
console.log('transactionTime: ' + transactionDetails.paymentResult.transactionTime);
console.log('responseMessage: ' + transactionDetails.paymentResult.responseMessage);
console.log('transactionReference: ' + transactionDetails.transactionReference);
console.log('token: ' + transactionDetails.token);
} else if (result.status == 'error') {
// Handle error here the code and message.
} else if (result.status == 'event') {
// Handle events here.
}
}
Pay with Apple Pay
Follow the guide Steps to configure Apple Pay to learn how to configure ApplePay with PayTabs.
Do the steps 1 and 2 from Pay with Card although you can ignore Billing & Shipping details and Apple Pay will handle it, also you must pass the merchant name and merchant identifier.
let configuration: PaymentSDKConfiguration = {
profileID: '*your profile id*',
serverKey: '*server key*',
clientKey: '*client key*',
cartID: '12345',
currency: 'USD',
cartDescription: 'Flowers',
merchantCountryCode: 'ae',
merchantName: 'Flowers Store',
amount: 20,
screenTitle: 'Pay with Card',
merchantName: 'Flowers Store'
merchantIdentifier = 'merchant.com.bundleID'
};
- To simplify ApplePay validation on all user's billing info, pass simplifyApplePayValidation parameter in the configuration with true.
configuration.simplifyApplePayValidation = true
- Call
startApplePayPayment
to start payment
const result = await PayTabsIonic.startApplePayPayment(configuration);
this.handleResult(result);
Pay with Samsung Pay
Pass Samsung Pay token to the configuration and call startCardPayment
configuration.samsungToken = "token"
Pay with Alternative Payment Methods
It becomes easy to integrate with other payment methods in your region like STCPay, OmanNet, KNet, Valu, Fawry, UnionPay, and Meeza, to serve a large sector of customers.
Do the steps 1 and 2 from Pay with Card.
Choose one or more of the payment methods you want to support.
configuration.alternativePaymentMethods = [PaymentSDKConstants.AlternativePaymentMethod.stcPay]
- Start payment by calling
startAlternativePaymentMethod
method and handle the transaction details
const result = await PayTabsIonic.startAlternativePaymentMethod(configuration);
this.handleResult(result);
Enums
Those enums will help you in customizing your configuration.
- Tokenise types
The default type is none
exports.TokeniseType = Object.freeze({
"none": "none", // tokenise is off
"merchantMandatory": "merchantMandatory", // tokenise is forced
"userMandatory": "userMandatory", // tokenise is forced as per user approval
"userOptinoal": "userOptional" // tokenise if optional as per user approval
});
configuration.tokeniseType = cordova.plugins.CordovaPaymentPlugin.TokeniseType.userOptinoal
- Token formats
The default format is hex32
exports.TokeniseFromat = Object.freeze({
"none": "1",
"hex32": "2",
"alphaNum20": "3",
"digit22": "3",
"digit16": "5",
"alphaNum32": "6"
});
configuration.tokeniseFormat = cordova.plugins.CordovaPaymentPlugin.TokeniseFromat.hex32
- Transaction types
The default type is sale
const TransactionType = Object.freeze({
"sale": "sale",
"authorize": "auth"
});
configuration.transactionType = cordova.plugins.CordovaPaymentPlugin.TransactionType.sale
- Alternative payment methods
AlternativePaymentMethod = Object.freeze({
"unionPay": "unionpay",
"stcPay": "stcpay",
"valu": "valu",
"meezaQR": "meezaqr",
"omannet": "omannet",
"knetCredit": "knetcredit",
"knetDebit": "knetdebit",
"fawry": "fawry"
});
configuration.alternativePaymentMethods = [cordova.plugins.CordovaPaymentPlugin.AlternativePaymentMethod.stcPay, ...]
API
startCardPayment(...)
startTokenizedCardPayment(...)
start3DSecureTokenizedCardPayment(...)
startPaymentWithSavedCards(...)
startApplePayPayment(...)
queryTransaction(...)
startAlternativePaymentMethod(...)
- Interfaces
startCardPayment(...)
startCardPayment(options
:
PaymentSDKConfiguration
) =>
Promise<any>
Param | Type |
---|---|
options | PaymentSDKConfiguration |
Returns: Promise<any>
startTokenizedCardPayment(...)
startTokenizedCardPayment(options
:
PaymentSDKTokenizationArgument
) =>
Promise<any>
Param | Type |
---|---|
options | PaymentSDKTokenizationArgument |
Returns: Promise<any>
start3DSecureTokenizedCardPayment(...)
start3DSecureTokenizedCardPayment(options
:
PaymentSDKConfiguration, savedCardInfo
:
PaymentSDKSavedCardInfo, token
:
string
) =>
Promise<any>
Param | Type |
---|---|
options | PaymentSDKConfiguration |
savedCardInfo | PaymentSDKSavedCardInfo |
token | string |
Returns: Promise<any>
startPaymentWithSavedCards(...)
startPaymentWithSavedCards(options
:
PaymentSDKConfiguration, support3ds
:
boolean
) =>
Promise<any>
Param | Type |
---|---|
options | PaymentSDKConfiguration |
support3ds | boolean |
Returns: Promise<any>
startApplePayPayment(...)
startApplePayPayment(options
:
PaymentSDKConfiguration
) =>
Promise<any>
Param | Type |
---|---|
options | PaymentSDKConfiguration |
Returns: Promise<any>
queryTransaction(...)
queryTransaction(options
:
PaymentSDKQueryConfiguration
) =>
Promise<any>
Param | Type |
---|---|
options | PaymentSDKQueryConfiguration |
Returns: Promise<any>
startAlternativePaymentMethod(...)
startAlternativePaymentMethod(options
:
PaymentSDKConfiguration
) =>
Promise<any>
Param | Type |
---|---|
options | PaymentSDKConfiguration |
Returns: Promise<any>
Interfaces
PaymentSDKConfiguration
PaymentSDKConfiguration: payment request configuration
Prop | Type | Description |
---|---|---|
profileID | string | merchant profile id |
serverKey | string | merchant server key |
clientKey | string | merchant client key |
transactionType | string | transaction type: refer to TransactionType enum |
transactionClass | string | transaction class: refer to TransactionClass enum |
cartID | string | order or cart id |
currency | string | payment currency |
amount | number | amount |
cartDescription | string | order or cart description |
languageCode | string | user interface language code(en, ar, ..) |
forceShippingInfo | boolean | validate shipping info |
showBillingInfo | boolean | validate billing info |
showShippingInfo | boolean | handle missing shipping info by showing shipping info section |
billingDetails | PaymentSDKBillingDetails | configured billing details |
shippingDetails | PaymentSDKShippingDetails | configured shipping details |
merchantCountryCode | string | merchant country code |
screenTitle | string | title of the screen |
merchantName | string | merchant name |
serverIP | string | server ip |
tokeniseType | string | tokenise type: refer to TokeiseType enum |
tokenFormat | string | token format: refer to TokeiseFormat enum |
hideCardScanner | string | option to hide or show card scanner button |
merchantApplePayIdentifier | string | merchant Apple Pay bundle id |
simplifyApplePayValidation | string | minimize the validation on Apple Pay billing and shipping info |
supportedApplePayNetworks | string | supported Apple Pay networks |
token | string | returned token |
isDigitalProduct | boolean | is digital product |
transactionReference | string | returned transaction reference |
samsungToken | string | samsung Token |
theme | PaymentSDKTheme | customized theme |
alternativePaymentMethods | string | list of alternative payment methods |
PaymentSDKBillingDetails
PaymentSDKBillingDetails
Prop | Type | Description |
---|---|---|
name | string | billing: customer name |
email | string | billing: customer email |
phone | string | billing: customer phone |
addressLine | string | billing: customer address line |
city | string | billing: customer city |
state | string | billing: customer state |
countryCode | string | billing: customer country code |
zip | string | billing: customer zip code |
PaymentSDKShippingDetails
PaymentSDKShippingDetails
Prop | Type | Description |
---|---|---|
name | string | shipping: customer name |
email | string | shipping: customer email |
phone | string | shipping: customer phone |
addressLine | string | shipping: customer address line |
city | string | shipping: customer city |
state | string | shipping: customer state |
countryCode | string | shipping: customer country code |
zip | string | shipping: customer zip code |
PaymentSDKTheme
PaymentSDKTheme
Prop | Type | Description |
---|---|---|
primaryColor | string | theme: primary color |
primaryFontColor | string | theme: primary font color |
primaryFont | string | theme: primary font |
secondaryColor | string | theme: secondary color |
secondaryFontColor | string | theme: secondary font color |
secondaryFont | string | theme: secondary font |
strokeColor | string | theme: stroke color |
strokeThinckness | number | theme: primary color |
inputsCornerRadius | number | theme: input corner radius |
buttonColor | string | theme: button color |
buttonFontColor | string | theme: button font color |
buttonFont | string | theme: button font |
titleFontColor | string | theme: title font color |
titleFont | string | theme: title font |
backgroundColor | string | theme: background color |
placeholderColor | string | theme: placeholder color |
logoImage | string | theme: logo |
PaymentSDKTokenizationArgument
PaymentSDKTokenizationArgument: tokenization configuration
Prop | Type | Description |
---|---|---|
configurations | PaymentSDKConfiguration | payment configurations |
token | string | trx token |
transactionReference | string | transaction reference |
PaymentSDKSavedCardInfo
PaymentSDKSavedCardInfo
Prop | Type | Description |
---|---|---|
maskedCard | string | maskedCard: Card mask |
cardType | string | cardType: card type (visa, mc...) |
PaymentSDKQueryConfiguration
PaymentSDKQueryConfiguration: query request configuration
Prop | Type | Description |
---|---|---|
serverKey | string | merchant server key |
clientKey | string | merchant client key |
merchantCountryCode | string | merchant country code |
profileID | string | merchant profile id |
transactionReference | string | returned transaction reference |
PaymentSDKCardDiscount
PaymentSDKCardDiscount: add discount to the payment
Prop | Type | Description |
---|---|---|
discountCards | string | a list of card prefixes |
discountValue | string | the discount value |
discountTitle | string | the title of the discount |
isPercentage | string | true if the discount value is percentage |
let discounts: PaymentSDKCardDiscount[] = [
{
discountCards: ['4111'],
discountValue: 5,
discountTitle: '5% Discount on VISA cards starting with 4111',
isPercentage: true
},
{
discountCards: ['4000', '41111'],
discountValue: 10,
discountTitle: '10 USD Discount on VISA card starts with 4000,41111',
isPercentage: false
}
];
Demo application
Check our complete example.