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

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 (client 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. Set the Intent Filters in the manifests
3. Add a listener to listen the payment status
4. Setup to Obtain JWT Token from the Server:
5. 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.

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

3. 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) {
         print('onAppLink: $uri');
       });
     }
   

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 in the checkout activity to capture checkout status post-completion:

   Dart

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

   By integrating this method, you can effectively capture and process the payment status updates within the checkout activity using the PortOne SDK in your Flutter application.

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

The PortOne SDK requires a JWT token for authentication. You need to implement a server-side process to generate this token and retrieve it in your app.

Steps:

1. Implement server logic to generate a JWT token.
2. In your app, fetch the token to process the checkout.

The process for generating a JWT token can be found in detail here

5. Generate Signture Hash

To generate a signature hash, create it on the server side using a secret key that will be included in the payload. This ensures secure processing of transactions.

Note: Generating a signature hash is optional if you have whitelisted your app while initializing the checkout. Detailed instructions on this are provided in the checkout setup section.

Steps:

1. Implement server logic to generate a signature hash.
2. In your app, fetch the signature hash to process the checkout.

The process for generating a Signature Hash can be found in detail here

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.

Initialize the SDK

To begin using the Flutter Embed SDK, create an instance of the PortOne SDK in the activity where the payment checkout process will take place. Initialize the SDK by specifying the environment—either sandbox for testing or live for production.

Steps

1. Create an instance of the PortOne SDK in your activity.
2. Set the environment to either sandbox for testing or live for production based on your use case.

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

late PortOneImpl portone;
portone = PortOneImpl(context, environment,"com.flutter.example");

Implementation

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

CheckoutUsingEmbedRequest embedCheckoutRequest = CheckoutUsingEmbedRequest()
portone.checkoutUsingEmbed(token,
    portoneKey, embedCheckoutRequest);
   

WebCheckoutRequest()

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

Parameter list for CheckoutEmbedDto.CheckoutUsingEmbedRequest

portone_key

string · required

The unique PortOne key for the merchant.

merchant_details

object

merchant_order_id

string · required

The unique merchant order reference generated by the merchant.

signature_hash

string · required

The signature hash of transaction details.

amount

double · required

The amount of the transaction.

currency

string · required

The currency of the transaction.

country_code

string · required

The country code of the transaction.

billing_details

object

shipping_details

object

order_details

array of objects

success_url

string · required

The URL of the success page hosted by the merchant.

failure_url

string · required

The URL of the failure page hosted by the merchant.

expiry_hours

int · required

The expiry time in hours for the checkout session.

redirect_url

string · required

The URL for redirection after the transaction.

environment

string · required

The environment for the transaction, either sandbox or live.

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)