iOS PnP SDK

Accept payments in your iOS apps using our Native iOS SDK. With our mobile SDKs, you do not need to worry about PCI-DSS compliance by eliminating the need to send card data to your server. Instead, our libraries send the card data directly to PayU servers which are PCI-DSS Compliant

With built-in support for the PayUmoney Wallet, Saved Cards and one of the largest coverage of banks for NetBanking, the PayUmoney iOS Plug and Play SDK is a quick and easy way to integrate payment checkout experiences in your app and start accepting payments from your users.

You can check out our sample app in GitHub here for reference
https://github.com/payu-intrepos/PayUMoney-IOS-SDK/tree/master/PlugNPlay/Objective-C%20SampleApp

Features Supported

The PayUmoney Plug n Play SDK for iOS supports the following features:

  • Plug N Play UI
  • Saved Cards
  • Multiple Payments methods
  • Custom Browser

  • Seamless login to PayUmoney accounts

Payment Modes Supported

The following payment modes are supported in the PayUmoney iOS SDK.

Steps to Integrate

1

Prerequisites

Meet the Prerequisites

2

Install and configure

Install and configure the SDK as shown in the guide

3

Server Side Changes

Calculate the server-side hash to secure the transaction

4

Initiate Transaction Request

Set the transaction details & hash on the SDK and start payment activity

5

Response Handling

Verify the response hash and display transaction status to the payer

Getting Started with the iOS SDK

This guide will take you through building your app's payment flow using PayUmoney iOS PnP SDK. The SDK handles collecting, saving, and reusing your user's payment details, and can also be used to collect billing info. Have a look at the iOS SDK Payment Activity Diagram before you take the deep dive.

Steps to Integrate

1

Prerequisites

Meet the Prerequisites

2

Install and configure

Install and configure the SDK as shown in the guide

3

Server Side Changes

Calculate the server-side hash to secure the transaction

4

Initiate Transaction Request

Set the transaction details & hash on the SDK and start payment activity

5

Response Handling

Verify the response hash and display transaction status to the payer

Prerequisites

To Integrate PayUmoney iOS SDK, you must :

  • Signup with PayUmoney (if you don’t already have an account with PayUmoney)
  • Retrieve your merchant ID, key & salt, which are available in your PayUmoney Dashboard

Add PNP SDK to your Project

Manually include PnP framework

If you’d like to download and maintain the framework manually, please follow the steps listed below:

1. Add PNP SDK to your Xcode project from Github
  • Clone it using following command
$ git clone --recursive https://github.com/payu-intrepos/PayUMoney-IOS-SDK.git
  • Navigate to the "PlugNPlay" folder & drag the PlugNPlay.framework into your existing Xcode project
  • In Xcode, go to your app's target settings. Under the Build Phases tab, expand the Link Binary With Libraries & Embedded Frameworks section.
  • Check if the PlugNPlay.framework is included in your project. If not then please add the framework again.
2. Adding dependencies

You need to add the following dependencies while including the framework manually:

PayUMoneyCoreSDK

  • Navigate to "CoreSDK" folder & drag PayUMoneyCoreSDK.framework into your existing Xcode project
  • In Xcode, go to your app's target settings. Under the General tab, expand the Embedded Binaries section.
  • Check the PayUMoneyCoreSDK.framework is included or not, If no then add the same

CitrusGraphics

  • Navigate to "Dependencies/CitrusGraphics/Framework/graphics-sdk" folder & drag CitrusGraphics.framework into your existing Xcode project
  • In Xcode, go to your app's target settings. Under the General tab, expand the Embedded Binaries section.
  • Check the CitrusGraphics.framework is included or not, If no then add the same

Kingfisher

  • Navigate to "Dependency/Kingfisher" folder & drag the Kingfisher.xcodeproj into your existing Xcode project
  • Select the target and Navigate to General tab and expand the Embedded Binaries section
  • Ensure that the Kingfisher.framework is included in your project. If not, then please add the same

Integrate PnP SDK using Cocoa Pods

To integrate PlugNPlay into your Xcode project using CocoaPods, specify it as a target in your Podfile:

1. Add following lines to Podfile :

pod 'PayUmoney_PnP'

2. Then, run the following command:

pod install

Open the {Project}.xcworkspace instead of the {Project}.xcodeproj when anything is installed from CocoaPods.

Import the SDK

After installation, you must import the PlugNPlay SDK in your project by adding the following line to the files in which you want to use this framework.

#import <PlugNPlay/PlugNPlay.h>

Calculate Server-Side Hash

The only server side change required while integrating PayUMoney iOS SDK is to generate a hash parameter for both the payment request & response.

