Merge branch 'master' of https://github.com/PaystackHQ/paystack-ios

Author: ibrahimlawal

GUIDE.md

@@ -2,28 +2,21 @@
 
 If you want to build a mobile app like [Afro](http://www.getafrocab.com) and enable people to make purchases directly in your app, our iOS and [Android](https://github.com/PaystackHQ/paystack-android) libraries can help.
 
-Accepting payments in your app involves 4 steps, which we'll cover in this guide:
+Accepting payments in your app after collecting card information can be acieved in either of two ways, which we'll cover in this guide. The `authorization code` from either option can be used on your server in future to charge the cards.
 
-- Collecting credit card information from your customer
-- Converting the credit card information to a _**single-use**_ token
-- Sending this token to your server to create a charge which provides an authorizaton code if successful
-- Using the returned authorization code to make future charge requests
+#### Option 1 - Charge the card directly from App
+- Charging the credit card and get the transaction `reference`
+- Verifying the transaction on your server which provides an `authorizaton code` if successful
 
-## Getting Started
-
-### Step 1: Install the library
-
-#### Using [CocoaPods](https://cocoapods.org/)
-
-We recommend using [CocoaPods](https://cocoapods.org/) to install the Paystack iOS library, since it makes it easy to keep your app's dependencies up to date.
-
-If you haven't set up Cocoapods before, their site has installation instructions. Then, add pod 'Paystack' to your Podfile, and run pod install.
+or
 
-(Don't forget to use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on out.)
+#### Option 2 - Tokenize on App, charge on server
+- Converting the credit card information to a _**single-use**_ `token`
+- Sending this token to your server to create a charge which provides an `authorizaton code` if successful
 
-#### Using Carthage
+## Getting Started
 
-We also support installing our SDK using Carthage. You can simply add github "paystackhq/paystack-ios" to your Cartfile, and follow the Carthage installation instructions.
+### Step 1: Install the library
 
 #### Manual installation
 
@@ -37,6 +30,18 @@ We also publish our SDK as a static framework that you can copy directly into yo
 - Click 'Add'.
 - In your project settings, go to the "Build Settings" tab, and make sure -ObjC is present under "Other Linker Flags".
 
+#### Using [CocoaPods](https://cocoapods.org/)
+
+We recommend using [CocoaPods](https://cocoapods.org/) to install the Paystack iOS library, since it makes it easy to keep your app's dependencies up to date.
+
+If you haven't set up Cocoapods before, their site has installation instructions. Then, add pod 'Paystack' to your Podfile, and run pod install.
+
+(Don't forget to use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on out.)
+
+#### Using Carthage
+
+We also support installing our SDK using Carthage. You can simply add github "paystackhq/paystack-ios" to your Cartfile, and follow the Carthage installation instructions.
+
 ### Step 2: Configure API keys
 
 First, you'll want to configure Paystack with your publishable API key. We recommend doing this in your `AppDelegate`'s `application:didFinishLaunchingWithOptions:` method so that it'll be set for the entire lifecycle of your app.
@@ -153,19 +158,133 @@ func paymentCardTextFieldDidChange(textField: PSTCKPaymentCardTextField) {
 
 #### Building your own form
 
-If you build your own payment form, you'll need to collect at least your customers' card numbers, CVC and expiration dates.
+If you build your own payment form, you'll need to collect at least your customers' card numbers, CVC and expiration dates. 
+
+### Step 4: Assembling Card information into `PSTCKCardParams`
+
+If you're using `PSTCKPaymentCardTextField`, simply call its `cardParams` property to get the assembled card data.
+
+```Swift
+let cardParams = paymentTextField.cardParams as PSTCKCardParams
+```
+
+```Objective-C
+PSTCKCardParams cardParams = [paymentTextField cardParams];
+```
+
+If you are using your own form, you can assemble the data into an `PSTCKCardParams` object thus:
+
+```Swift
+let cardParams = PSTCKCardParams.init();
+
+// then set parameters thus from card
+cardParams.number = card.number
+cardParams.cvc = card.cvc
+cardParams.expYear = card.expYear
+cardParams.expMonth = card.expMonth
+
+// or directly
+cardParams.number = "2963781976222"
+cardParams.cvc = "289"
+cardParams.expYear = 2018
+cardParams.expMonth = 9
+```
+
+```Objective-C
+PSTCKCardParams cardParams = [[PSTCKCardParams alloc] init];
+
+// then set parameters thus from card
+cardParams.number = [card number];
+cardParams.cvc = [card cvc];
+cardParams.expYear = [card expYear];
+cardParams.expMonth = [card expMonth];
+
+// or directly
+cardParams.number = "2963781976222";
+cardParams.cvc = "289";
+cardParams.expYear = 2018;
+cardParams.expMonth = 9;
+```
+
+### Step 4: Getting payments
+
+Our libraries shoulder the burden of PCI compliance by helping you avoid the need to send card data directly to your server. Instead, our libraries send credit card data directly to our servers, where we can charge them or create tokens which you charge on your server.
+
+
+#### Step 4 Option 1: Charge Card
+
+If you choose the `chargeCard` route, we charge cards you send using parameters provided in your `PSTCKTransactionParams`. Assemble Transaction parameters into `PSTCKTransactionParams`, and send them along with the `cardParams` to get a charge.
+
+```Swift
+@IBAction func charge(sender: UIButton) {
+    // cardParams already fetched from our view or assembled by you
+    let transactionParams = PSTCKTransactionParams.init();
 
-### Step 4: Creating Tokens
+    transactionParams.amount = 1390;
+    transactionParams.metadata  = "{\"custom_fields\":[{\"display_name\":\"Via\",\"variable_name\":\"via\",\"value\":\"iOS\"}]}";
+    transactionParams.email = "e@ma.il";
 
-Our libraries shoulder the burden of PCI compliance by helping you avoid the need to send card data directly to your server. Instead, our libraries send credit card data directly to our servers, where we can convert them to tokens. You should charge these tokens later in your server-side code to get an authorization code.
+    // check https://developers.paystack.co/docs/split-payments-overview for details on how these work
+    // transactionParams.subaccount  = "ACCT_80d907euhish8d";
+    // transactionParams.bearer  = "subaccount";
+    // transactionParams.transaction_charge  = 280;
 
-#### Using `PSTCKCardParams`
+    // if a reference is not supplied, we will give one
+    // transactionParams.reference = "ChargedFromiOSSDK@"
 
-If you're using `PSTCKPaymentCardTextField` or your own form, you can assemble the data into an `PSTCKCardParams` object. Once you've collected the card number, expiration, and CVC, package them up in an `PSTCKCardParams` object and invoke the `createTokenWithCard:` method on the `PSTCKAPIClient` class, instructing the library to send off the credit card data to Paystack and return a token.
+    PSTCKAPIClient.shared().chargeCard(cardParams, forTransaction: transactionParams, on: viewController, 
+               didEndWithError: { (error) -> Void in
+                handleError(error)
+            }, didRequestValidation: { (reference) -> Void in
+                // an OTP was requested, transaction has not yet succeeded
+            }, didTransactionSuccess: { (reference) -> Void in
+                // transaction may have succeeded, please verify on server
+        })
+}
+```
+
+```Objective-C
+- (IBAction)charge:(UIButton *)sender {
+    // cardParams already fetched from our view or assembled by you
+    
+    PSTCKTransactionParams transactionParams = [[PSTCKTransactionParams alloc] init];
+
+    transactionParams.amount = 1390;
+    transactionParams.metadata  = @"{\"custom_fields\":[{\"display_name\":\"Via\",\"variable_name\":\"via\",\"value\":\"iOS\"}]}";
+    transactionParams.email = @"e@ma.il";
+
+    // check https://developers.paystack.co/docs/split-payments-overview for details on how these work
+    // transactionParams.subaccount  = @"ACCT_80d907euhish8d";
+    // transactionParams.bearer  = @"subaccount";
+    // transactionParams.transaction_charge  = 280;
+
+    // if a reference is not supplied, we will give one
+    // transactionParams.reference = "ChargedFromiOSSDK@"
+
+    [[PSTCKAPIClient sharedClient] chargeCard:cardParams
+                               forTransaction:transactionParams
+                                           on: viewController, 
+                              didEndWithError:^(NSError *error){
+                                                [self handleError:error];
+                                            }
+                         didRequestValidation: ^(NSString *reference){
+                                                // an OTP was requested, transaction has not yet succeeded
+                                            }
+                        didTransactionSuccess: ^(NSString *reference){
+                                                // transaction may have succeeded, please verify on server
+      }];
+
+}
+```
+
+#### Step 4 Option 2: Using Tokens
+
+If you choose the `createToken` route, we convert cards sent to tokens. You should charge these tokens later in your server-side code to get an authorization code.
 
 ```Swift
 @IBAction func save(sender: UIButton) {
-    if let card = paymentTextField.cardParams as? PSTCKCardParams {
+    // cardParams Fetched from our view or built by you
+    if let card = cardParams as? PSTCKCardParams {
         PSTCKAPIClient.sharedClient().createTokenWithCard(card) { (token, error) -> Void in
             if let error = error  {
                 handleError(error)
@@ -180,14 +299,15 @@ If you're using `PSTCKPaymentCardTextField` or your own form, you can assemble t
 
 ```Objective-C
 - (IBAction)save:(UIButton *)sender {
+    // cardParams Fetched from our view or built by you
     [[PSTCKAPIClient sharedClient]
-     createTokenWithCard:self.paymentTextField.cardParams
+     createTokenWithCard:cardParams
      completion:^(PSTCKToken *token, NSError *error) {
          if (error) {
              [self handleError:error];
          } else {
             // call your createBackendChargeWithToken function
-            // A sample is presented in step 5
+            // A sample is presented in step 6
          }
      }];
 }
@@ -197,7 +317,72 @@ In the example above, we're calling `createTokenWithCard:` when a save button is
 
 Handling error messages and showing activity indicators while we're creating the token is up to you.
 
-### Step 5: Sending the token to your server
+### Step 6 Option 1: Sending the reference to your server
+
+The blocks you gave to `chargeCard` will be called whenever Paystack returns with a reference (or error). You'll need to send the reference off to your server so you can verify the transactions.
+
+Here's how it looks:
+
+```Swift
+// ViewController.swift
+
+func verifyCharge(reference: String) {
+    let url = NSURL(string: "https://example.com/verify")!
+    let request = NSMutableURLRequest(URL: url)
+    request.HTTPMethod = "POST"
+    let postBody = "reference=reference"
+    let postData = postBody.dataUsingEncoding(NSUTF8StringEncoding, allowLossyConversion: false)
+    session.uploadTaskWithRequest(request, fromData: postData, completionHandler: { data, response, error in
+        let successfulResponse = (response as? NSHTTPURLResponse)?.statusCode == 200
+        if successfulResponse && error == nil && data != nil{
+            // All was well
+            let newStr = NSString(data: data!, encoding: NSUTF8StringEncoding)
+            print(newStr) // All we did here is log it to the output window
+        } else {
+            if let e=error {
+                print(e.description)
+            } else {
+                // There was no error returned though status code was not 200
+                print("There was an error communicating with your payment backend.")
+                // All we did here is log it to the output window
+            }
+            
+        }
+    }).resume()
+}
+```
+
+```Objective-C
+// ViewController.m
+
+- (void)verifyCharge:(String *)reference
+                           {
+    NSURL *url = [NSURL URLWithString:@"https://example.com/verify"];
+    NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:url];
+    request.HTTPMethod = @"POST";
+    NSString *body     = [NSString stringWithFormat:@"reference=%@", reference];
+    request.HTTPBody   = [body dataUsingEncoding:NSUTF8StringEncoding];
+    NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
+    NSURLSession *session = [NSURLSession sessionWithConfiguration:configuration];
+    NSURLSessionDataTask *task =
+    [session dataTaskWithRequest:request
+               completionHandler:^(NSData *data,
+                                   NSURLResponse *response,
+                                   NSError *error) {
+                   if (error) {
+                       ...
+                   } else {
+                       ...
+                   }
+               }];
+    [task resume];
+}
+
+```
+
+On the server, you just need to implement an endpoint that will accept the parameter: `reference`. Make sure any communication with your server is SSL secured to prevent eavesdropping.
+
+### Step 6 Option 2: Sending the token to your server
 
 The block you gave to `createToken` will be called whenever Paystack returns with a token (or error). You'll need to send the token off to your server so you can, for example, charge the card.
 
@@ -266,16 +451,38 @@ On the server, you just need to implement an endpoint that will accept the param
 
 --------------------
 
-### Step 6: Implement payment on your server
+### Step 6 Option 1: Implement verification on your server
+Verify a charge by calling our REST API. An `authorization_code` will be returned once the card has been charged successfully. You can learn more about our API [here](https://developers.paystack.co/docs/getting-started).
+ 
+ **Endpoint:** GET: https://api.paystack.co/transaction/verify
+ 
+ **Documentation:** https://developers.paystack.co/docs/verify-transaction
+
+ **Parameters:**
+ 
+ - reference - the transaction reference
+
+**Example**
+
+```bash
+   $ curl https://api.paystack.co/transaction/verify/ChargedFromiOSSDK%40 \
+    -H "Authorization: Bearer SECRET_KEY" \
+    -H "Content-Type: application/json" \
+    -X GET
+
+```
+### Step 6 Option 2: Implement payment on your server
 Create a charge by calling our REST API. An `authorization_code` will be returned once the _single-use_ token has been charged successfully. You can learn more about our API [here](https://developers.paystack.co/docs/getting-started).
 
- **Endpoint:** https://api.paystack.co/transaction/charge_token
+ **Endpoint:** POST: https://api.paystack.co/transaction/charge_token
+
+ **Documentation:** https://developers.paystack.co/docs/charge-token
 
  **Parameters:**
 
- - token - the token you want to charge
+ - token - the token you want to charge (required)
+ - reference - unique reference 
  - email  - customer's email address (required)
- - reference - unique reference  (required)
  - amount - Amount in Kobo (required) 
 
 **Example**