POS

This object exposes APIs to interact with the POS side. This includes authentication and initiating and listing payments.

Setup

The recommended way is to have a singleton instance of VipasoPOS in your code with a passed delegate/listener instance that will receive all authentication state change events.

Configuration

When you create the instance, you can pass some configuration parameters to update the base path and the BLE settings. You can also pass a VipasoPOSDelegate instance, that will receive notifications when the authentication state changes.

VipasoPOS(
    config: VipasoConfiguration(
        paymentBasePath: Config.basePath,
        bleServiceUUID: Config.bleServiceUUID
    ),
    delegate: delegate
)

Observing SDK events

By implementing the VipasoPOSDelegate interface and passing it to the SDK, the client-side developer can subscribe to authentication state change events. You can pass the listener/delegate at init. Setting it automatically fires an event with the latest authentication state of the user. As the user signs up, logs in or out, an event will arrive and the app can be updated accordingly.accordingly.

extension RootCoordinator: VipasoPOSDelegate {

    func onAuthenticationStateChange(vipaso: VipasoPOSProtocol, authenticated: Bool) {
        if authenticated {
            displayMainCoordinator()
        } else {
            displayAuthenticationCoordinator()
        }
    }

    func onEventTracked(name: String, parameters: [String: String]?) {
        // analytics calls
    }
}

Managed Authentication

There is not signup support on the POS side on purpose. We have a proper merchant registration flow in place that is outside of the applications' scope.

Login

You can log in with the merchant details you received from us. You pass the e-mail address as identifier with a password, the SDK will store your session token securely and the observer will be notified.

let request = LoginRequest(identifier: email, password: password)
vipasoPOS.managedAuth.login(request: request) { result in
    switch result {
    case .success:
        print("success")
    case .failure(let error):
        print("error: \(error.localizedDescription)")
    }
}

Logging out

Simply calling the exposed logout function, the SDK will remove the stored session token and the observer will be notified.

Delegated Authentication

With delegated authentication Vipaso provides the opportunity to authenticate a self hosted user management with the Vipaso SDK. This means that Vipaso does not provide user management but allows your user management to be integrated with the SDK.

Establishing authentication

With this method Vipaso supports authenticating users that are not managed by Vipaso. The host app is expected to call establishAuthentication on each app start, after login.

NOTE: This method is using async/await in order as the first step to modernize our classic closure based SDK.

try await vipasoPay.delegatedAuth.establishAuthentication(
  userIdentifier: userIDString,
  connect: { [weak self] jwk in
  	// Use received JWK here to return encrypted init token
	}
)

Merchant data

Fetching merchant info

To get all info about the merchant, use fetchMerchant.

vipasoPOS.user.fetchMerchant { result in
    switch result {
    case .success(let response):
        promise(.success(response.merchant))
    case .failure(let error):
        promise(.failure(.generic(error: error)))
    }
}

This will return a merchant object with the following data.

public struct VipasoMerchant {
    public var id: String?
    public var name: String?
    public var operatorID: String?
    public var currency: String?
}

Fetching feature flags

We support adding custom feature flags so you can remote control what your users have access to in their apps. The SDK fetches them under the hood and exposes an API to read them on the client-side. The API prefers using cached flags from the database.

vipasoPOS.user.fetchFeatureFlags { [weak self] result in
    guard let self = self else { return }
    switch result {
    case .success(let response):
        print("success: \(response.featureFlags)")
    case .failure(let error):
        print("error: \(error.localizedDescription)")
    }
}

Payments

List all payments

You can list all your payment history by the following fetch call. You can specify a page and a status filter.

vipasoPOS.payment.fetchPayments(page: 3, status: .completed) { result in
    switch result {
    case .success(let response):
        print("success: \(response.payments)")
    case .failure(let error):
        print("error: \(error.localizedDescription)")
    }
}

Initiating a payment

To create a new payment, you can use requestPaymentViaBLE. You only need to set the expected payment details and the SDK initiate the payment request. You can then share that id with the Pay side (for example over BLE) and it can start executing the payment.

let paymentRequest = VipasoPaymentRequest(
    paymentID: paymentID,
    merchantID: merchantID,
    operatorID: operatorID,
    merchantName: merchantName,
    amount: amount,
    currency: currency,
    createdAt: Date().iso8601String
)
vipasoPOS.payment.requestPaymentViaBLE(request: paymentRequest) { result in
    switch result {
    case .success(let response):
        promise(.success(response))
    case .failure(let error):
        promise(.failure(.generic(error: error)))
    }
}

Cancel Payment

Cancels the payment with the supplied paymentID

vipasoPos.payment.cancelPayment(paymentID: paymentID)

Fetching payment details

Fetching the details of a payment is a simple fetch call, you only need to set the payment id.

let request = FetchPaymentDetailsRequest(paymentID: paymentID)
vipasoPOS.payment.fetchPayment(request: request) { result in
    switch result {
    case .success(let response):
        print("success: \(response.payment)")
    case .failure(let error):
        print("error: \(error.localizedDescription)")
    }
}

Stop BLE payment

Stops the payment and demolishes the Payment BLE stack.

NOTE: Only use this only after the payment finished (either with success, cancellation or failure).

vipasoPOS.payment.stopBLE()

Sync offline payments - !!! EXPERIMENTAL !!!

Synchronizes the offline payments stored in the mobile app. Please note that this feature is currently experimental.

vipasoPOS.payment.syncPayments { result in
    switch result {
    case .success(let response):
        print("success: \(response)")
    case .failure(let error):
        print("completion success/error")
    }
}

Fetch offline payments - !!! EXPERIMENTAL !!!

You can fetch all offline payments that will be synchronized by syncPayments using the following API. Please note that this feature is currently experimental.

let offlinePayments = vipasoPOS.payment.fetchOfflinePayments()
print("offline payments: \(offlinePayments)")