The PortOne Flutter SDK offers merchants a seamless way to integrate the PortOne Payment Gateway into their Flutter 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 tools and features tailored specifically for handling payment transactions.

The PortOne Flutter SDK empowers merchants to unlock the full potential of their Flutter applications by seamlessly integrating a reliable and secure payment gateway, enhancing user experience, and driving business growth through efficient payment processing capabilities

Video Tutorial

Sample App

Check the sample app to integrate on GitHub

Prerequisites

• Create an account on PortOne:
  Before proceeding with the integration, ensure you have created an account on PortOne to access their services and functionalities.
• Enable Payment Channels and Methods:
  Customize and enable the specific payment channels and methods that align with your business requirements and preferences.
• Access API Keys
  Login to the portone portal where you can access the API Keys ( portone key and secret key) for integrations under Settings -> API tab.
• Flutter application for the integration:
  You will need an Flutter application in which you intend to integrate the PortOne Flutter SDK for payment processing capabilities.

Integration

Steps to integrate your Flutter application with PortOne Flutter SDK.

1. Configure the Flutter SDK with the Flutter App
2. Initialise the PortOne Instance
3. Set the Intent Filters in the manifests
4. Add a listener to listen the payment status
5. Setup to Obtain JWT Token from the Server:
6. Generate a Signature Hash for Payload

1. Configure the Flutter SDK with the Flutter App

1. Retrieve the Flutter package distributed by the PortOne team and ensure it is placed at the same directory level as your Flutter application within the folder structure.

2. To integrate the necessary dependencies in your Flutter project, you can update the pubspec.yaml file with the following configuration:

   Dart

   dependencies:
     flutter:
       sdk: flutter
     portone_flutter_package:
       path: /Users/flutter_app_sdk/flutter_sdk
     app_links: ^6.1.1
   

   Parameters	Description
   portone_flutter_package	This is the package where the portone flutter sdk lies and it also has one param name path which requires the path of the sdk. In above code the given path is dummy please put the path where your portone sdk lies.
   app_links: ^6.1.1	The app_links package plays a crucial role in your application by enabling the reception of intents from deep links or other applications. Its functionality is essential for capturing payment status updates seamlessly within your Flutter app.c

2. Initialise the PortOne Instance

• To facilitate checkout processing within your widget, initialize the PortOneImpl() instance. This instance grants access to the checkout methods necessary for transaction processing.
• Additionally, ensure to provide the environment parameter (SANDBOX or LIVE) for seamless integration and transaction testing.

String environment = "sandbox";            // For Sandbox
String environment = "live";               // For Live

late PortOneImpl portone;
portone = PortOneImpl(context, environment);

3. Enable deep links

1. For Android:

   1. Change the project structure to Android from Project or open the android module as project in IDE

   2. To add an Intent Filter to the activity in your AndroidManifest.xml file so that users are navigated to a specific activity (default being Checkout Activity) after payment completion

      XML

      <activity android:name=".CheckoutActivity">
          <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:scheme="portone"
                  android:host="checkout" />
          </intent-filter>
      </activity>
      
      

      In this setup:

      • The <intent-filter> block defines the conditions under which the activity should be launched.
      • The <data> tag specifies the scheme and host required in the incoming Intent for it to be directed to this activity after payment completion.
      • The <activity> tag specifies the activity to which the Intent Filter applies.

   Update the activity name (e.g., .CheckoutActivity) as per your actual activity name and place this Intent Filter configuration within the corresponding <activity> tag in the AndroidManifest.xml file to handle post-payment navigation effectively.

   By configuring the scheme as "portone" and host as "checkout" within the <data> tag of the Intent Filter, your Android application will be able to intercept the redirection URL with the format "portone://checkout" and navigate the user to the specified activity (e.g., CheckoutActivity) after payment completion. Adjust the activity name in the configuration according to your actual activity name for proper redirection handling.

2. For iOS:

   1. To open your application, add the url schemes to the app, Go to ProjectSettings -> info

   2. Add url schemes and identifier inside the URL types.

      You can see the scheme and identifier details in info.plist as below:

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

   3. To open the other applications, should include the url schemes in info.plist

      Swift

      <key>LSApplicationQueriesSchemes</key>
      	<array>
      		<string>itms-appss</string>
      		<string>zalopay</string>
      		<string>line</string>
      		<string>ascendmoney</string>
      	</array>
      
      

      LSApplicationQueriesSchemes - Specifies the URL schemes you want the app to be able to use with the canOpenURL: method of the UIApplication class.

