XPay React Native SDK
XPay Element for React Native is an embedded payment system that allows you to collect payments directly from users within your applications. This package is highly customizable, enabling you to tailor the appearance and functionalities of the payment form to align seamlessly with your app's style and theme.
Features
Seamless Payment Integration
Easily integrate payment functionalities into your app without redirecting users to external applications or pages.
Custom Styling
Style the payment SDK according to your app's theme with customizable labels, placeholders, and more.
Embedded Authentication
Conduct OTP authentication within your app, ensuring a smooth and secure user experience.
Event Handling
Utilize built-in events such as onBinDiscount and onReady to dynamically manage changes and validate inputs.
Prerequisite Dependency
🧩 For React Native versions below 0.76
// using npm
npm i react-native-webview@^11.23.1
// using yarn
yarn add react-native-webview@^11.23.1🧩 For React Native versions 0.76 and above
// using npm
npm i react-native-webview@^13.13.5
// using yarn
yarn add react-native-webview@^13.13.5Getting started
To incorporate the XPay embedded payment system into your application, start by adding the following dependency:
🧩 For React Native versions below 0.76
// for live env.
npm i @xstak/xpay-element-react-native@3.0.2
// for stagging env.
npm i @xstak/xpay-element-react-native-stage@2.5.1🧩 For React Native versions 0.76 and above
// for live env.
npm i @xstak/xpay-element-react-native@4.0.3
// for stagging env.
npm i @xstak/xpay-element-react-native-stage@4.0.3E2E Integration Sample Repo
Usage
To use the XPay SDK in your app, follow these steps:
Import the Package
// for production
import { XPayProvider, PaymentElement, JazzCashPaymentElement, EasyPaisaPaymentElement } from '@xstak/xpay-element-react-native';
// for stagging
import { XPayProvider, PaymentElement, JazzCashPaymentElement, EasyPaisaPaymentElement } from '@xstak/xpay-element-react-native-stage';XPay SDK Integration Guide
The XPay SDK allows you to easily integrate multiple payment options into your app, including:
- Card Payments via
PaymentElement - Easypaisa Payments via
EasyPaisaPaymentElement - JazzCash Payments via
JazzCashPaymentElement
Card Payment Integration
To enable card payments, wrap the PaymentElement inside the XPayProvider. Use the required credentials from your XPay Dashboard:
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<PaymentElement />
</XPayProvider>Easypaisa Payment Integration
To enable Easypaisa payments, wrap the EasyPaisaPaymentElement inside the XPayProvider with the necessary credentials:
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<EasyPaisaPaymentElement />
</XPayProvider>JazzCash Payment Integration
To enable JazzCash payments, wrap the JazzCashPaymentElement inside the XPayProvider with the required credentials:
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<JazzCashPaymentElement />
</XPayProvider>Multiple Payment Methods Together
You can also wrap multiple payment elements inside a single XPayProvider if you're supporting more than one payment method in the same view:
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<>
<View>
<PaymentElement />
</View>
<View>
<JazzCashPaymentElement />
</View>
<View>
<EasyPaisaPaymentElement />
</View>
</>
</XPayProvider>Custom Styling for Payment Elements
Customize the SDK's appearance to seamlessly integrate with your app's style and theme. The XPay SDK allows you to modify elements' style and appearance, making it adaptable to various design requirements. You can customize the appearance of the payment elements using the options prop. This prop allows you to:
- Set labels and placeholders for each field (via
fieldsin style object) - Apply a consistent UI style for labels, inputs, invalid states, focus, and placeholders (via
style)
// For card payment element fileds style props will be
const paymentElementFieldsStyle = {
creditCard: {
label: "Card Number",
placeholder: "1234 1234 1234 1234",
},
expiry: {
label: "Expiry Date",
placeholder: "MM/YY",
},
cvc: {
label: "CVC",
placeholder: "CVC",
},
}
// For JazzCashPaymentElement fileds style props will be
const JazzCashPaymentElementFieldsStyle = {
phoneNumber: {
label: "Phone Number",
placeholder: "0301-2345678",
},
cnic: {
label: "CNIC",
placeholder: "Enter last 6 digits of your CNIC",
},
}
// For EasyPaisaPaymentElement fileds style props will be
const EasyPaisaPaymentElement = {
phoneNumber: {
label: "Phone Number",
placeholder: "0301-2345678",
},
}
// Unified Styling for All Elements
// To avoid repetition when using multiple payment methods, you can define all possible fields in one fields object:
const unifiedStyle = {
fields: {
creditCard: {
label: "Card Number",
placeholder: "1234 1234 1234 1234",
},
expiry: {
label: "Expiry Date",
placeholder: "MM/YY",
},
cvc: {
label: "CVC",
placeholder: "CVC",
},
phoneNumber: {
label: "Phone Number",
placeholder: "0301-2345678",
},
cnic: {
label: "CNIC",
placeholder: "Enter last 6 digits of your CNIC",
},
}
// final custom style object.
const customStyle = {
fields: unifiedStyle, // Field configuration will depend on the element type you're using,
style: {
label: {
color: "#3c4257",
},
input: {
borderWidth: 2,
borderRadius: 5,
padding: 10,
fontSize: 16,
borderColor: "#e6e6e6",
},
invalid: {
borderColor: "red",
borderWidth: 2,
borderRadius: 5,
color: "red",
},
onFocus: {
borderColor: "#C8DBF9",
color: "#3c4257",
},
placeholder: {
color: 'black', // Optional. To use the default color, remove the placeholder from the style object.
},
},
}Applying the Custom Styles
After configuring your styles, pass the customStyle object to the relevant payment element to apply the custom UI styling.
Each element (PaymentElement, EasyPaisaPaymentElement, JazzCashPaymentElement) will automatically pick only the fields it needs (creditCard, expiry, cvc, phoneNumber, cnic, etc.) from the unified customStyle object.
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<>
<PaymentElement customStyle={customStyle} />
<EasyPaisaPaymentElement customStyle={customStyle} />
<JazzCashPaymentElement customStyle={customStyle} />
</>
</XPayProvider>If you're integrating only one or a specific set of payment methods, you can define and pass a tailored customStyle object for each, like so:
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<PaymentElement customStyle={customStyle} />
</XPayProvider>
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<EasyPaisaPaymentElement customStyle={customStyle} />
</XPayProvider>
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<JazzCashPaymentElement customStyle={customStyle} />
</XPayProvider>
The above styling properties are all optional; you can define only those you require, ensuring flexibility and customization according to your specific design needs.
Element Events
Handle element-specific events to enhance the user experience:
onReady Event
This event triggers when all form fields are valid and the form is ready for submission.
// Card Payment Integration using PaymentElement
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<PaymentElement onReady={(data) => { setEnabled(data.complete); }} />
</XPayProvider>
// Easypaisa Payment Integration using EasyPaisaPaymentElement
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<EasyPaisaPaymentElement onReady={(data) => { setEnabled(data.complete); }} />
</XPayProvider>
// JazzCash Payment Integration using JazzCashPaymentElement
<XPayProvider xpay={{ publishableKey: '', hmacSecret: '', accountId: '' }}>
<JazzCashPaymentElement onReady={(data) => { setEnabled(data.complete); }} />
</XPayProvider>
onBinDiscount
Receive data related to the card's BIN as the user inputs their card number, which can be used for implementing discounts or promotional offers.
<XPayProvider xpay={{publishableKey: '', hmacSecret: '', accountId: ''}}>
<PaymentElement onBinDiscount={(data) => {console.log(data)}} />
</XPayProvider>Confirming Payment
To proceed with the payment confirmation when all form fields are valid and the onReady event has returned true, you should perform a few necessary steps. First, ensure you have initiated a server-side API call to create a payment intent. This create intent API is responsible for generating the clientSecret , which are critical for securing the payment confirmation.
Server-Side Payment Intent Creation
Before invoking the payment confirmation on the client side, your backend should call the create intent API to obtain pi_client_secret.
Create Intent API Reference: Please Check the Below Document
Confirming the Payment
Once you have the necessary keys from your backend, use the PaymentElement to call the confirmPayment method. Here’s how you can implement this in your app:
const confirmPayment = async () => {
try {
const customer = { name: 'Jon Doe' };
// Check which payment method the user selected, then call confirmPayment from the corresponding element.
// If the customer is paying via Card
const { message, error } = await PaymentElement.confirmPayment("client_secret_from_intent_api", customer);
// If the customer is paying via Easypaisa
// const { message, error } = await EasyPaisaPaymentElement.confirmPayment("client_secret_from_intent_api", customer);
// If the customer is paying via JazzCash
// const { message, error } = await JazzCashPaymentElement.confirmPayment("client_secret_from_intent_api", customer);
if (error) {
// Handle payment failure
console.log("Payment failed: ", message);
} else {
// Handle payment success
console.log("Payment successful: ", message);
}
} catch (e) {
// Handle unexpected exceptions
console.log("Payment Error: ", e);
}
};
Confirm Payment Response
The response from confirmPayment contains two keys:
error: A boolean that indicates whether the payment was unsuccessful. If true , it means the payment failed. message: A string containing a message from the server. This message provides details about the payment outcome or error information.
Clean Method
The clear method is used to reset the payment form. This is especially useful if you have a button designed to clear the form or reset the checkout process.
You can use the clear method to clear the form of the previously selected payment method when the user switches to a different payment option.
// Clear the fields based on the selected payment method
// Assuming all elements are imported from the XPay SDK
// For Card payment
PaymentElement?.clear();
// For Easypaisa payment
EasyPaisaPaymentElement?.clear();
// For JazzCash payment
JazzCashPaymentElement?.clear();