RN Connect
Integrate the PortOne React Native SDK to start accepting payments via PortOne.
Integrate with React Native SDK
The PortOne React Native SDK allows merchants to seamlessly integrate the PortOne Payment Gateway into their React Native applications, enabling secure and efficient payment processing.
The PortOne react native SDK offers merchants a seamless way to integrate the PortOne Payment Gateway into their react native applications, enabling them to accept payments securely and efficiently. This SDK serves as a bridge between a merchant's app and the PortOne Payment Gateway, providing a comprehensive set of features tailored specifically for handling payment transactions.
Follow the below steps to integrate the PortOne react native SDK with your react native Application.
Video Tutorial
For a detailed guide on integrating the PortOne RN SDK and using a payment method flow, refer to the following video tutorial
Sample App
Check the sample app to integrate on GitHub
React Native Integration
Prerequisites
-
Create a PortOne Account
- Sign up on PortOne to access services and functionalities.
-
Access API Keys
- Log in to the PortOne portal to obtain API Keys (client key and secret key) under Settings -> API tab.
-
Enable Payment Channels and Methods
- Customize and enable payment channels and methods as per your requirements.
-
React Native Application
- Ensure you have a React Native application ready for SDK integration.
Integration
Steps to integrate your React native application with PortOne React native SDK.
1. Enable Deep Link in iOS
-
Add URL schemes and identifier in info.plist
<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleTypeRole</key> <string>Editor</string> <key>CFBundleURLName</key> <string>checkout</string> <key>CFBundleURLSchemes</key> <array> <string>portone</string> </array> </dict> </array> -
Include URL schemes in info.plist to open other applications
<key>LSApplicationQueriesSchemes</key> <array> <string>itms-appss</string> <string>zalopay</string> <string>line</string> <string>ascendmoney</string> </array> -
Add HTTP connection support in info.plist
<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> <key>NSAllowsLocalNetworking</key> <true/> <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key> <true/> </dict>
2. Enable Deep Link in Android
-
Add an intent filter in AndroidManifest.xml
<intent-filter> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:host="checkout" android:scheme="portone" /> </intent-filter>
3. Obtain JWT Token
-
Generate a JWT token using
portoneKey
on the server. -
Retrieve and store the JWT token securely in your RN app.
For more details, refer to Authentication | PortOne.
4. Generate Signature Hash
Generate a Signature Hash using HmacSHA256 for inclusion in the payload. For details, refer to Payment Request | PortOne.
5. Install the SDK
-
Download the compressed framework folder from this link (Access will be provided by the portone team)
-
Add the folder directly into your workplace and add the package inside the package.json
-
"dependencies": { "portone-sdk": "file:./PaymentSDK", }
-
Install the SDK and peer dependencies
npm install npm install @react-native-async-storage/async-storage npm install react-native-localization npm install react-native-webview npm install react-native-linear-gradient npm install react-native-rsa-native
6. Initialize PortOne RN SDK
-
Import the SDK library
import { Checkout } from 'portone-sdk'; -
Initialize the checkout instance
<Checkout callbackFunction={this.afterCheckout} redirectUrl={"portone://"} environment={"sandbox"} // Optional />
- Handle the web view response in
afterCheckout
afterCheckout = transactionDetails => { console.log('Response from webview', transactionDetails); };
Payment Methods
New Credit Card Payment
-
Collect card details and use the
startPaymentWithNewCard
methodlet response = await Checkout.startPaymentWithNewCard( cardDetails, payload, JWTToken, clientKey, customerUUID, subMerchantKey ); -
Handle the web view response in
afterCheckout
afterCheckout = transactionDetails => { console.log('Response from webview', transactionDetails); };
Saved Card Payment
-
Use the
startPaymentWithSavedCard
methodlet response = await Checkout.startPaymentWithSavedCard( cardDetails, payload, JWTToken, clientKey );
Wallet Payment
-
Use the
startPaymentWithWallets
methodlet data = await Checkout.startPaymentWithWallets(payload, subMerchantKey);
Non-Tokenized Payment
-
Use the
startPaymentWithoutTokenization
methodlet data = await Checkout.startPaymentWithoutTokenization(newPayload, subMerchantKey);
Fetch Available Payment Methods
-
Use the
getAvailablePaymentMethods
methodlet data = await Checkout.getAvailablePaymentMethods(portOneKey, currency, subMerchantKey);
Merchant-Centric Card Vault
The Merchant Centric Card Vault operates by enrolling merchants initially, followed by adding customers specific to each merchant. Cards are then saved based on individual customers, ensuring a personalized and secure card storage system. Several methods are available to facilitate various operations within this card vault setup.
- addCardForCustomer
- deleteCardForCustomerId
- fetchCustomerCards
- addCustomer
- getCustomerData
-
Add Card for Customer
let data = await helpers.addCardForCustomerId(customerId, clientKey, JWTToken, cardData, subMerchantKey); -
Delete Card for Customer
let data = await helpers.deleteCardForCustomerId(customerId, clientKey, JWTToken, cardData, subMerchantKey); -
Fetch Customer Cards
let data = await helpers.fetchCustomerCards(customerId, clientKey, JWTToken, subMerchantKey); -
Add Customer
let data = await helpers.addCustomer(customerData, clientKey, JWTToken, subMerchantKey); -
Get Customer Data
let data = await helpers.getCustomerData(customerID, clientKey, JWTToken);
Failover Routing
Failover routing is a functionality designed to ensure seamless credit card payment processing. This feature allows the configuration of primary and secondary payment channels through the admin portal. If a payment attempt using the primary channel fails for any reason, the system automatically redirects the user to the secondary payment channel.
To support failover routing add the following two parameters to payload:
- isRoutingEnabled= true
- Routing Param type should be failover.
-
Enable failover routing in payload
let payload = getDefaultPayload(); payload.isRoutingEnabled = true; payload.routingParams = { type: "failover", routeRef: "1233" }; -
Fetch list of routes
let data = await helpers.fetchRoutes(clientKey, JWTToken);
PreAuth and Capture Payment
During Pre-authorization, the transaction is initially approved, and at a later time or within specified days, the payment can be processed using the Capture API.
To designate a transaction for pre-authorization, a specific parameter must be configured in the payload:
transactionType= PREAUTH || PURCHASE
-
Pre-Authorization
let payload = getDefaultPayload(); payload.transactionType = "PREAUTH"; -
Capture Payment
let data = await helpers.captureTransactionAPI(transactionOrderRef, clientKey, JWTToken);
Payload Parameters
Parameter | Data Type | Mandatory |
---|---|---|
portOneKey | String | Yes |
merchantDetails | Object | No |
merchantOrderId | String | Yes |
signatureHash | String | Yes |
amount | Double | Yes |
currency | String | Yes |
countryCode | String | Yes |
billingDetails | Object | No |
shippingDetails | Object | No |
orderDetails | Array | No |
successUrl | String | Yes |
failureUrl | String | Yes |
expiryHours | Int | Yes |
source | String | Yes |
description | String | No |
showShippingDetails | Boolean | No |
showBackButton | Boolean | No |
defaultGuestCheckout | Boolean | No |
isCheckoutEmbed | Boolean | No |
redirectUrl | String | Yes |
environment | String | Yes |
MerchantDetails
Parameter | Data Type | Optional |
---|---|---|
name | String | Yes |
logo | String | Yes |
returnUrl | String | Yes |
merchantId | String | No |
mcc | String | No |
OrderDetails
Parameter | Data Type | Optional |
---|---|---|
title | String | Yes |
description | String | Yes |
quantity | Int | Yes |
price | Double | Yes |
BillingDetails
Parameter | Data Type | Optional |
---|---|---|
address | String | Yes |
city | String | Yes |
country | String | Yes |
postalCode | String | Yes |
phone | String | Yes |
ShippingDetails
Parameter | Data Type | Optional |
---|---|---|
address | String | Yes |
city | String | Yes |
country | String | Yes |
postalCode | String | Yes |
phone | String | Yes |
Probable Errors
INVALID_UNAUTHORIZED_JWT_TOKEN_ERROR
INVALID_UNAUTHORIZED_JWT_TOKEN_ERROR
- Check whether PortOne Key and the Secret Key are of the same account
- Check whether the Secret Key is not modified
- Check whether
Bearer
keyword is added before the generated token with a white space.Bearer $jwtToken
- Verify if the expiration time should be greater than the current time
INVALID_UNAUTHORISED_TRANSACTION_SIGNATURE_ERROR
INVALID_UNAUTHORISED_TRANSACTION_SIGNATURE_ERROR
- Check whether all params match with the payload/request
- Check whether the portone key match with the payload and the account
INVALID_UNAUTHORISED_TRANSACTION_IAMPORTKEY_ERROR
INVALID_UNAUTHORISED_TRANSACTION_IAMPORTKEY_ERROR
- Check whether the portone key match with the payload and the account
INVALID_PAYMENT_CHANNEL
INVALID_PAYMENT_CHANNEL
- Make sure the payment channels and payment methods which are added in the payload are enable from the portone portal
INVALID_ENVIRONMENT
INVALID_ENVIRONMENT
- Make sure you have added environment either
sandbox
orlive
Summation of order value, tax, duties, shipping and discount is equal to amount
Summation of order value, tax, duties, shipping and discount is equal to amount
- If items are provided then please verify the values provided should match the total amount:
sum(items price * items quantity) + shipping charge - discount = amount
- Mandatory params in payload:
price
promo_discount (0 is also acceptable)
shipping_charges (0 is also acceptable)
Support
For additional support or questions, please contact the PortOne support team.
Updated 2 months ago