In App Sdk

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

Fill out the form (opens in a new tab) to request the Tap to Pay entitlement.
If you do not have an organizational Apple Developer account, visit Apple Developer Enrollment (opens in a new tab) to enroll.
After receiving the entitlement, follow Apple’s official instructions (opens in a new tab) to configure your Xcode project to support Tap to Pay on iPhone.

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

User should be onboarded on iPOSpays sandbox (UAT) environment as a merchant and have a valid Tap to Pay on iPhone 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.

Install Xcode:

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

Accept Terms:

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

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.

import IposgoSDK

Initiate the Reader Variable:

var readerInstance = IposgoReader()

Invoke the Delegate:

override func viewDidLoad() {
    super.viewDidLoad()
    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:

readerInstance.downloadParameter(tpn:"123456789012")

Parameter Name

Description	Sample Value
tpn	Unique 12-digit code

Perform Transactions

Supported Transaction Types

SALE
REFUND
VOID
PRE-AUTH
TICKET

REFUND and PRE-AUTH transactions operate the same as SALE transactions. The only difference is the transaction type parameter, which needs to be adjusted accordingly.

Initiate Transactions

Use the startTransaction method for transactions:

API Call

Sale

readerInstance.startTransaction(
    amount: "10.00",
    tipAmount: "1.00",
    currenyCode: .usd,
    tranType: .SALE
)

Refund

readerInstance.startTransaction(
    amount: "10.00",
    currenyCode: .usd,
    tranType: .REFUND
)

Pre-auth

readerInstance.startTransaction(
    amount: "10.00",
    currenyCode: .usd,
    tranType: .PRE_AUTH
)

Transaction Parameters

Parameters Name	Type	Description	Sample
amount	String	Transaction amount	$10.00
tipAmount	String	Tip amount (optional)	$1.00
currencyCode	Enum	Transaction currency	.usd
tranType	Enum	Transaction type	.SALE
rrn	String	Unique transaction ID	123536758578

Ticket Transactions

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

API Call

readerInstance.startTicket(amount: string?, tipAmount: string?,currentCode: CurrencyCode, rrn: string?)

Request Parameters

Parameters Name	Type	Description	Sample
amount	String	Transaction requested amount	$10.00
tipAmount	String	Tip amount (optional)	$1.00
currencyCode	Enum	Currency (choose from CurrencyCode enum)	.usd
rrn	String	Unique identifier to track the transaction from TXN response	123536758578

Void Transactions

Use startVoid for voiding a transaction:

API Call

readerInstance.startVoid(rrn: "123536758578")

Parameter Name

Description	Sample Value
rrn	Unique transaction ID

Batch Settlement

Use startBatchSettlement for batch settlements:

API Call Example

readerInstance.startBatchSettlement()

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

Sample Responses

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

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

Response Details

Field	Type	Description	Sample
RefId *	string	Transaction reference ID is a unique ID tagged with each transaction	688041066395
AuthCode *	string	It’s a Unique code.Its TXN hash key	83398129492534106720240723110923
PNRef *	string	RRN number to track the txn details	400907500270
TransNum *	string	Invoice number	4
ResultCode *	string	For success TXN code = 0 0r 00 If code != 0 then is considered as failure TXN	00
Message *	string	Message from Processor for transaction	APPROVED
RespMsg *	string	Message from Processor for transaction	APPROVAL DSC380
PaymentType *	string	Credit / Debit	credit
CardType *	string	Its Card type	VISA, MASTERCARD
Amount *	string	Transaction base amount	10.00
Tip	string	if tip enable tip amount will return	$1.00
TaxCity	string	if local tax enable local tax amount will along with local fee is applicable	2.00
Tax1Label	string	Label given for tax 1 in portal configuration edit param	Local Tax
TaxState	string	if state tax enable local tax amount will along with state fee is applicable	1.00
Tax2Label	string	Label given for tax 2 in portal configuration edit param	State Tax
Fee	string	Fee amount which enable in portal configuration edit param	0.40
FeeLabel	string	Fee label which enable in portal configuration edit param	Custom Fee
BaseAmount *	string	Transaction base amount	10.00
BatchNum *	string	Batch number for particular transaction	121
AcntLast4 *	string	Last four digits for your txn	5859
AcntFirst4	string	first four digits for your txn	3530
TotalAmt *	string	Total amount	13.40
TaxAmount	string	Total of tax amount	2.00
RespCode *	string	For success TXN code = 0 0r 00 If code != 0 then is considered as failure TXN	00
RRN *	string	Unique id to track transaction	400907500270
TraceNum *	string	Invoice number of transaction	4
HostTxnId *	string	Transaction hash key	123456789012345
txnId *	string	Unique id to track transaction	00000433772392582420240109012159
TxnType *	string	Transaction type	1
EntryType *	string	Entry type	tap-on-phone
txnLabel *	string	Transaction title	sale
networkMode	string	Mode of connected device network	WIFI
DateTime *	string	Timestamp	20240222173537
iPOSToken *	string	It’s a Unique code.Its TXN hash key	CE268D77935FDBF3F9C72E7
HostResponseCode *	string	For success TXN code = 0 0r 00 If code != 0 then is considered as failure TXN	00
HostResponseMessage *	string	Message from Processor for transaction	APPROVAL DSC380

Deep Linking Hosted Payment Page