Deep linking from your iOS mobile app

You can use deep linking to navigate users from your mobile app to payment screens in the AffiniPay, CPACharge, or LawPay mobile app (the target app). Using these payment screens and an optional AffiniPay card reader or manual entry, your users submit card payment information securely in the target app and then return seamlessly to your mobile app. Your backend system then submits the charge.

To take advantage of deep linking:

Obtain the payment token

1: Set a scheme name to identify your mobile app

To set a scheme name for your mobile app:

  1. In Xcode, select your mobile app project in the sidebar.
  2. Click the Info** tab.
  3. In the URL Types** section, add a URL type and set the identifier and the URL scheme. In the following examples, partnerapp is the scheme name.

You must create the URL that will initiate the deep linking process from your mobile app. Here is an example URL:

ioslawpay://charge?amount=100&publicKey=m_Nz_JZ1wDEoSP7uRTQnIqY&accountName=Operating&demoMode=1&disableCardReader=0&requireCvv=0&requireSwipeCvv=1&trustAccount=0&&requiredPaymentFields=cvv,address1,postal_code&swipeRequiredPaymentFields=cvv,address1,postal_code&continue=partnerapp://

The deep link URL starts with the scheme name for the target app. In this example, ioslawpay is the scheme name and it provides a deep link to the LawPay app.

You must include the required parameters publicKey and continue in the deep link URL.

Required parameters

ParameterTypeDescription
publicKeyStringThe merchant’s public key.
continueStringThe scheme name for your mobile app (partnerapp is used in the examples on this page).

Optional parameters

ParameterTypeDescription
amountStringThe amount to charge, in terms of the currency’s smallest unit. For USD, this is the amount in cents.
accountNameStringThe name of the merchant account.
demoModeStringWhether the transaction is a demo transaction (if set to 1) or live transaction (if set to 0).
disableCardReaderStringWhether the card reader should be disabled and transactions should be manual entry only (if set to 1) or the card reader should be enabled (if set to 0).
requireCvvStringWhether CVV is required for manual transactions (if set to 1) or CVV is not required for manual transactions (if set to 0).
requireSwipeCvvStringWhether CVV is required for swiper transactions (if set to 1) or CVV is not required for swiper transactions (if set to 0).
requiredPaymentFieldsStringWhich fields are required for manual transactions, such as cvv,address1,postal_code.
swipeRequiredPaymentFieldsStringWhich fields are required for swiper transactions, such as cvv,address1,postal_code.
trustAccountStringWhether the account type is Trust (if set to 1) or not (if set to 0).

3: Send the payment token request to the target app

To send the payment request (including the deep link URL) to the target app:

  1. Add the following lines of code to ViewController.swift.

    @IBAction func openapp(_ sender: UIButton) {
         let originalUrlString = "ioslawpay://charge?amount=100&publicKey=m_Nz_JZ1wDEoSP7uRTQnIqY&accountName=Operating&demoMode=1&disableCardReader=0&requireCvv=0&requireSwipeCvv=1&trustAccount=0&&requiredPaymentFields=cvv,address1,postal_code&swipeRequiredPaymentFields=cvv,address1,postal_code&continue=partnerapp://"
         let urlString = originalUrlString.replacingOccurrences(of: "", with: "%20")
         let customURL = URL(string: urlString)
         if UIApplication.shared.canOpenURL(customURL!) {
               if #available(iOS 10.0, *) {
                   UIApplication.shared.open(customURL!, options: [:], completionHandler: nil)
               } else {
                   UIApplication.shared.openURL(customURL!)
               }
           } else {
                 //Print alert here
           }
     }

  2. Add the following lines of code to AppDelegate.swift.

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {​​​​​​​​
      if (options[UIApplication.OpenURLOptionsKey.sourceApplication] as! String == "com.affinipay.IOSLawPay") {​​​​​​​​
       handleResponseFromLawPay(url: url)
      }​​​​​​​​
      return true
    }​​​​​​​​

4: Parse the response

After the payment details are processed, the target app returns the following parameters:

ParameterTypeDescription
successStringWhether tokenization was successful (true) or not (false).
reasonStringWhen the tokenization fails, details are returned, such as “User cancelled the charge” or “The one-time token cannot be created”.
clientDetailsInfoJSON StringWhen a payment token is created, the token ID and the payer details submitted in the target app are returned. Here is an example: {\"id\":\"ONZ-48zBR-SrR1wh3UNcAw\",\"email\":\"abc@affinipay.com\",\"phone\":\"(123) 456-7890\",\"reference\":\"Ref Value\",\"city\":\"Austin\",\"country\":\"US\",\"name\":\"John Doe\",\"address1\":\"A/502 Street Lane\",\"address2\":\"Near Cross Road\",\"postalCode\":\"37701\"}

Add the following code to AppDelegate.swift to parse this data.

func handleResponseFromLawPay(url: URL) {​​​​​​​​
    let queryParams = url.queryParameters
    print("query params: ", queryParams!)
    if queryParams!["success"] == "true" {​​​​​​​​
          showSuccessAlert(oneTimeToken: queryParams!["oneTimeToken"]!)
    }​​​​​​​​
    else if queryParams!["success"] == "true" {​​​​​​​​
          if (queryParams!["reason"] != nil) {​​​​​​​​
              showFailedAlert(errorMessage: queryParams!["reason"]!)
          }​​​​​​​​ else {​​​​​​​​
              showFailedAlert(errorMessage: "Unknown error. Please try again.")
          }​​​​​​​​
    }​​​​​​​​
}​​​​​​​​

func showSuccessAlert(oneTimeToken: String) {​​​​​​​​
    let alert = UIAlertController(title: "Success", message: "One-time-token generated : " + oneTimeToken, preferredStyle: .alert)
    alert.addAction(UIAlertAction(
        title: "Ok",
        style: .cancel,
        handler: {​​​​​​​​ (action) in }​​​​​​​​
    ))
    window?.rootViewController?.present(alert, animated: true, completion: nil)
}​​​​​​​​

func showFailedAlert(errorMessage: String) {​​​​​​​​
    let alert = UIAlertController(title: "Error", message: errorMessage, preferredStyle: .alert)
    alert.addAction(UIAlertAction(
        title: "Ok",
        style: .cancel,
        handler: {​​​​​​​​ (action) in }​​​​​​​​
    ))
    window?.rootViewController?.present(alert, animated: true, completion: nil)
}​​​​​​​​

Submit the charge

To submit the charge:

  1. Hand off the payment token and payment details to your backend server, which is already integrated with AffiniPay.
  2. Create a charge from your backend server.