PAX D135 iOS Quickstart

This guide shows how to build in-person payment flows on iOS using the Finix iOS SDK with the PAX D135 Bluetooth card reader.

Environment Designation

When ordering a PAX D135 your Finix point of contact will have you designate which environment you wish to use it in. Finix will notify you which device serial number corresponds to each environment.

Device Designation

A D135 device can be designated to be used for either Sandbox development or Production transaction processing but not both. We recommend requesting enough devices to utilize in both your Sandbox development and Production testing.

Prerequisites

• Your PAX D135 device is fully charged.
• iOS 18.1 or higher.

Charging the Device

Charge the battery only with PAX-approved power supplies. Using others may damage the product and void the warranty.

Charging time must not exceed 24 hours. If the battery is empty, recharge it fully, then disconnect the device to avoid shortening its life.

Determine Which Type of Integration You Prefer

The SDK supports the use of either ROLE_PARTNER or ROLE_MERCHANT credentials. If you would like to scope your device to a single merchant it is recommended to use ROLE_MERCHANT credentials. If you plan to use the device across multiple merchants you should use ROLE_PARTNER credentials.

Note that the following functionality requires the use of ROLE_PARTNER credentials.

• Split Transactions

How to Create ROLE_MERCHANT Credentials

The following outlines how to create ROLE_MERCHANT credentials. Once created, you can use these credentials across multiple devices as long as the devices are associated to the same Merchant.

Request

POST /identities

• Sandbox server https://finix.sandbox-payments-api.com/identities

cURL

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/identities \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "additional_underwriting_data": {
      "annual_ach_volume": 0,
      "average_ach_transfer_amount": 0,
      "average_card_transfer_amount": 0,
      "business_description": "string",
      "card_volume_distribution": {
        "card_present_percentage": 0,
        "ecommerce_percentage": 0,
        "mail_order_telephone_order_percentage": 0
      },
      "credit_check_allowed": true,
      "credit_check_ip_address": "string",
      "credit_check_timestamp": "string",
      "credit_check_user_agent": "string",
      "merchant_agreement_accepted": true,
      "merchant_agreement_ip_address": "string",
      "merchant_agreement_timestamp": "string",
      "merchant_agreement_user_agent": "string",
      "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
      "volume_distribution_by_business_type": {
        "business_to_business_volume_percentage": 0,
        "business_to_consumer_volume_percentage": 0,
        "consumer_to_consumer_volume_percentage": 0,
        "other_volume_percentage": 0,
        "person_to_person_volume_percentage": 0
      }
    },
    "identity_roles": [
      "SELLER"
    ],
    "type": "BUSINESS"
  }'

How to Create ROLE_PARTNER Credentials

1. Login to the Finix dashboard.
2. Select the environment for which you would like to create the api credentials (Sandbox or Live)
3. In the bottom left hand corner select the Developer section
4. In the Api Keys section. Select Create Api Key

Creating a Device Resource

Creating a device resource can be done either via the Finix dashboard or via API. Below are the steps for creating a device via API.

Step 1: Create a Device

Create a Device under the Merchant provisioned to process In-Person Payments. Include the Device.model of the payment terminal you'll be using to process cards.

Request

curl -i -X POST \
  -u USfdccsr1Z5iVbXDyYt7hjZZ:313636f3-fac2-45a7-bff7-a334b93e7bda \
  https://finix.sandbox-payments-api.com/merchants/MUwfZPNW3r4EqLMzwgr6txw4/devices \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Cashier Three",
    "model": "PAX_D135",
    "name": "My PAX_D135 Finix Device",
    "serial_number": "19046260947"
  }'

Using the SDK

Installation

Add the SDK to your project via Swift Package Manager.

Initialization

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

Start Transaction

To start a transaction, first update the client with the Finix device ID (DVxxxx). Then call the function startTransaction().

finixClient.update(deviceId: "DVxxxxx")

let transactionAmount = Currency(amount: Int(amountDouble * 100), code: .USD)
finixClient.startTransaction(amount: transactionAmount, type: transactionType, splitTransfers: [SplitTransfer]? = nil, tags: ResourceTags? = nil, buyerIdentityId: String? = nil) { transferResponse, error 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.

func startRefund(transactionID: String, amount: Currency, completion: ((RefundResponse?, Error?) -> Void)?) {
    // Implement refund logic here
}

Troubleshooting with the Finix D135 Sample App

If you encounter issues with a PAX D135 while using the SDK you can reach out to the Finix Support Team at support@finix.com. A sample app showing how to integrate the iOS D135 SDK can be found here.