Pax D135 - iOS Quickstart

Note: the iOS sdk is currently in external pilot

PAX D135 Integration Overview

The PAX D135 is an ultra-portable and cost-effective mobile device that can serve a wide range of uses.

iOS Demo Application

Step 1: Download Sample Application

Example demo app.

Step 2: Run Sample Application

Please see the sample app to see how to interact with the SDK. The App works as follows:

Ensure the mPOS device has been paired to your phone/tablet via bluetooth.
Launch the app
To connect the app to the device, first click the Scan for Devices button. This will scan for currently paired bluetooth devices.
Once the button is clicked a dialog would open showing a list of currently paired bluetooth devices
Select the mPOS device. This will begin the process of connecting to the device and a loading spinner will be shown. You can observe the log output on the screen as it outputs messages of current progress
Once the connection is complete and successful, one can initiate transactions by typing the amount into the TextField with the default value of 3.14 and clicking one of Sale, Auth, Refund

Using the SDK

Create Role Merchant Credentials

All Finix Device SDK calls require ROLE_MERCHANT credentials. Once created, you can use these credentials across multiple devices as long as the devices are associated to the same Merchant.

curl https://finix.sandbox-payments-api.com/identities/IDuWtgdP9VERb4FiLeYatWy/users \
-H "Content-Type: application/json" \
-H 'Finix-Version: 2022-02-01' \
-u "USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3" \
-d '{}'

HTTP Request

GET https://finix.sandbox-payments-api.com/identiities/:IDENTITY_ID:/users

URL Parameters

Parameter	Description
:IDENTITY_ID:	ID of the `Identity` for the Merchant.

Example Response

{
    "id": "USxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2022-10-10T06:05:08.11Z",
    "updated_at": "2022-10-10T06:05:08.11Z",
    "enabled": true,
    "identity": "IDxxxxxxxxxxxxxxxxxxxxxx",
    "password": "xxxxxxxxxxxxxxxxxxxxxx",
    "role": "ROLE_MERCHANT",
    "tags": {},
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/users/USgymgj1dSkCNxYmZKd9GxQN"
        },
        "applications": {
            "href": "https://finix.sandbox-payments-api.com/applications"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
        }
    }
}

Installation

Add the SDK to your project via Swift Package Manager using:

https://github.com/finix-payments/finix-pax-mpos-ios-sdk

Initialization

Pre-requisites

iOS 17.6 or later
iOS device. Simulator not supported
Add Bluetooth permission in Info.plist using key Privacy - Bluetooth Always Usage Description

To interact with the MPOS device, first initialize the SDK

import PaxMposSDK

let finixClient = FinixClient(config: FinixConfig(
            environment: TEST_ENVIRONMENT,
            credentials: Finix.APICredentials(username: TEST_USERNAME, password: TEST_PASSWORD),
            application: TEST_APPLICATION,
            version: TEST_VERSION,
            merchantId: TEST_MERCHANT_ID,
            mid: TEST_MERCHANT_MID,
            deviceType: .Pax,
            deviceId: "")
)
finixClient.delegate = self
finixClient.interactionDelegate = self

Once initialized, connect to the device. When the device is ready for pairing, it will show an orange light and green light. Once connected, the orange light will disappear and only the green light will stay on.

Scan for devices:

finixClient.startScan()

extension ViewController: FinixDelegate {
    func didDiscoverDevice(_ deviceInfo: DeviceInfo) {
        devices.append(deviceInfo)
    }
}

Connect to device:

finixClient.connectDevice(device.id)

extension ViewController: FinixDelegate {
    func deviceDidConnect(_ deviceInfo: DeviceInfo) {
        connectedDevice = deviceInfo
    }
}

Start Transaction

To start a transaction, first, update the client with the device ID. Then call the function startTransaction(). This will prep the mPOS device to accept card input (swipe, tap, insert). A blue status light will be shown. Once any action is performed with the card the device would show a red light to indicate, the card has been read and to remove it.

finixClient.update(deviceId: TEST_DEVICE_ID)

let transactionAmount = Currency(amount: Int(amountDouble * 100), code: .USD)
finixClient.startTransaction(amount: transactionAmount, type: transactionType) { transferResponse, error in
    Task { @MainActor in
        // Handle using transferResponse and error
    }
}

Referenced Refund

A referenced refund, refunds the amount specified (refund amount) of a particular transaction (transaction id) to the card on file

/// Start a referenced refund
    func startRefund(transactionID: String, amount: Currency, completion: ((RefundResponse?, Error?) -> Void)?) {
        let mainCompletion: (RefundResponse?, Error?) -> Void = { response, error in
            if let error {
                self.logger.error("startRefund failed with error: \(error)")
            }
            
            DispatchQueue.main.async {
                completion?(response, error)
            }
        }
        
        let externalEndpoint = FinixAPIEndpoint.externalEndpoint(config.environment)
        let endPoint = "transfers/\(transactionID)/reversals"
        guard let url = URL(string: endPoint, relativeTo: externalEndpoint) else {
            mainCompletion(nil, FinixError(code: .MalformedRequest, message: "Could not encode path!"))
            return
        }

        guard let request = requestBuilder(url: url, method: .POST, payload: ["refund_amount": amount.amount]) else {
            mainCompletion(nil, FinixError(code: .CannotEncodeParameters, message: "Cannot encode request parameters"))
            return
        }

        finixRequest(request: request) { (response: RefundResponse?, error: Error?) in
            print(response as Any, error as Any)
            mainCompletion(response, error)
        }
    }

Device Unreachable

Add a warning or statement not to exit out of payment application or put the device in sleep mode. If they exit out of the application or put the device in sleep mode, they will likely get the above error.