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:

• [x] iOS
• [x] 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

1. Configure the billing & shipping info, the shipping info is optional

let billingDetails: PaymentSDKBillingDetails = {
    name: 'John Smith',
    email: '[email protected]',
    phone: '+201111111111',
    addressLine: 'Address line',
    city: 'Dubai',
    state: 'Dubai',
    countryCode: 'AE',
    zip: '1234'
};

const shippingDetails: PaymentSDKShippingDetails = {
    name: 'John Smith',
    email: '[email protected]',
    phone: '+201111111111',
    addressLine: 'Address line',
    city: 'Dubai',
    state: 'Dubai',
    countryCode: 'AE',
    zip: '1234'
};

2. 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    

3. 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

1. Follow the guide Steps to configure Apple Pay to learn how to configure ApplePay with PayTabs.

2. 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'
};

3. To simplify ApplePay validation on all user's billing info, pass simplifyApplePayValidation parameter in the configuration with true.

configuration.simplifyApplePayValidation = true

4. 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.

1. Do the steps 1 and 2 from Pay with Card.

2. Choose one or more of the payment methods you want to support.

configuration.alternativePaymentMethods = [PaymentSDKConstants.AlternativePaymentMethod.stcPay]

3. 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][example].

PayTabs

Support | Terms of Use | Privacy Policy