iOS Deep Linking Integration - Version 2.0

Prerequisites

For Sandbox (UAT) Users should be onboarded on the iPOSpays sandbox(UAT) environment as a merchant and have a valid TPN.

For Production (Live) Users should be onboarded on the iPOSpays production environment as a merchant and have a valid TPN.

Set up Testing Environment

• Install Xcode (opens in a new tab)

Before setting up the testing device

• Use a separate device for testing.

• Only use the credentials given to you throughout the testing process.

• Avoid changing the account during testing.

• Don't change the device's date and time.

• These rules apply only to the testing environment, not production.

Watch This Video for a Visual Walkthrough of the Steps

To Develop iOS Application, Create a new iOS project or use the existing project and configure the below app setup.

Initially, we will use the new TPN. You must accept the Apple Tap-on-Phone Terms and Conditions before proceeding with the Tap-on-Pay transaction.

Supported Devices & Versions

• OS Version Above 16.9
• Tap to Pay on iPhone requires iPhone Xs or later.

Configure the URL Scheme

1. Demo App Setup

2. iPOSgo! Setup

3. Configure the SDK

Install the Applications

The Demo App and iPOSgo! applications are installed via a link, and a Diawi link is created for testing purposes. The following URL is used to obtain the device’s UDID: https://get.udid.io/ (opens in a new tab)

After obtaining the UDID, the source file of the demo application is shared for review and implementation reference.

TPN Register

The TPN register is used to download the parameters to configure the merchant configuration data from the backend application portal.

Watch This Video for a Visual Walkthrough of the Steps

Input Request Parameters:

1. To access the SDK Reader wrapper class, import DeepLinking, and initiate an instance of the class as follows:

import DeepLinking

2. Create a variable to access the methods

var readerInstance = Wrapper()

API CALL

struct RegisterData: Register 
{  
var tpn: String  
var merchantCode: String
} 
 
let payload = RegisterData(tpn: "12345678912", merchantCode: "12345678912")
 
readerInstance.downloadParameter(param: payload)

Parameter Name

Delegate Response and Error Handling

To handle responses and errors from the SDK, implement the DLProtocolV2 delegate methods as shown below:

extension ViewController: DLProtocolV2 {
    
    func didReceiveRespV2Error(err: String?) {
        print(">>>>>>ERROR :", err ?? "")
    }
    
    func didReceiveV2Response(success: URL?) {
        print(">>>>>url", success ?? "")
    }
 
    func didReceive_TransactionResponse(res: String?) {
        print(">>>res", res ?? "")
    }
 
}

Transaction Response Structure

The didReceive_TransactionResponse(res:) method returns the following response, which allows the user to track transaction details:

transactionData: {
  "TPN": "794525543578",
  "TimeStamp": "20250602115852",
  "TXN Ref No": "830266506984"
}

• This response provides essential metadata for the transaction that was just processed.

• It includes:

These values can be used to log, track, or reconcile transactions.

Perform Transactions

This API is used to invoke applications to perform the transaction.

It supports:

• SALE

• REFUND

• PRE AUTH

• TICKET

• VOID

• BATCH SETTLEMENT

Initiate Transactions

Use the deepLink.startTransaction to initiate the transactions.

API Call Examples

The structure and API call method are consistent for Sale, Refund, and Pre Auth transactions. You can use it for all three transaction types.

// Define the PayloadParameter struct
struct TxnData: PayloadParameter {    
    var amount: String
    var tipAmount: String?
    var feeAmount: String?
    var currencyCode: CurrencyCode
    var tranType: TransType
    var showTipScreen: Bool?
    var showBreakUpScreen: Bool?
    var showApprovalScreen: Bool?
}
 
// Payload of saleStruct
let sale = TxnData
        (
          amount: 1, 
          currencyCode: .USD, 
          tranType: .SALE,
          tipAmount: 1.00, //Optional
          feeAmount: 5.00, //Optional
          showTipScreen: true, //Optional
          showBreakUpScreen: true, //Optional
          showApprovalScreen: true //Optional
        )
 
// Start the transaction using this method.
readerInstance.startTransaction(param: sale, delegate: self)

Transaction Example Using Deep Linking V2

Sale Transactions

A Sale transaction is the most common type of payment operation performed. It represents a standard purchase where the customer pays for goods or services using a supported payment method, such as a credit card, debit card, or tap to pay.

Import the payload provided below into your code to perform sale transactions.

// Payload of saleStruct
let sale = TxnData
        (
          amount: 1, 
          currencyCode: .USD, 
          tranType: .SALE,
          tipAmount: 1.00, //Optional
          feeAmount: 5.00, //Optional
          showTipScreen: true, //Optional
          showBreakUpScreen: true, //Optional
          showApprovalScreen: true //Optional
        )
 
// Start the transaction using this method.
readerInstance.startTransaction(param: sale, delegate: self)

Below is the tabular representation of the Sale Struct payload:

Refund Transactions

A standalone Refund transaction is used to return funds to a customer for a previously completed Sale transaction. This type of refund is not linked to the original transaction via the RRN (Retrieval Reference Number). Instead, it is initiated as a separate transaction, typically performed after the batch containing the original sale has been settled.

Refunds are commonly used when:

• A product is returned

• A service is canceled

• An overcharge or billing error needs to be corrected

Because it occurs post-settlement, a standalone refund ensures that the original sale has already been finalized before reversing the amount.

Import the payload provided below into your code to perform sale transactions.

// Refund Transaction
let refund = TxnData(
    amount: "10.00",
    currencyCode: .USD,
    tranType: .REFUND,
    showApprovalScreen: true
)
 
