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
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.
- 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.
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 Name | Description |
---|---|
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
// 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 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 |
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.
// 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.
// 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.
// 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 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 |
tranType * | Enum | Transaction 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 Name | Type | Description | Sample |
---|---|---|---|
rrn * | String | Unique transaction ID | |
tranType * | Enum | Transaction 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 Name | Type | Description | Sample |
---|---|---|---|
txRefNo * | String | The transaction reference number can be obtained from the callback delegate of the transaction API call | 025212939898 |
txnTimeStamp * | String | The 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
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 |
Transaction Types and Currency Codes Enums
public enum TransType: Int {
case SALE = 1
case VOID = 2
case REFUND = 3
case PRE_AUTH = 4
case TICKET = 5
case SETTLEMENT = 7
}
public enum CurrencyCode : String {
case usd = "840"
}