iOS Native SDK Integration

The iOS Native SDK integration involves the following steps below:

1. [Prerequisite] Integrate APIs in Your Backend
2. Installation
3. Initialize SDK
4. Handle Payments
5. Manage Transactions
   1. Get Order by Order ID
   2. Webhooks

📘

Note:

• Ensure you store your Client ID and Secret in your Backend securely.
• Integrate our APIs on your backend system.
• We strictly recommend not to call our APIs from the frontend.
• Failure to adhere to the above guidelines may result in legal implications. In such cases, you will be held responsible for any damage or loss arising from non-compliance.

1. [Prerequisite]

curl --location 'https://pluraluat.v2.pinepg.in/api/auth/v1/token' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--data '
{
  "client_id": "a17ce30e-f88e-4f81-ada1-c3b4909ed232",
  "client_secret": "fgwei7egyhuggwp39w8rh",
  "grant_type": "client_credentials"
}
'

curl --location 'https://api.pluralpay.in/api/auth/v1/token' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--data '
{
  "client_id": "a17ce30e-f88e-4f81-ada1-c3b4909ed232",
  "client_secret": "fgwei7egyhuggwp39w8rh",
  "grant_type": "client_credentials"
}
'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": 3600
}

curl --location 'https://pluraluat.v2.pinepg.in/api/checkout/v1/orders' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--header 'Content-Type: application/json' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'accept: application/json' \
--data '
{
  "merchant_order_reference": "f4c45dbd-6eba-453d-b317-158c6ba12825",
  "order_amount": {
    "value": 500,
    "currency": "INR"
  },
  "purchase_details": {
    "customer": {
      "email_id": "[email protected]",
      "first_name": "joe",
      "last_name": "kumar",
      "customer_id": "192212",
      "mobile_number": "192192883",
			"country_code": "91",
      "billing_address": {
        "address1": "H.No 15, Sector 17",
        "address2": "",
        "address3": "",
        "pincode": "61232112",
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA"
      },
      "shipping_address": {
        "address1": "H.No 15, Sector 17",
        "address2": "string",
        "address3": "string",
        "pincode": "144001123",
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA"
      }
    },
    "merchant_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "integration_mode": "SDK"
  }
}
'

curl --location 'https://api.pluralpay.in/api/checkout/v1/orders' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--header 'Content-Type: application/json' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'accept: application/json' \
--data '
{
  "merchant_order_reference": "f4c45dbd-6eba-453d-b317-158c6ba12825",
  "order_amount": {
    "value": 500,
    "currency": "INR"
  },
  "purchase_details": {
    "customer": {
      "email_id": "[email protected]",
      "first_name": "joe",
      "last_name": "kumar",
      "customer_id": "192212",
      "mobile_number": "192192883",
			"country_code": "91",
      "billing_address": {
        "address1": "H.No 15, Sector 17",
        "address2": "",
        "address3": "",
        "pincode": "61232112",
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA"
      },
      "shipping_address": {
        "address1": "H.No 15, Sector 17",
        "address2": "string",
        "address3": "string",
        "pincode": "144001123",
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA"
      }
    },
    "merchant_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "integration_mode": "SDK"
  }
}
'

{
  "token": "REDIRECT TOKEN",
  "order_id": "ORDER ID",
  "redirect_url": "https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=REDIRECT TOKEN",
  "response_code": 200,
  "response_message": "Order Creation Successful."
}

bussiness_name.com.yourcompany.app

<key>com.apple.developer.in-app-payments</key>
<array>
  <string>merchant.com.yourcompany.app</string>
</array>

2. Installation

🚧

Pre-requisites:

• Before proceeding, ensure that all prerequisites listed in the Quick Guide are fully completed. The required prerequisites may differ depending on the implementation type you choose, so review them carefully for a smooth and seamless experience.

Install the Pine Labs Online iOS Native SDK using Xcode. You can integrate the SDK in two ways — either through Swift Package Manager (SPM) or by manually importing the .xcframework file into your project.

2.1. Add the SDK Using Swift Package Manager (SPM)

Requirements:

• Xcode 12.5 or later.
• iOS 11.0 or higher.

Steps:

1. Open your project in Xcode.
2. Navigate to File → Add Packages…
3. In the search bar, enter the SDK’s GitHub repository URL.

4. Choose the latest Release Tag (e.g. v1.0.2).
5. Add the package to your App Target.

📘

Note:

• When a new version of the SDK is released, you can simply select “Update Package” in Xcode to automatically fetch and integrate the latest build.

2.2. Add the SDK via manual method

Install Pine Labs Online iOS Native SDK using Xcode. To add the SDK to your app, import the .xcframework file to the project using the following steps:

1. Download the SDK Framework: You can download the SDK as a (SDKFramework).xcframework file here, which is in a package format that Apple recommends for distributing binary frameworks.