A hash is an encrypted value (checksum) that is to be sent by the merchant in a payment request and sent by PayUMoney in the payment response. A hash is used to protect transactions against a “man in the middle” attack.

Hash for Payment Request

hashSequence = key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||salt.
$hash = hash("sha512", $hashSequence);
Note:
A blank udf field is to be used while computing hashSequence, even if a merchant is not passing any udf field in input request.

Hash for Payment Response

responseHashSequence = salt|status||||||udf5|udf4|udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|key
$responseHash = hash("sha512", $responseHashSequence);
Note:
The entire hash logic is built on the assumption 'Salt' is always safe with the merchant. Hence is very important for the merchant to keep the 'Salt' safe by adhering to the best security practices. For eg: Merchant should always compute from the server side and never from the client side, should never share the 'Salt & Key' over emails or directly commit on public repositories like Github.

Set Payment Params

To start using the PayUmoney PnP SDK, you need you initialize the SDK by providing details about the customer and the transaction. To initiate the payment, create an object of type ‘PUMTxnParam’ and set all the mandatory parameters as shown below.

PUMTxnParam *txnParam= [[PUMTxnParam alloc] init];
//Set the parameters
txnParam.phone = @"9717410858";
txnParam.email = @"umangarya336@gmail.com";
txnParam.amount = @"123";
txnParam.environment = PUMEnvironmentProduction;
txnParam.firstname = @"Umang";
txnParam.key = @"merchantKey";
txnParam.merchantid = @"MerchantID";
txnParam.txnID = @"txnID123";
txnParam.surl = @"https://www.payumoney.com/mobileapp/payumoney/success.php";
txnParam.furl = @"https://www.payumoney.com/mobileapp/payumoney/failure.php";
txnParam.productInfo = @"iPhone7";
txnParam.udf1 = @"userDefinedField1";
txnParam.udf2 = @"userDefinedField2";
txnParam.udf3 = @"userDefinedField3";
txnParam.udf4 = @"userDefinedField4";
txnParam.udf5 = @"userDefinedField5";
txnParam.udf6 = @"userDefinedField6";
txnParam.udf7 = @"userDefinedField7";
txnParam.udf8 = @"userDefinedField8";
txnParam.udf9 = @"userDefinedField9";
txnParam.udf10 = @"userDefinedField10";
txnParam.hashValue = @"HashFromServer";

Details of these parameters are explained in the 'Transaction Parameters' Section.

The 'udf' fields stand for 'user defined field'. These fields are provided to pass custom information about the transaction to PayUmoney. You may pass up to 5 UDF fields. You must pass an empty string value here if you do not want to use it. The fields 'udf6 - udf10' are non-mandatory. You may not pass any value in this field if there is no need.

Start the Payment Flow

Invoke the following function to open the checkout page. The Customer will now interact with PayUmoney screens till the transaction is complete.

