In-App SDK Integration

Tap to Pay on iPhone With iPOSgo!

Tap to Pay on iPhone with iPOSgo! is an iOS point-of-sale (POS) application that allows businesses to accept contactless payments directly on iPhones using NFC (Near Field Communication) technology. This eliminates the need for additional hardware, turning compatible iPhones into fully functional payment terminals.


Steps to Obtain the Tap to Pay Entitlement

UI & Marketing Guidelines for Tap to Pay on iPhone

Follow the Human Interface Guidelines for Tap to Pay on iPhone to ensure an optimal user experience and a successful review process with Apple.

You can launch and promote your Tap to Pay on iPhone marketing campaigns using Apple’s messaging templates and design assets. Make sure to adhere to the Tap to Pay on iPhone Marketing Guidelines (opens in a new tab).


Prerequisites

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

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

If you do not have a TPN, contact your ISO or support@dejavoo.io.


Testing Environment Setup

To use the sandbox or UAT environment, you need to create a sandbox Apple account. Learn how (opens in a new tab). After creating the sandbox account, sign out of your Apple account on all testing devices and sign back in with your new sandbox tester account.

  1. Install Xcode:

Create or use an existing iOS project. Configure the app to use the TPN provided.

  1. Accept Terms:

When entering the TPN, Apple’s Tap to Pay on iPhone terms and conditions must be accepted.

  1. Testing Best Practices:

    • Use a separate device for testing.
    • Do not change the account or device date/time during testing.

Supported Devices and Versions

  • Devices: iPhone Xs or later.
  • iOS Version: iOS 16.9 or later. It’s recommended to use the latest version for optimal performance.

Project Setup

Add the Entitlement:

Ensure the Tap to Pay entitlement is added to your project.

Integrate the SDK: Drag and drop the IposgoSDK into your project.

To import the SDK, use the below code

import IposgoSDK

Watch This Video for a Visual Walkthrough of the Steps

Initiate the Reader Variable:

var readerInstance = IposgoReader()

Invoke the Delegate:

Import the delegate before invoking the Reader API. [Refer to the demo app for clarification.]

readerInstance.delegate = self

Use this delegate function to get the response callback:

extension yourVC: IposgoDelegate {
    func didReceiveSuccessData(message: String?, responseDict: [String:Any]?) {
        // Handle successful data
        }
 
    func didReceiveError(error: String?, code: Int?) {
        // Handle errors
    }
}

TPN Registration

Purpose: To download Merchant’s TPN parameters from the backend (iPOSpays).

API Call:

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

Parameter Name

Parameters NameDescription
Tpn Unique 12-digit code
merchantCode Unique code - To Identify the Merchant

Watch This Video for a Visual Walkthrough of the Steps


Perform Transactions

Supported Transaction Types

  • SALE
  • REFUND
  • PRE AUTH
  • TICKET
  • VOID
  • For Sale, Refund, and Pre Auth transactions, ensure that you use the same startTransaction to call their respective APIs.
  • The tranType parameter must be adjusted according to the transaction type

Initiate Transactions

Use the startTransaction method for 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.

Example

Example
// Define the `TxnData` struct
struct TxnData: PayloadParameter {
  var amount: String
  var tipAmount: String?
  var currentCode: CurrencyCode
  var tranType: TransType
  var sms: String?
  var email: String?
}
 
// Example usage for a Sale transaction
let payload = TxnData(
  amount: "10.00",
  tipAmount: "1.00",
  currentCode: .usd,
  tranType: .SALE
)
 
// Start the transaction using the reader instance
readerInstance.startTransaction(param: payload)

Transaction Parameters

Parameters NameTypeDescriptionSample
amount * StringTransaction amount$10.00
tipAmount StringTip amount (optional)$1.00
currencyCode * EnumTransaction currency.usd
tranType * EnumTransaction type.SALE

However, the payload is unique to each transaction type, as demonstrated in the code below.

Sale Transactions

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

Sale
// Example usage for a Sale transaction
let payload = TxnData(
  amount: "10.00",
  tipAmount: "1.00",
  currentCode: .usd,
  tranType: .SALE
)

Watch This Video for a Visual Walkthrough of the Steps

Refund Transactions

Import the payload provided below inside your code to process refunds.

Refund
// Example usage for a Refund transaction
let payload = TxnData(
    amount: "10.00",
    tipAmount:"", // No tip for a refund
    currentCode: .usd,
    tranType: .REFUND
)

Pre Auth Transactions

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

Pre-auth
// Example usage for a Pre Auth transaction
let payload = TxnData(
  amount: "10.00",
  tipAmount: nil,  // No tip for a Pre Auth
 
  currentCode: .usd,
  tranType: .PRE_AUTH
)

Ticket Transactions

To access the TXN API, initiate the API call using the startTicket method of the iposgoReader class.

Transaction Parameters

Parameters NameTypeDescriptionSample
amount * StringTransaction requested amount$10.00
tipAmount StringTip amount (optional)$1.00
currencyCode * EnumCurrency (choose from CurrencyCode enum).usd
rrn * StringUnique identifier to track the transaction from TXN response123536758578
tranType * EnumTransaction type.TICKET

