iOS Native SDK Integration Steps

Learn how you can start integrating with Pine Labs Online iOS Native SDK.

The iOS Native SDK integration involves the following steps below:

  1. Prerequisite
  2. Installation
  3. Configure the App Target
  4. Initialize SDK
  5. Handle Payments
  6. Manage Transactions
    1. Get Order by Order ID
    2. Webhooks

📘

Note:

  • Ensure you store your client_id and client_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

1.1. Platform & Build Environment

iOS SDK Requirements & Specifications

CategoryMinimum SupportedDescription
iOS VersioniOS 16.0Apps must target iOS 16 or higher
Deployment TargetiOS 16.0Required for SDK integration
Swift Version (SDK)Swift 5.xSDK is built using Swift 5
Swift Version (App)Swift 4+App source can be Swift 4 or later
Xcode VersionXcode 15.0+Required to build iOS 16 apps
Framework TypeXCFrameworkDevice + simulator support
Architecturesarm64Apple Silicon compatible
1.2. Enable Apple Pay Capability in Xcode

1. Open Your Project in Xcode

  1. Launch Xcode and open your project.

  2. In the Project Navigator (left panel), select your project name.

  3. Under Targets, select your app target.

2. Configure Signing & Capabilities

  1. Click on the Signing & Capabilities tab at the top of the main editor.

  2. Ensure that your Team and Bundle Identifier are properly configured.

  3. Verify that your project uses a valid Apple Developer account (with Merchant ID access).

3. Add the Apple Pay Capability

  1. Click the **+ Capability** button in the top-left corner.
  2. In the popup, search for Apple Pay.
  3. Double-click Apple Pay (or press Enter) to add it.
  4. The Apple Pay capability will now appear under your app’s capabilities list.

4. Configure Merchant IDs

  1. Under the newly added Apple Pay section, locate Merchant IDs.
  2. Click the “+” button to add one.
  3. Select an existing Merchant ID if already created in the Apple Developer Portal.
  4. If not available, choose “Add an Account → Manage Certificates, Identifiers & Profiles” to create a new Merchant ID.
  5. Use a naming convention such as:
bussiness_name.com.yourcompany.app

5. Verify Entitlements

Xcode automatically adds the required entitlements file (if not already present) and enables the following key:

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

This ensures your app is authorized to process Apple Pay transactions using the registered Merchant ID(s).

1.3. Integrate APIs in Your Backend

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

1.3.1. Generate Token

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

Below are the sample requests and response for the Generate Token API.

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
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

The table below lists the request parameters of our Generate Token API.

Parameter Type Description
client_id required string Unique client identifier in the Pine Labs Online database.

Example: a17ce30e-f88e-4f81-ada1-c3b4909ed232

Note: The Onboarding team has provided you with this information as part of the onboarding process.
client_secret required string Unique client secret key provided while onboarding.

Example: fgwei7egyhuggwp39w8rh

Note: The Onboarding team has provided you with this information as part of the onboarding process.
grant_type required string The grant type to generate an access token.

Accepted value: client_credentials

The table below lists the response parameters of our Generate Token API.

Parameter Type Description
access_token string The access token generated by the system.

• Minimum length: 1 character.
• Maximum length: 8192 characters.

Example: eyJhbGciOiJIUzI1NiIsIn

Note: Use this token in the authorization headers to authenticate Pine Labs Online APIs.
expires_at string Access duration timestamp.

Example: 2024-06-28T13:26:06.909140Z

Refer to our Generate Token API documentation to learn more.


1.3.2. Generate Checkout Link

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

