Checkout workflow for iOS

The Checkout workflow for iOS is as follows:

1. The Merchant iOS App is integrated with Payabbhi iOS SDK.

   • This generally means that your App includes Payabbhi iOS SDK and implements PaymentCallback to receive payment response on successful Payment.

2. The customer clicks the Pay button in your App.

3. This opens Payabbhi Checkout where the customer is able to provide his Card details or choose other payment options like NetBanking, UPI, Wallets etc.

4. Payabbhi Checkout sends the payment details directly to Payabbhi Servers from the customer’s device (if it passes basic validation).

5. Once the payment is successfully completed on the customer’s device, Checkout will return the signed payment response via callback to onPaymentSuccess

6. Your mobile App should typically pass the signed payment response to your mobile backend (server-side code) for further processing.

7. Your Server-side code validates the signed payment response (typically using the utility function of our Client Library ).

8. After verification, your Mobile Backend (server-side code) communicates with your Mobile App for it to display appropriate success (or failure) message to your customer.

Installation

Requirements

• The Payabbhi iOS SDK is compatible with apps supporting iOS 11 and above.
• Both Swift framework Ver 4.0 onwards and Objective-C are supported.
• XCode 11 onwards.

Using Cocoapods (recommended)

• Add Payabbhi to your Podfile:

pod 'payabbhi-ios'

• Run the following command:

$ pod install

• Open the <Project>.xcworkspace instead of the <Project>.xcodeproj when anything is installed from CocoaPods.

Manual

• Download from iOS SDK Releases

• Naming convention : Payabbhi-iOS-<Swift-Version>-<Payabbhi-SDK-Version>.tar.gz

e.g. Payabbhi-iOS-40-1.0.3.tar.gz denotes Payabbhi iOS SDK v1.0.3 built in Swift ver 4.0

So if you use Swift 4.0, you should download Payabbhi-iOS-40-<current-version>.tar.gz

• Untar Payabbhi-iOS-*.tar.gz

• In Xcode, open the application which you want to integrate with Payabbhi iOS SDK. Go to File and select Add Files to "your-project".

• Select Payabbhi.framework from directory where you unzipped.

• Make sure to check the Copy items if needed checkbox in destination and select Create folder references radio button in Added folders while adding the framework.

• Choose Target → Project Name → General and add Payabbhi.framework to Frameworks, Libraries and Embedded Content (if not present).

• Make sure to change Embed status from Do not Embed to Embed & Sign.

• For Objective-C : Select Target → Project Name → Build Settings - Select All and Combined. Under Build Options set Always Embed Swift Standard Libraries option to Yes.

NOTE: Older naming convention : Payabbhi-iOS-<XCode-Version>-<Payabbhi-SDK-Version>.tar.gz was used on or before Payabbhi iOS SDK v1.0.2 release.

Using the SDK - Swift

Make sure you have signed up for your Payabbhi Account and downloaded the API keys from the Portal.

Step 1.1 : Instantiate Payabbhi with access_id.

While instantiating you also need to pass the delegate that implements PaymentCallback protocol.

ViewController.swift

import Payabbhi

class ViewController: UIViewController, PaymentCallback {
  var payabbhi : Payabbhi!

  override func viewDidLoad() {
    super.viewDidLoad()
    ..
    ..
    /* Instantiate Payabbhi */
    payabbhi = Payabbhi(accessID: "<your_access_id>", delegate: self)
  }

}

Step 1.2 : Implement PaymentCallback in your view controller.

Your ViewController needs to implement PaymentCallback to receive callbacks for the Payment response and error.

ViewController.swift