4. Add a listener to listen the payment status by the callback to initState()

1. Receiving Payment Status:

   a. Set up app-to-app communication to receive a deep link via intent post-checkout.

   b. In the root stateful widget, implement initState() and dispose() methods.

   c. Declare variables:

   Dart

   late AppLinks _appLinks;
   StreamSubscription<Uri>? _linkSubscription;
   

2. Initialization in initState():

   a. Initialize initState() method to handle payment status reception:

   Dart

   @override
     void initState() {
       super.initState();
       initDeepLinks();
     }
     
     Future<void> initDeepLinks() async {
       _appLinks = AppLinks();
       _linkSubscription = _appLinks.uriLinkStream.listen((uri) {
         portone.processPaymentStatus(uri,$environment);
       });
     }
   
   

3. Dispose Method Handling:

   a. To cancel the subscription and avoid memory leaks, implement dispose():

   Dart

   @override
     void dispose() {
        _linkSubscription?.cancel();
       super.dispose();
     }
   
   

4. Adding Payment Status Listener:

   a. Implement the following method to capture checkout status post payment completion:

   Dart

   portone.setPaymentStatusListener(
           callback: (Map<String, dynamic> paymentStatus) {
         print('PortOne_PaymentStatus-> $paymentStatus');
       });
   
   

5. Have a setup to get JWT token from the server

To set up the process of obtaining a JWT token from the server, you need to construct a JWT token that accepts the portoneKey as input. Here's an outline of the steps involved in setting up this process:

1. JWT Token Construction:

   Implement the server-side logic to generate a JWT token using the portoneKey as a key component of the token payload.

2. Token Retrieval in Android App:

   • Implement logic in your Android application to make a server request to retrieve the JWT token using the portoneKey.
   • Receive and store the returned token securely within the app for subsequent API authentication.

Authentication | PortOne

6. Generate Signture Hash

To generate a signature hash on the server side using a secret key that will be included in the payload.

Payment Request | PortOne

Flutter Embed

PortOne's Checkout offers a streamlined integration experience, simplifying the process for merchants. This variant involves calling a single method with the essential payload, which results in the PortOne SDK opening a webpage seamlessly. By handling the user interface within the SDK, merchants can focus on the payment flow without concerns about UI intricacies.

Video Tutorial

Implementation

This is the method that has been utilised to process the web checkout.

portone.checkoutUsingWeb(token,
    portoneKey, WebCheckoutRequest());
   

WebCheckoutRequest()

All of the web checkout request's parameters are listed here, along with the appropriate data type.

MerchantDetails

CheckoutPaymentDto.BillingDetails

CheckoutPaymentDto.ShippingDetails

CheckoutPaymentDto.Address

CheckoutPaymentDto.OrderDetail

After the payment completion the payment status will be received on paymentStatus listener which we have already added while integration.

Response:

Receiving the payment status within the override method paymentStatus listener is a common practice in integration to handle payment callbacks. By implementing this method during the integration process, developers can capture and process the payment status information returned by the payment gateway or SDK. This allows for real-time feedback on the payment's success or failure, enabling further actions to be taken based on the outcome of the transaction.

Possible Error Scenarios:

INVALID_UNAUTHORIZED_JWT_TOKEN_ERROR

1. Ensure that the PortOne Key and Secret Key belong to the same account.
2. Confirm that the Secret Key has not been altered.
3. Verify that the Bearer keyword precedes the generated token with a space. Example: Bearer $jwtToken.
4. Check if the token expiration time is after the current time.

INVALID_UNAUTHORIZED_TRANSACTION_SIGNATURE_ERROR

1. Validate if all parameters align with the payload/request.
2. Ensure that the PortOne key matches with the payload and the account.

INVALID_UNAUTHORIZED_TRANSACTION_IAMPORTKEY_ERROR

1. Confirm that the PortOne key matches with the payload and the account.

INVALID_PAYMENT_CHANNEL

1. Validate that the payment channels and methods included in the payload are enabled in the PortOne portal.

INVALID_ENVIRONMENT

1. Verify that an environment (sandbox or live) has been specified.

Summation of order value, tax, duties, shipping, and discount should equal the total amount

1. If items are provided, ensure that the values match the total amount calculation formula: sum(items price * items quantity) + shipping charge - discount = amount.
2. Mandatory parameters in the payload:
   • price
   • promo_discount (0 accepted)
   • shipping_charges (0 accepted)