2. Add Framework to Your Package:

   1. Drag and Drop: Simply drag and drop the (SDKFramework).xcframework file into your Xcode project in the Project Navigator under the Frameworks section.

   2. Dialog Box Settings: A dialog box will appear when you drop the (SDKFramework).xcframework file into your project. Ensure that the checkbox labeled Copy items if needed is selected. This ensures that the framework gets copied into your project directory, making it available whenever you need to build the project.

   3. Drag and drop the .xcframework in the app.

      

   4. copy files to destination.

   

📘

Note:

The userSDKFramework function, created during the SDK installation, implements startPayment. Use this function to pass the order token and initiate the call to ios_SDK.

🚧

Watch Out:

Ensure that the minimum compilation compatibility version is set to iOS 16 or 17

3. Configure the App Target: You need to configure the target to embed the SDK framework properly.

   1. Navigate to the General tab of your target's settings. Add the (SDKFramework).xcframework file under the Frameworks, Libraries, and Embedded Content section.

   2. Ensure you choose Embed & Sign. This ensures the framework is embedded in your app when it's built and signed properly to run on iOS devices.

      

📘

Note:

• Once the .xcframework is embedded, you can import the package in the view controller.

4. Info.plist update: To ensure proper functionality, you must update your app’s Info.plist (Information Property List) file to allow the required connections.
   To enable UPI payments, add the necessary URL Schemes in the Info.plist file as shown below:

Without these entries, the SDK won’t be able to navigate to the required UPI payment app.

3. Initialize SDK

a) To initialise the iOS Native SDK, follow the below steps:

1. Import the SDK into the app and,

2. Create an object of the class EdgeController to initiate the payment function. In your application, you are creating a function that passes the order token received from the create order response to start the payment function of our SDK.

   

Parameters for startPayment:

from: Pass the context of the current ViewController where the SDK is invoked(generally ‘self’).

orderToken: The token generated from the Create Hosted Checkout API response.

environment: Use .uat for testing (default) or .prod for production.

MerchantCallbackResponse: An instance that sends callback messages to the merchant IOS app. This value remains constant.

📘

Note:

• You can use a single build and change the environment variable to run the SDK in either UAT or Production. Currently, only two modes are supported: .uat for UAT and .prod for Production.

b) The user must define a Response Callback class that includes the following functions:

public class MerchantCallbackResponse: UIViewController, ResponseCallback {
  public func onErrorOccured(code: Int, message: String) {
      print("Test app response: error occurred")
      NotificationCenter.default.post(name: Notification.Name("ErrorFlowTransactionNotification"), object: nil)
  }

  public func onTransactionResponse() {
      print("Test app response: transaction response")
        
      // Post a notification for the transaction response and call Inquery from inside it.
      NotificationCenter.default.post(name: Notification.Name("TransactionResponseNotification"), object: nil)
      print("Notification posted.")
      print("Success Flow.")
  }

  public func onCancelTxn(code: Int, message: String) {
      print("Test app response: cancel transaction")
    
      // Post a notification to trigger the flow in the ViewController
      NotificationCenter.default.post(name: Notification.Name("ErrorFlowTransactionNotification"), object: nil)
  }

  public func onPressedBackButton(code: Int, message: String) {
      print("Test app response: back pressed")
  } 
} 

4. Handle Payments

You need to implement call-back methods to handle your payment responses. This will provide the payment status and reason for transaction failures. Based on the reasons for failures, handling can be built at your end. Transaction callbacks can be listened to via overriding methods of ResponseCallback. 

 In case of success, inside the SDK we check if the URL being loaded is the completion/final URL in the checkout flow. If that URL is being opened, then onTransactionResponse() is called from your app, which will return the flow back to your app from the SDK, indicating a successful transaction.

internetNotAvailable: This method is called when the internet is not available.
onErrorOccured: This method is called when SDK is unable to load the payment page.
onPressedBackButton: This method is called when the user presses the back button
onCancelTxn: This method is called when the user cancels the transaction.

public class MerchantCallbackResponse: UIViewController, ResponseCallback {
    
    public func internetNotAvailable(code: Int, message: String) {
        print("Test app response: internet not available")
    }

    public func onErrorOccured(code: Int, message: String) {
        print("Test app response: error occurred")
    }

    public func onTransactionResponse() {
        print("Test app response: transaction response")
    }

    public func onCancelTxn(code: Int, message: String) {
        print("Test app response: transaction cancelled")
    }

    public func onPressedBackButton(code: Int, message: String) {
        print("Test app response: back pressed")
    }
}

5. Manage Transactions

To get the status of the transaction made from your application, you can use our Fetch APIs to know the real time status.

5.1. Get Order by Order ID

Use this API to know the real time status of the transaction made on your application. Refer to our Get Order by Order ID API documentation to learn more.

5.2. Webhooks

You can configure the webhook events to know the status of your transactions. Refer to our Webhooks documentation to learn more.