IDTech VP3350 Support

Starting from SDK v 2.4.0, you can add support for the VP3350 series of devices by adding the following lines to your application's Info.plist.

  UISupportedExternalAccessoryProtocols = com.idtechproducts.neo

You can use the existing search, connect, and start transaction code with the new VP3350 device.

Connect to a Mobile Reader

To connect a mobile reader, search for a list of available readers.

omni.getAvailableReaders { readers in

}

Once you have the list of available readers, you can choose which one you’d like to connect.

omni?.getAvailableReaders(completion: { readers in
	guard !readers.isEmpty else {
		self.log("No readers found")
		return
	}

	var chosenReader = ... // Choose a reader

	omni.connect(reader: chosenReader, completion: { connectedReader in
		self.log("Connected reader: \(connectedReader)")
	}) { (error) in
		// Something went wrong
	}
}) {
	self.log("Couldn't connect to the mobile reader")
}

Listen to connection events via MobileReaderConnectionStatusDelegate

Connecting to your mobile reader is a multi-step process. For example, your mobile reader may require a firmware update, or it may be fetching useful configurations from your merchant account. You can now be notified of these updates by assigning a MobileReaderConnectionStatusDelegate. Conformance of this protocol requires that you define a_ func mobileReaderConnectionStatusUpdate(status: MobileReaderConnectionStatus) _via which you’ll be notified of the status of the mobile reader as it’s connecting.

class YourClass: MobileReaderConnectionStatusDelegate {
	func mobileReaderConnectionStatusUpdate(status: MobileReaderConnectionStatus) {
		print("Mobile reader is: \(status)")
	}


	omni?.mobileReaderConnectionUpdateDelegate = self
	omni?.connect(...)
}

❗️
Required
Apple requires information about the software/hardware of systems using their payment system. Please contact your Account Manager so we can add your device and software to acceptable applications. Please provide:

Version & Build Number

Bundle ID

Name of the app on the store

Short description of your application

Take a Payment

TransactionRequest is an object that represents an intent to make a transaction. This object contains necessary data about transaction parameters, such as how much money should be collected and whether or not the payment method should be tokenized. You can pass the following items to a TransactionRequest:

/// The `Amount` to be collected during the transaction
var amount: Amount

/// The `CreditCard` to charged, if you are not paying with a mobile reader
var card: CreditCard?

/// The LineItems being passed to the transaction
var lineItems: [CatalogItem]?

/// The subtotal of the transaction
var subtotal: Double?

/// The tax applied to the transaction
var tax: Double?

/// The tip amount applied to the transaction
var tip: Double?

/// A memo for the transaction
var memo: String?

/// A reference for the transaction
var reference: String?

/// The option to tokenize the payment method for later usage
///
/// - Note: Defaults to true
///
/// Set this to false if you do not want the payment method stored
var tokenize: Bool = true

/// The id of the invoice that this payment should be applied to
///
/// If nil, then a new invoice will be created
var invoiceId: String?

/// The option to perform a preauthorization
///
/// - Note: Defaults to false
///
/// Set this to true if you would like to *only* authorize an amount. This means that the transaction will
/// only hold funds and you will need to capture it at a later date via the Stax API or the SDK
public var preauth: Bool = false

To take a payment, create a TransactionRequest and pass it along to omni.takeMobileReaderTransaction(...).

// Create an Amount
let amount = Amount(cents: 50)

// Create the TransactionRequest
let request = TransactionRequest(amount: amount)

// Take the payment
omni.takeMobileReaderTransaction(request, { completedTransaction in
    // Payment successful!
}) {
    // Error
}

Note: By default, the payment method used in the transaction is tokenized for reuse. This allows the payment method to be used from the Stax Virtual Terminal and via the Stax API. To opt out of tokenization, you can set the tokenize to false.

// Create a TransactionRequest with no tokenization
let request = TransactionRequest(amount: amount, tokenize: false)

Listen to transaction events via UserNotificationDelegate

During a transaction, some messages need to be shown to the user. For example, if the user attempts to pay with a chip EMV card by swiping it, the BBPOS mobile reader will reject this (since the card is meant to be inserted into the chip EMV slot). In this case, the Omni SDK will notify the user that the card must be inserted. This happens via the UserNotificationDelegate. Conformance of this protocol requires that you declare a func onUserNotification(userNotification: UserNotification), via which you will receive the UserNotification objects. Then, you can assign that delegate to Omni.userNotificationDelegate.

class YourClass: UserNotificationDelegate {
	func onUserNotification(userNotification: UserNotification) {
		print(userNotification.userFriendlyMessage)
	}

	omni?.userNotificationDelegate = self
	omni?.takeMobileReaderTransaction(...)
}

Refund a Payment

You can use the Stax API to refund a payment. Once you get the transaction, you can use the refundMobileReaderTransaction method to attempt the refund.

// Attain a transaction
var transaction = Transaction()

// Perform refund
omni.refundMobileReaderTransaction(transaction: transaction, completion: { (refundedTransaction) in
	// Refund successful!
}, error: { error in
	// Error
})

Pre-Auth Transaction

There are several ways you can capture a pre_auth transaction. You can capture it via our Stax API or by calling the Omni.capturePreauthTransaction(...) method in our iOS or Android SDK. You’ll need to know:

The id of the transaction.
(Optional) The amount that you’d like to capture. By default, this is the authorized amount.

/// Captures a previously-authorized transaction
///
/// - Parameters:
///   - transactionId: The id of the transaction you want to capture
///   - amount: the amount that you want to capture. If nil, then the original transaction amount will be captured
///   - completion: Called when the operation is complete successfully. Receives a Transaction
///   - error: Receives any errors that happened while attempting the operation
public func capturePreauthTransaction(transactionId: String,
                                      amount: Amount?,
                                      completion: @escaping (Transaction) -> Void,
                                      error: @escaping (OmniException) -> Void)

Note: Be mindful of the amount you want to capture. If you attempt to capture more than the authorized amount, you may get a CapturePreauthTransactionException.

Void a Pre-Auth Transaction

There are several ways for you to void a preauth transaction. You can perform the void via our Stax API or the_Omni.voidTransaction(...) method in our iOS or Android SDK. You’ll need to know the transaction ID.

/// Voids a transaction
///
/// - Parameters:
///   - transactionId: The id of the transaction you want to void
///   - completion: Called when the operation is complete successfully. Receives a Transaction
///   - error: Receives any errors that happened while attempting the operation
public func voidTransaction(transactionId: String,
                            completion: @escaping (Transaction) -> Void,
                            error: @escaping (OmniException) -> Void)

Tokenize a Card

To collect a payment method and tokenize the card without accepting a payment.

Collect payment information

You first want to collect credit card information and populate a CreditCard object.

let creditCard = CreditCard(personName = "Joan Parsnip",  
cardNumber = "4111111111111111",  
cardExp = "1230",  
addressZip = "32822")

Create the PaymentMethod

Once you have a CreditCard object, call the tokenize(:) method on the Omni object and pass a listener to be notified once tokenization is complete.

omni.tokenize(card, completion: { (paymentMethod) in

}) { error in

}