API Call Example

// Define the `TicketTxnData` struct
struct TicketTxnData: TicketPayloadParameter {
  var amount: String
  var tipAmount: String?  // Optional tip amount
  var currentCode: CurrencyCode
  var tranType: TransType
  var sms: String?
  var email: String?
  var rrn: String  // Retrieval Reference Number
}
 
// Example usage for a Ticket transaction
let payload = TicketTxnData(
  amount: "10.00",
  tipAmount: nil,  // No tip amount provided
  currentCode: .usd,
  tranType: .TICKET,
  rrn: "12345678989"
)
 
// Start the ticket transaction using the reader instance
readerInstance.startTicket(param: payload)

Void Transactions

Use startVoid for voiding a transaction:

API Call Example

// Define the `VoidTxnData` struct
struct VoidTxnData: VoidPayloadParameter {
  var rrn: String  // Retrieval Reference Number
  var tranType: TransType
  var sms: String?
  var email: String?
}
 
// Example usage for a Void transaction
let payload = VoidTxnData(
  rrn: "12345678989",  // Reference number for the transaction to void
  tranType: .VOID
)
 
// Start the void transaction using the reader instance
readerInstance.startVoid(param: payload)

Parameter Name

Parameters NameTypeDescriptionSample
rrn * StringUnique transaction ID
tranType * EnumTransaction type.TICKET

Batch Settlement

Use startBatchSettlement for batch settlements:

API Call Example

readerInstance.startBatchSettlement()

Status Check

If a transaction response is not received on your end due to any interruption, you can track the status of the transaction using the status check API method.

Use the reference number and timestamp from the initiated transaction’s callback delegate, and call the method provided below.

struct StatusCheckData: StatusCheckPayload {
  var txRefNo: String
  var txnTimeStamp: String
}
 
let payload = StatusCheckData(txRefNo: "123454646", txnTimeStamp: "200240112212121")
 
readerInstance.startStatusCheckforTXN(param: payload)
Parameters NameTypeDescriptionSample
txRefNo * StringThe transaction reference number can be obtained from the callback delegate of the transaction API call025212939898
txnTimeStamp * StringThe timestamp can be obtained from the callback delegate of the transaction API call.20241219133645

Sample Responses

Transaction Response

{
  "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"
  }
}

Batch Settlement Response

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

Response Details

FieldTypeDescriptionSample
RefId * stringTransaction reference ID is a unique ID tagged with each transaction688041066395
AuthCode * stringIt’s a Unique code.Its TXN hash key83398129492534106720240723110923
PNRef * stringRRN number to track the txn details400907500270
TransNum * stringInvoice number4
ResultCode * stringFor success TXN code = 0 0r 00 If code != 0 then is considered as failure TXN00
Message * stringMessage from Processor for transactionAPPROVED
RespMsg * stringMessage from Processor for transactionAPPROVAL DSC380
PaymentType * stringCredit / Debitcredit
CardType * stringIts Card typeVISA, MASTERCARD
Amount * stringTransaction base amount10.00
Tip stringif tip enable tip amount will return $1.00
TaxCity stringif local tax enable local tax amount will along with local fee is applicable2.00
Tax1Label stringLabel given for tax 1 in portal configuration edit paramLocal Tax
TaxState stringif state tax enable local tax amount will along with state fee is applicable1.00
Tax2Label stringLabel given for tax 2 in portal configuration edit paramState Tax
Fee stringFee amount which enable in portal configuration edit param0.40
FeeLabel stringFee label which enable in portal configuration edit paramCustom Fee
BaseAmount * stringTransaction base amount10.00
BatchNum * stringBatch number for particular transaction121
AcntLast4 * stringLast four digits for your txn5859
AcntFirst4 stringfirst four digits for your txn3530
TotalAmt * stringTotal amount13.40
TaxAmount stringTotal of tax amount2.00
RespCode * stringFor success TXN code = 0 0r 00 If code != 0 then is considered as failure TXN00
RRN * stringUnique id to track transaction400907500270
TraceNum * stringInvoice number of transaction4
HostTxnId * stringTransaction hash key123456789012345
txnId * stringUnique id to track transaction00000433772392582420240109012159
TxnType * stringTransaction type1
EntryType * stringEntry typetap-on-phone
txnLabel * stringTransaction titlesale
networkMode stringMode of connected device networkWIFI
DateTime * stringTimestamp20240222173537
iPOSToken * stringIt’s a Unique code.Its TXN hash keyCE268D77935FDBF3F9C72E7
HostResponseCode * stringFor success TXN code = 0 0r 00 If code != 0 then is considered as failure TXN00
HostResponseMessage * stringMessage from Processor for transactionAPPROVAL DSC380

Transaction Types and Currency Codes Enums

Transaction Types
public enum TransType: Int {
    case SALE = 1
    case VOID = 2
    case REFUND = 3
    case PRE_AUTH = 4
    case TICKET = 5
    case SETTLEMENT = 7
}
currency codes
public enum CurrencyCode : String {
    case usd = "840"
}