// Start the transaction using this method.
readerInstance.startTransaction(param: refund, delegate: self)

Pre Auth Transactions

A Pre-Authorization (Pre-Auth) transaction is used to place a temporary hold on a customer’s funds without immediately capturing the payment. This is commonly used in industries such as hospitality, car rentals, or services where the final amount may vary at checkout.

The transaction must later be completed using a Ticket transaction, where the final amount (including tips, fees, or taxes) is captured.

Import the payload provided below into your code to perform Pre Auth transactions.

// Pre Auth Transaction
let preAuth = TxnData(
    amount: "10.00",
    currencyCode: .USD,
    tranType: .PRE_AUTH,
    showApprovalScreen: true
)
 
// Start the transaction using this method.
readerInstance.startTransaction(param: preAuth, delegate: self)

Ticket Transactions

A Ticket transaction is used to finalize and capture a previously initiated Pre-Authorization (Pre-Auth). Once the goods or services have been delivered and the final amount is confirmed, the merchant uses the Ticket function to complete the payment.

To perform a Ticket transaction, the RRN (Retrieval Reference Number) from the original Pre-Auth transaction is required. This allows the system to locate and complete the correct authorization.

Import the payload provided below into your code to perform Ticket transactions.

// Define the Ticket struct
struct TicketTxnData: TicketPayloadParameter {
    var amount: String?
    var tipAmount: String?
    var feeAmount: String?
    var currencyCode: CurrencyCode
    var tranType: TransType
    var showTipScreen: Bool?
    var showBreakUpScreen: Bool?
    var showApprovalScreen: Bool?
    var rrn: String
}
 
// Payload of Ticket
let ticket = TicketTxnData
      (  
        currencyCode: .USD, 
        tranType: .TICKET,
        amount: 10.00, //Optional
        tipAmount: 1.00, //Optional
        feeAmount: 1.00, //Optional
        showTipScreen: false, //Optional
        showBreakUpScreen: true, //Optional
        showApprovalScreen: false, //Optional
        rrn: "123445667788"
      )
 
// Start the transaction using this method.
readerInstance.startTicket(params: ticket, delegate: self)

Tabular Representation of the Ticket Payload

Void Transactions

A Void transaction is used to cancel a sale or refund before it has been settled. Unlike a refund, which returns funds after a transaction has been finalized, a void stops the transaction from completing and prevents it from appearing in the customer’s bank account.

To void a specific transaction, the RRN (Retrieval Reference Number) of the original sale or refund is required. This ensures the app targets and cancels the correct transaction before it is submitted for settlement.

Import the payload provided below into your code to void a transaction.

// MARK: - PayloadParameter [Void]
struct VoidTxnData: VoidPayloadParameter {
    var rrn: String,          // Reference Retrieval Number
    var tranType: TransType,  // Transaction Type
    var showApprovalScreen: Bool? //Optional
}
 
let void = VoidTxnData(
    rrn: "502213502779",      // Sample RRN
    tranType: .VOID,         // Void transaction type
    showApprovalScreen: true
)
 
// Start the Void transaction using this method.
readerInstance.startVoid(params: void, delegate: self)

Parameter Name

Batch Settlement

Batch Settlement is the process of finalizing and submitting all approved transactions collected over a period (typically a day) to the payment processor for funding. Once a batch is settled, the transactions are sent for clearing, and the merchant’s bank account is credited accordingly.

Use startBatchSettlement for batch settlements:

API Call Example

deepLink.startBatchSettlement( delegate: self)

{
  "transaction_title": "settlements",
  "Tpn": "794524937054",
  "transaction_type": 7,
  "batch_no": 243,
  "timeStamp": "20241219114620",
  "transaction_id": "84566476174593705420241219114620",
  "status": "BATCH SETTLED",
  "statusCode": "00"
}

Sample Responses

{
  "Spin_Response": {
    "RefId": "688041066395",
    "AuthCode": "DSC380",
    "PNRef": "400907500270",
    "TransNum": "4",
    "ResultCode": "0",
    "Message": "APPROVED",
    "RespMsg": "APPROVAL DSC380",
    "PaymentType": "credit",
    "ExtData": {
      "Amount": "10.00",
      "Tip": "1.00",
      "Fee": "0.40",
      "BatchNum": "121",
      "AcntLast4": "5859",
      "AcntFirst4": "3530",
      "FeeLabel": "Custom Fee",
      "BaseAmount": "10.00",
      "TaxCity": "1.00",
      "Tax1Label": "Local Tax",
      "TaxState": "1.00",
      "Tax2Label": "State Tax",
      "RespCode": "00",
      "RRN": "400907500270",
      "TraceNum": "4",
      "HostTxnId": "123456789012345",
      "txnId": "00000433772392582420240109012159",
      "TxnType": "1",
      "EntryType": "tap-on-phone",
      "TotalAmt": "13.40",
      "TaxAmount": "2.00",
      "txnLabel": "Sale",
      "networkMode": "WIFI",
      "DateTime": "20240222173537"
    },
    "iPOSToken": "CE268D77935FDBF3F9C72E8894A1F410B3A2856F37999A88F347B002BB5E3AD7",
    "HostResponseCode": "00",
    "HostResponseMessage": "APPROVAL DSC380"
  }
}

 
{
  "transaction_title": "settlements",
  "Tpn": "794524937054",
  "transaction_type": 7,
  "batch_no": 243,
  "timeStamp": "20241219114620",
  "transaction_id": "84566476174593705420241219114620",
  "status": "BATCH SETTLED",
  "statusCode": "00"
}

Transaction Response Details

Support

Email us directly at devsupport@denovosystem.com with any questions or suggestions.