iOS Web SDK Integration

The iOS Web SDK integration involves the following steps below:

1. Installation
2. Integrate APIs in Your Backend
   1. Generate Auth Token
   2. Create Hosted Checkout
3. Initialize SDK
4. Handle Payments
5. Manage Transactions
   1. Fetch APIs
   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.

1. Installation

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

1. Download the SDK Framework: You can download the SDK as a .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 .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 .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.

🚧

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 .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. Network Check: In the SDK, there is an internet connectivity function that accesses a URL (example.com). To ensure this works as expected, you need to update the Info.plist[Information Property List] file in your app to allow this connection.

👍

Ensure

• Once this is added, you can check if the exception is being displayed in the Signing and Capabilities tab

2. Integrate APIs in Your Backend

Start a payment by triggering the payment flow. To start a payment follow the below steps:

2.1. Generate Auth Token

Integrate our Generate Token API in your backend servers to generate the auth token. Use the token generated to authenticate Plural APIs.

Use the below endpoint to generate a token.

POST: https://pluraluat.v2.pinepg.in/api/auth/v1/token

POST: https://api.pluralpay.in/api/auth/v1/token

Below is a sample request and response for the Generate Token API.

{
  "client_id": "1234567890",
  "client_secret": "asdfgwei7egyhuggwp39w8rh",
  "grant_type": "client_credentials"
}

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

Refer to our Generate Token API documentation to learn more.

2.2. Create Hosted Checkout

Use this API to create a hosted checkout, for authentication use the generated access token in the headers of the API request.

Use the below endpoint to Create Hosted Checkout.

POST: https://pluraluat.v2.pinepg.in/api/checkout/v1/orders

POST: https://api.pluralpay.in/api/checkout/v1/orders

Below is a sample request and response for a Create Hosted Checkout API.

{
  "merchant_order_reference": 112345171,
  "order_amount": {
    "value": 500,
    "currency": "INR"
  },
  "pre_auth": false,
  "purchase_details": {
    "customer": {
      "email_id": "[email protected]",
      "first_name": "Kevin",
      "last_name": "Bob",
      "customer_id": "192212",
      "mobile_number": "9876543210",
      "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": "",
        "address3": "",
        "pincode": "144001123",
        "city": "CHANDIGARH",
        "state": "PUNJAB",
        "country": "INDIA"
      }
    },
    "merchant_metadata": {
      "key1": "DD",
      "key2": "XOF"
    }
  }
}

{
  "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."
}

Refer to our Create Hosted Checkout API documentation to learn more.

3. Initialize SDK

To initialise the iOS web SDK, follow the below steps:

1. Import the SDK into the app and,
2. Create an object of the class EdgeController to start a payment function. You are creating a function in your app that passes the redirect[challenge] URL to start the payment function of our SDK.

import UIKit
import IOS_SDK_V2

class ViewController: UIViewController {

    func UsingFramework(redirectUrl: String) {
        let IOS_Framework_Object = EdgeController()
        IOS_Framework_Object.startPayment(from: self, withURL: redirectUrl, callBack: ResponseCallback())
    }
}

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. 

onTransactionResponse: This method is called when the transaction is completed. Transaction can be a failure or a success. 
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.