class ViewController: UIViewController, PaymentCallback {
..
..

func onPaymentSuccess(paymentResponse: PaymentResponse) {
  /**
   * Add your logic here to process the Payment response on successful payment
   * It is expected that you would pass the Payment response
   * to your Mobile Backend (Server-side code) for further processing
   */
}

func onPaymentError(code: Int, message: String) {
   /**
   * Add your logic here to handle scenarios where the Checkout did not result in a successful Payment
   */
}

Step 2: Initiate payment using Payabbhi

After instantiating Payabbhi, you will need to pass the Checkout Configuration options as a Dictionary. The configuration options in checkout.js are also applicable to iOS.

It is expected that the Mobile Backend (Server-side code) would create an Order using Payabbhi Order API and pass the unique order_id to the App. This unique order_id should be passed by your App to Payabbhi to initiate Checkout.

ViewController.swift

let options = [
//order_id is a unique identifier of the Order created using Payabbhi Order API
"order_id": "unique_order_id",
// Order amount in paisa (e.g., 5000 paisa = Rs 50.00) */
"amount": 5000,
"currency": "INR",
"name":"Merchant Name",
"prefill": [
    "name":"Bruce Wayne",
    "email": "bruce@wayneinc.com",
    "contact": "9999999999999"
  ]
] as [String : Any]


let err = payabbhi.open(options: options)
if err != nil {
  print("Error opening payabbhi checkout: ",err?.getCode(),err?.getMessage())
  /**
  * Add logic here to handle any error while opening the checkout form.
  */
}

TIP: You can generate a unique order_id using curl and then pass it as param:

curl https://payabbhi.com/api/v1/orders \
  -u access_id:secret_key \
  -d amount=5000 \
  -d merchant_order_id=ordRefNo123456 \
  -d currency=INR

payabbhi.open() displays the Payabbhi Checkout form where the customer is able to provide his Card details or choose other payment options like NetBanking,UPI, Wallets etc.

Step 3.1 : onPaymentSuccess callback

Once the payment is successfully completed on the customer’s device, Payabbhi will return the signed Payment response via callback to onPaymentSuccess

ViewController.swift

func onPaymentSuccess(paymentResponse: PaymentResponse) {

  paymentResponse.getPaymentID()
  paymentResponse.getOrderID()
  paymentResponse.getPaymentSignature()
  /**
   * Add your logic here to process the Payment response on successful payment
   * It is expected that you would pass the Payment response
   * to your Mobile Backend (Server-side code) for further processing
   */

}

Step 3.2 : onPaymentError callback

Checkout may return an error code via a callback to onPaymentError.

ViewController.swift

func onPaymentError(code: Int, message: String) {
  if (Payabbhi.PAYMENT_CANCELED == code) {
      // Handle scenario when payment is canceled
   }
}

Error Codes

The error codes that may be returned in the onPaymentError method are:

Update for iOS 9 and later

For iOS 9.0 or later, App Transport Security (ATS) is enabled by default. Since this setting requires HTTPS that is not supported by all PSPs and Banks, the following workaround is needed.

Info.plist

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

See here for more information.

Using the SDK - Objective-C

Make sure you have signed up for your Payabbhi Account and downloaded the API keys from the Portal.

Step 1.1 : Instantiate Payabbhi with access_id.

While instantiating you also need to pass the delegate that implements PaymentCallback protocol.

ViewController.m

@import Payabbhi;

@interface ViewController () <PaymentCallback>
@end

@implementation ViewController
  Payabbhi *payabbhi;