[PlugNPlay presentPaymentViewControllerWithTxnParams:txnParam
onViewController:viewController withCompletionBlock:^(NSDictionary *paymentResponse, NSError
*error, id extraParam) { //Response callback }];

The details of the objects passed as input to the function are described below:

Sl No. Input Object Description
1. txnParam Object of PUMTxnParam after setting all the transaction parameters including the server-computed hash value.
2. viewController Object of parent viewController Completion Block

The callback for this method is passed the following data objects:

1. paymentResponse The response of a transaction will be given as a call back to this block after payment failure or success.
2. error Any errors will be given as a callback response to this object. An error may occur if:
  • Transaction parameters are invalid
  • User presses back button on the webview
  • Call to the payment API fails
3. extraParam Reserved for future use

The checkout UI will be displayed similar to the screenshots below:

Logged in user screen
Guest user screen
Logged in user screen
Guest user screen

Response Handling

The PayUmoney SDK provides default response handling and associated screens thereby removing the need for you to create your own screens or handle the response from the PayUmoney server.

The default screens are illustrated in the screenshots below:

Logged in user screen
Guest user screen

The payment response itself is given as a callback to the same function which triggered the payment request.

[PlugNPlay presentPaymentViewControllerWithTxnParams:txnParam onViewController:self
withCompletionBlock:^(NSDictionary *paymentResponse, NSError *error, id extraParam) {
//Response callback }];

Handle the callback on paymentResponse object for the payment response.

If you’d like to create your own screens to display the transaction response, you can disable the payment completion screen using the setDisableCompletionScreen as shown below:

[PlugNPlay setDisableCompletionScreen:YES];

The default value of the setDisableCompletionScreen is NO.

Change look and feel of the Checkout Screens

The PayUmoney Plug n Play SDK provides convenient methods to change the look and feel of the checkout screens to match the look and feel of your own app. The SDK allows you to change the color and text for the following UI elements:

  • Button text on the result screen
  • Page Title
  • Color combinations (when a theme is not provided)

To customize the UI elements, please use the appropriate methods listed below:

To set Button color:

[PlugNPlay setButtonColor:[UIColor redColor]];

To set Button Text color:

[PlugNPlay setButtonTextColor:[UIColor yellowColor]];

To set Top bar color:

[PlugNPlay setTopBarColor:[UIColor blueColor]];

To set Top bar title color:

[PlugNPlay setTopTitleTextColor:[UIColor orangeColor]];

To set merchant Display Name:

[PlugNPlay setMerchantDisplayName:@"Merchant Name"];

Manipulating the Payment options in PNP SDK

All of the payment options, Wallet, Cards, Net banking, are enabled for a user by default. You can configure to disable any of the payment options as shown below.

Disable Cards

[PlugNPlay setDisableCards:YES];

Disable Netbanking

[PlugNPlay setDisableNetbanking:YES];

Disable Wallet

[PlugNPlay setDisableWallet:YES];

Disable Completion Screen

[PlugNPlay setDisableCompletionScreen:YES];
Note:
These options will only have an effect if the payment method is enabled for your account from PayUmoney server. If disabled, the method will not have any effect.

Testing the Integration

During integration, test the PayUmoney SDK integration by setting the SDK in the test mode. For using SDK in test mode you need to follow the below-mentioned steps.

  • Set the environment parameter of the txnParam object when initializing the SDK to PUMEnvironmentTest
  • Send the SURL/FURL, MerchantId and key accordingly for test and live mode. Goto ‘Parameters Section’ to know what this means.

Transaction Parameters

This section contains the details about different request & response parameters to used while transacting using PayUmoney.

REQUEST PARAMETERS

Sl No. Parameter Mandatory Description
1. environment Yes The environment variable controls which environment the PayUmoney SDK is working in. During integration, it is recommended to test the integration in the test mode. The environment parameter has two possible values: PUMEnvironmentProduction – Production environment mode PUMEnvironmentTest – Test environment mode
2. surl Yes Success URL
3. furl Yes Failure URL
4. amount Yes Transaction Amount
5. key Yes Merchant Key ;available from the PayUmoney Dashboard
6. merchantid Yes Merchant Id; available from the PayUmoney Dashboard
7. txnid Yes Unique transaction id to be passed by you
8. delegate Yes Pass the object that will receive callback here.Typically ‘Self’.
9. firstname Yes Address of the payer.
10. productinfo Yes Information Regarding Product. 255 Char Max
11. email Yes Email Id of the payer
12. phone Yes Mobile No of the payer
13. udf1 Yes User Defined Field
14. udf2 Yes User Defined Field
15. udf3 Yes User Defined Field
16. udf4 Yes User Defined Field
17. udf5 Yes User Defined Field
18. udf6 No User Defined Field
19. udf7 No User Defined Field
20. udf8 No User Defined Field
21. udf9 No User Defined Field
22. udf10 No User Defined Field

RESPONSE PARAMETERS

Sl No. Parameter Descripiton
1. status Transaction Status. (Described in detail in the Transaction Status section)
2. firstname First name of the Payer
3. amount Transaction Amount
4. txnid Unique Transaction Id passed by you in request.
5. hash Response Hash
6. key Merchant key
7. productinfo Product Info passed in request
8. email Email Id of the payer
9. payuMoneyId The PayUmoney transaction id
10. mode Payment Mode in:
  • Netbanking (NB)
  • Debit Card(DC)
  • Credit Card(CC)

Transaction Status

A transaction can have several different statuses as explained in the table below.

No. Status Description
1. Not Started The transaction has not been started yet.
2. Initiated The transaction has been started but not completed.
3. Money With PayUMoney The transaction was successful and the transaction amount is with PayUMoney.
4. Under Dispute A dispute for the transaction has been raised.
5. Refunded The entire amount of the transaction has been refunded.
6. Partially Refunded A part of the amount of the transaction has been refunded.
7. Bounced Incomplete or no details provided at PayUMoney payment page.
8. Failed The transaction didn't complete due to a failure.
9. Settlement in Process Settlement for the transaction is in process.
10. Completed The transaction is settled and complete.

Sample App

PayUMoney recommends that you download the sample and test it out to understand the integration and payment flow. Check it out here:
https://github.com/payu-intrepos/PayUMoney-IOS-SDK/tree/master/PlugNPlay/Objective-C%20SampleApp