Below are the sample requests and response for a Generate Checkout Link API.

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": "112345",
  "order_amount": {
    "value": 1100,
    "currency": "INR"
  },
  "integration_mode": "SDK",
  "pre_auth": false,
  "allowed_payment_methods": [
    "CARD",
    "UPI",
    "NETBANKING",
    "POINTS",
    "WALLET"
  ],
  "notes": "order1",
  "callback_url": "https://sample-callback-url",
  "failure_callback_url": "https://sample-failure-callback-url",
  "purchase_details": {
    "customer": {
      "email_id": "[email protected]",
      "first_name": "Kevin",
      "last_name": "Bob",
      "customer_id": "123456",
      "mobile_number": "9876543210",
      "country_code": "91",
      "billing_address": {
        "address1": "10 Downing Street Westminster London",
        "address2": "Oxford Street Westminster London",
        "address3": "Baker Street Westminster London",
        "pincode": "51524036",
        "city": "Westminster",
        "state": "Westminster",
        "country": "London",
        "full_name": "harsh kumar",
        "address_type": "HOME/WORK/OTHER",
        "address_category": "BILLING"
      },
      "shipping_address": {
        "address1": "10 Downing Street Westminster London",
        "address2": "Oxford Street Westminster London",
        "address3": "Baker Street Westminster London",
        "pincode": "51524036",
        "city": "Westminster",
        "state": "Westminster",
        "country": "London",
        "full_name": "harsh kumar",
        "address_type": "HOME/WORK/OTHER",
        "address_category": "BILLING"
      }
    },
    "merchant_metadata": {
      "express_checkout_enabled": "TRUE",
      "express_checkout_allowed_action": "checkoutCollectAddress",
      "key1": "DD",
      "key2": "XOF"
    }
  },
  "cart_details": {
    "cart_items": [
      {
        "item_id": "cart_id_1",
        "item_name": "T Shirt",
        "item_description": "Test Description",
        "item_details_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
        "item_image_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
        "item_original_unit_price": 1,
        "item_discounted_unit_price": 1,
        "item_quantity": 1,
        "item_currency": "INR"
      }
    ]
  }
}
'
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": "112345",
  "order_amount": {
    "value": 1100,
    "currency": "INR"
  },
  "integration_mode": "SDK",
  "pre_auth": false,
  "allowed_payment_methods": [
    "CARD",
    "UPI",
    "NETBANKING",
    "POINTS",
    "WALLET"
  ],
  "notes": "order1",
  "callback_url": "https://sample-callback-url",
  "failure_callback_url": "https://sample-failure-callback-url",
  "purchase_details": {
    "customer": {
      "email_id": "[email protected]",
      "first_name": "Kevin",
      "last_name": "Bob",
      "customer_id": "123456",
      "mobile_number": "9876543210",
      "country_code": "91",
      "billing_address": {
        "address1": "10 Downing Street Westminster London",
        "address2": "Oxford Street Westminster London",
        "address3": "Baker Street Westminster London",
        "pincode": "51524036",
        "city": "Westminster",
        "state": "Westminster",
        "country": "London",
        "full_name": "harsh kumar",
        "address_type": "HOME/WORK/OTHER",
        "address_category": "BILLING"
      },
      "shipping_address": {
        "address1": "10 Downing Street Westminster London",
        "address2": "Oxford Street Westminster London",
        "address3": "Baker Street Westminster London",
        "pincode": "51524036",
        "city": "Westminster",
        "state": "Westminster",
        "country": "London",
        "full_name": "harsh kumar",
        "address_type": "HOME/WORK/OTHER",
        "address_category": "BILLING"
      }
    },
    "merchant_metadata": {
      "express_checkout_enabled": "TRUE",
      "express_checkout_allowed_action": "checkoutCollectAddress",
      "key1": "DD",
      "key2": "XOF"
    }
  },
  "cart_details": {
    "cart_items": [
      {
        "item_id": "cart_id_1",
        "item_name": "T Shirt",
        "item_description": "Test Description",
        "item_details_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
        "item_image_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
        "item_original_unit_price": 1,
        "item_discounted_unit_price": 1,
        "item_quantity": 1,
        "item_currency": "INR"
      }
    ]
  }
}
'
{
  "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."
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

The table below lists the request parameters of our Create Checkout Link API.

Parameter Type Description
merchant_order_reference required string Enter a unique identifier for the order request.

  • Minimum: 1 character.
  • Maximum: 50 characters.
Example: 1234567890

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • -
  • _
order_amount required object An object that contains the transaction amount details.

Learn more about the order_amount child object.
pre_auth boolean The pre-authorization type.

Possible values:
  • false (default): When pre-authorization is not required.
  • true: When pre-authorization is needed.
allowed_payment_methods array of strings The type of payment methods you want to offer customers.

Accepted values:
  • CARD
  • UPI
  • POINTS
  • NETBANKING
  • WALLET
  • CREDIT_EMI
  • DEBIT_EMI
Example: CARD

Note: Ensure it is configured for you.
notes string Note to show against an order.

Example: Order1
callback_url string Use this URL to redirect your customers to specific success or failure pages based on the order or product details.

Example: https://sample-callback-url
failure_callback_url string Use this URL to redirect your customers to specific failure pages based on the order or product details.

Example: https://sample-failure-callback-url
purchase_details object An object that contains purchase details.

Learn more about the purchase_details child object.
cart_details object An object that contains cart details.

Learn more about the cart_details child object.

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object. This object is part of the Create Checkout Link request object.

Parameter Type Description
value required integer Transaction amount in Paisa.

  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currency required string Type of currency.

Example: INR

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the Create Checkout Link request object.

Parameter Type Description
customer object An object that contains the customer details.

Learn more about the customer child object.
merchant_metadata object An object of key-value pair that can be used to store additional information.

Learn more about the merchant_metadata child object.

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter Type Description
email_id string Customer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210
country_code string Country code of the registered mobile number.
  • Maximum length: 5 characters.
Example: 91

Note: If the country code is not provided, it defaults to 91.
billing_address object An object that contains the details of the billing address.

Learn more about our billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about our shipping_address child object.

Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London
full_namestringFull name of the customer.
  • Max length: 50 characters.
Example: Doctor Strange
address_typestringType of the billing address.

Example: Home

Accepted values:
  • HOME
  • WORK
  • OTHER
address_categorystringAddress category.

Example: Billing

Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London
full_namestringFull name of the customer.
  • Max length: 50 characters.
Example: Doctor Strange
address_typestringType of the shipping address.

Example: Home

Accepted values:
  • HOME
  • WORK
  • OTHER
address_categorystringAddress category.

Example: Shipping

Merchant Metadata [Child Object]

The table below lists the various parameters in the merchant_metadata child object. This object is part of the purchase_details child object.

Parameter Type Description
express_checkout_allowed_action string Access allowed during the express checkout.

Accepted values:
  • checkoutCollectAddress: We will collect the address of the customer during the checkout.
  • checkoutCollectMobile: We will collect the mobile number of the customer during the checkout.

Cart Details [Child Object]

The table below lists the various parameters in the cart_details child object. This object is part of the Create Checkout Link request object.

Parameter Type Description
cart_items array of objects An object that contains the cart item details.

Learn more about the cart_itmes child object.

Cart Items [Child Object]

The table below lists the various parameters in the cart_items child object. This object is part of the cart_details child object.

Parameter Type Description
item_id string Unique identifier of the item.

Example: cart_id_1
item_name string Name of the item.

Example: T Shirt
item_description string Description corresponding to the item.

Example: Shopping on Diwali Sale
item_image_url string Image URL of the item.

Example: https://chriscross.in/cdn/shop/files/95_800x.jpg

Note: To ensure better resolution and optimal display on the checkout, please provide the image in 24x24 dimensions.
item_original_unit_price string Original price of the item.

Example: 199
item_discounted_unit_price string Discount price of the item.

Example: 49
item_quantity string Number of items purchased.

Example: 2
item_currency string Indicates the currency type for the purchase of the item.

Example: INR

The table below lists the various parameters returned in the Generate Checkout Link response objects.

Parameter Type Description
token string Token generated by our system for Pine Labs Online Hosted Checkout.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
order_id string Unique identifier of the order in the Pine Labs Online database.

Example: v1-5757575757-aa-hU1rUd
redirect_url string The checkout link generated on our system.

Example: https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=<>
response_code integer Response code of the request.

Example: 200
response_message string Corresponding message to the response code.

Example: Order Creation Successful

Refer to our Generate Checkout Link API documentation to learn more.


2. Installation

Follow the below steps to install Pine Labs Online iOS Native SDK using Xcode. We provide two methods to integrate our SDK into your project.

Pine Labs SDK Installation Tabs

2.1 Add the SDK via Swift Package Manager

Recommended method for easy updates and dependency management

Requirements

Xcode 12.5+ iOS 11.0+

Installation Steps

1

Open your project in Xcode

Launch Xcode and open your iOS project.

2

Navigate to Add Packages

Go to the menu:

File → Add Packages…
3

Enter SDK GitHub URL

In the search bar, paste the SDK GitHub URL https://github.com/plural-pinelabs/Infinity_Checkout_iOS_SDK.

4

Select Release Tag

Choose the latest Release Tag (e.g., 1.1.1).

5

Add to App Target

Add the package to your App Target.

6

Verify Installation

Once added, it should appear in the General tab of your app target. You can also see the package details by clicking on the Package Dependency.

You can also see the package details by clicking on the Package Dependency.

Easy Updates

In case of any new release update, simply select Update Package and it will automatically get the latest build.

2.2 Add the SDK via Manual Method

To add the SDK to your app, import the (SDKFramework).xcframework file to the project using the following steps:

Installation 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

Drag and Drop Framework

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

3

Configure Dialog Settings

A dialog box will appear when you drop the framework file into your project.

Ensure that the checkbox labeled "Copy items if needed" is selected. This ensures the framework gets copied into your project directory, making it available for builds.

4

Complete Installation

Drag and drop the .xcframework in the app.

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.
  1. 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:
property-list-view

Figure: Property List View

Source Code View

Figure: Source Code View

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


4. Initialize SDK

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.

    Initialize Code

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.

5. 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 onSuccessResponse() is called from your app, which will return the flow back to your app from the SDK, indicating a successful transaction.

onFailureResponse: This method is called when SDK reaches a failure state.

onSuccessResponse: This method is called when the SDK reaches the success state.

onCancelTxn: This method is called when the user cancels the transaction.

onPressedBackButton: This method is called when the user presses the back button.

public class MerchantCallbackResponse: UIViewController, ResponseCallback {

    public func onFailureResponse(orderID: String, status: String, code: String, message: String) {
        print("Test app response: error occurred")
    }

    public func onSuccessResponse(orderId: String, status: String) {
        print("Test app response: transaction response")
    }

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

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

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

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

6.2. Webhooks

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


Ask AI
Assistant
Order Lifecycle
Refunds
Settlements
Checkout
Dashboard
International Payments
How do I implement webhook notifications for payment status updates, and what's the recommended way to verify webhook authenticity?
How do I integrate Pine Labs payment gateway with my React Native mobile app and what are the required API credentials?
Can I customize the payment UI for card transactions, and what parameters can I pass to modify the checkout experience for my customers?
Assistant