  - (void)viewDidLoad {
      [super viewDidLoad];
      ..
      ..

      payabbhi = [[Payabbhi alloc] initWithAccessID: @"<your_access_id>" delegate: self];
  }

@end

Step 1.2 : Implement PaymentCallback in your view controller.

Your ViewController needs to implement PaymentCallback to receive callbacks for the Payment response and error.

ViewController.m

@interface ViewController () <PaymentCallback>
@end

@implementation ViewController
..
..

- (void)onPaymentSuccessWithPaymentResponse:(PaymentResponse *)paymentResponse {
        /**
         * Add your logic here to process the Payment response on successful payment
         * It is expected that you would pass the Payment response
         * to your Mobile Backend (Server-side code) for further processing
         */
}

- (void)onPaymentErrorWithCode:(NSInteger)code message:(NSString *)message {
       /**
       * Add your logic here to handle scenarios where the Checkout did not result in a successful Payment
       */
}

Step 2: Initiate payment using Payabbhi

After instantiating Payabbhi, you will need to pass the Checkout Configuration options as a Dictionary. The configuration options in checkout.js are also applicable to iOS.

It is expected that the Mobile Backend (Server-side code) would create an Order using Payabbhi Order API and pass the unique order_id to the App. This unique order_id should be passed by your App to Payabbhi to initiate Checkout.

ViewController.m

/* Pass your configuration options to Payabbhi Checkout as a NSDictionary */
NSDictionary *options = @{
  /* order_id is a unique identifier of the Order created using Payabbhi Order API */
  @"order_id": @"unique_order_id",
  /* Order amount in paisa (e.g., 5000 paisa = Rs 50.00) */
  @"amount" : @"5000",
  @"currency" : @"INR",
  @"name" : @"Merchant Name",
  @"prefill" : @{
      @"email" : @"bruce@wayneinc.com",
      @"contact" : @"9999999999"
    }
};

PayabbhiError *error = nil;

error = [payabbhi openWithOptions: options];
if (error != nil) {
  NSLog(@"%@", error.getMessage);
  NSLog(@"%ld", (long)error.getCode);
  /**
  * Add logic here to handle any error while opening the Checkout form
  */
}

TIP: You can generate a unique order_id using curl and then pass it as param:

curl https://payabbhi.com/api/v1/orders \
  -u access_id:secret_key \
  -d amount=5000 \
  -d merchant_order_id=ordRefNo123456 \
  -d currency=INR

payabbhi.open() displays the Payabbhi Checkout form where the customer is able to provide his Card details or choose other payment options like NetBanking,UPI, Wallets etc.

Step 3.1 : onPaymentSuccess callback

Once the payment is successfully completed on the customer’s device, Payabbhi will return the signed Payment response via callback to onPaymentSuccess

ViewController.m

- (void)onPaymentSuccessWithPaymentResponse:(PaymentResponse *)paymentResponse {
  paymentResponse.getPaymentID;
  paymentResponse.getOrderID;
  paymentResponse.getPaymentSignature;
  /**
   * Add your logic here to process the Payment response on successful payment
   * It is expected that you would pass the Payment response
   * to your Mobile Backend (Server-side code) for further processing
   */
}

Step 3.2 : onPaymentError callback

Checkout may return an error code via a callback to onPaymentError.

ViewController.m

- (void)onPaymentErrorWithCode:(NSInteger)code message:(NSString *)message {
  if (Payabbhi.PAYMENT_CANCELED == code) {
      // Handle scenario when payment is canceled
   }
}

Refer to Swift section above for Error codes.

Quick Tips

1. 'Unsupported Architectures' error while uploading your app to Appstore

While uploading your app to Appstore, you might get an error related to 'Unsupported Architectures'. This is because our iOS framework distribution includes all possible architectures of the simulators to allow development in any environment. To fix this, we need to remove the unsupported architectures prior to uploading the app on iTunes.

• Create a script file as below
• Save it in the directory where the Payabbhi iOS framework is located
• Run the script
• Remove the script file

These steps may be repeated for each development cycle - code, test and upload - of your App.

#!/bin/sh
## Remove following architectures which are not needed for App store upload
lipo -remove i386 Payabbhi.framework/Payabbhi -output Payabbhi.framework/Payabbhi
lipo -remove x86_64 Payabbhi.framework/Payabbhi -output Payabbhi.framework/Payabbhi
rm Payabbhi.framework/Modules/Payabbhi.swiftmodule/i386.swiftdoc
rm Payabbhi.framework/Modules/Payabbhi.swiftmodule/i386.swiftmodule
rm Payabbhi.framework/Modules/Payabbhi.swiftmodule/x86_64.swiftdoc
rm Payabbhi.framework/Modules/Payabbhi.swiftmodule/x86_64.swiftmodule