Skip to content

The SDK Architecture

The Wirecard ePOS SDK is designed to be platform-non-specific so that the apps you build using the SDK can also be largely designed in a platform-non-specific way. The architecture is comprised of nine main components, as illustrated below:

Note

While the actual component and object class names in the code vary slightly from the picture, based on the platform and programming language, the component names are all very similar. For example, the Sales Manager component is implemented as salesManager in the Objective-C code and sales() in the Java code.

Each component is essentially an Application Programming Interface (API) with public calls that greatly simplify your job of creating payment acceptance app functionality. The Integration Guide walks you through each component in detail and presents platform-specific code to show you exactly how to implement. Let's look at each component in more detail.

Note

All nine components are fully implemented on iOS, however, some of the components are not yet fully implemented on Android. Talk to your Wirecard representative for more information.

Sales Manager

Sales are the lifeblood of any merchant so the Sales Manager component is the centerpiece of the SDK.

A sale consists of a Sales Request and a Sales Response. The Sales Request is essentially what the consumer wants, which is typically a purchase (but it can also be a Return or Refund). A Sales Response is the post-processed information from the back-end, essentially indicating if the payment was successful or not.

Caution

A sale is not the same thing as a transaction. This is because a sale may involve more than one transaction, for example, if a consumer pays for a single sale with a card and cash.

Inventory Manager

Inventory Manager enables you to:

  • maintain product catalogues
  • maintain product categories
  • maintain products
  • maintain product images

In addition, if the merchant uses an ERP system, it also enables:

  • use of product stock information stored in the ERP
  • use of product price information stored in the ERP

The Inventory Manager component is highlighted below:

Cash Management Components

The Wirecard ePOS SDK is a comprehensive solution for merchants, so Cash Management is a key feature that merchants can choose to use. Cash Management is a feature that is enabled by two components:

  • The Cash Manager component handles all of the cash-related operations that take place in a merchant's shop, such as opening and closing of shifts, paying in and out, and so forth.
  • The Cash Drawer Manager component is one of four components that handles hardware that may be paired with the merchant user's mobile device. Specifically, it handles any cash drawer hardware or cash register hardware that may be paired.

These two components are highlighted below:

Hardware Components

Four of the nine components in the SDK architecture enable the management of hardware. They are highlighted below:

Terminal Manager

The Terminal Manager component enables the discovery and usage of paired terminal devices, as well as the updating of firmware.

Cash Drawer Manager

As described earlier, the Cash Drawer Manager component enables the discovery and usage of paired cash drawers and cash registers.

Printer Manager

The Printer Manager component enables the discovery and usage of paired printer devices, primarily for the printing of receipts.

Scanner Manager

This Scanner Manager component enables the discovery and usage of paired scanning devices, which are used to scan QR codes and barcodes.

Customer, User and File Management

Few supplementary components assist with handling customers and users and their standards behavior

Customer Manager (ERP)

ERP systems store a wide variety of useful information about a merchant's customers, such as pricing discounts and so forth. The Customer Manager component enables the use of this information.

User Manager

Apps created with the SDK are typically part of a larger app, so you may not need to handle authentication of users, passwords and so forth. But if you do need to handle these things, the User Manager component has a variety of useful functionality, including:

  • Password Policy checks
  • Password Resets
  • Reminder User of Password
  • Change Password

File Manager

This File Manager enables handling of (usually brand-specific) files in app using support from backend side. Primary it's like branding support component natively build in SDK.

Error management

Almost all Wirecard ePOS SDK calls can have two results. First is positive, when everything is happy and second, something less-happy is the error result. See in categories below, which errors could appear.

iOS Errors

WDErrorBackendReturnedJSONDoesNotMatchMappedClass
WDErrorUnauthorizedUser
WDErrorUserPasswordExpired
WDErrorUserPasswordChangeRequired
WDErrorUserAccessForbidden
WDErrorResourceNotFound
WDErrorSessionExpired
WDErrorRequestTimeOut
WDErrorRequestNoProperResponse
WDErrorRequestParameterRequired
WDErrorRequestedResourceNotFound
WDErrorRequestFailedValidation
WDErrorPlugInTimeout
WDErrorSignatureTimeout
WDErrorInitialization
WDErrorLowBatteryLevel
WDErrorSwipeTimeout
WDErrorBadSwipe
WDErrorNotSupportedCardType
WDErrorDataProcessing
WDErrorOnlineProcessing
WDErrorTransactionNotApproved
WDErrorHardwareAccessPermission
WDErrorTokenExpired
WDErrorConnection
WDErrorSignatureRequired
WDErrorCantLoadTerminalConfiguration
WDErrorTerminalDamaged
WDErrorNoDUKPT
WDErrorFailedToStartEMV
WDErrorFailedToSendOfflineEMV
WDErrorFailedToSendOnlineEMV
WDErrorTerminalNotSetInMerchant
WDErrorResponseLost
WDErrorTransactionTerminated
WDErrorTransactionDeclined
WDErrorTransactionFailure
WDErrorBlockedCardType
WDErrorFailedBluetoothConnection
WDErrorFailedPrinterBluetoothConnection
WDErrorFailedTerminalBluetoothConnection
WDErrorFailedDrawerBluetoothConnection
WDErrorFailedPistolBluetoothConnection

WDErrorTerminalNotReady
WDErrorTerminalCommunication
WDErrorTerminalTimeoutApplicationSelection
WDErrorTerminalFailedToGetICCApplicationsList
WDErrorTerminalFailedToTerminateCurrentTerminalPaymentFlow
WDErrorLowPowerInAudioJack
WDErrorMonoAudioEnabled
WDErrorTerminalCommandTimeOut
WDErrorTerminalTimeOut
WDErrorTerminalWaitingUserTimeOut
WDErrorTerminalCancelledFileUpload

WDErrorWrongUserNameOrPassword
WDErrorVendorNotFound
WDErrorExternalAccessoriesProtocolInvalid application .plist file.
WDErrorExternalIdNotFound
WDErrorChangePasswordCriteriaNotMet
WDErrorQueryStatsTokenExpired
WDErrorForgotExternalIdNotFound

WDErrorConfigFilesInfoTimeout
WDErrorConfigFilesZipDownload
WDErrorTerminalDisconnected
WDErrorConfigFilesTerminalMayNotBeSet
WDErrorConfigFilesTerminalCancelledFileDownload
WDErrorConfigFilesProductionFirmwareOnDevelopmentTerminal
WDErrorConfigFilesDevelopmentFirmwareOnProductionTerminal
WDErrorConfigFilesTerminalUnsupported
WDErrorConfigFilesTokenExpired
WDErrorInventoryNoData
WDErrorTerminalFirmwareDoesNotExist
WDErrorTerminalConfigDoesNotExist

WDErrorConfigFilesReading

WDErrorPrinterTimeout
WDErrorPrinterInitialization
WDErrorPrinterLowBatteryLevel
WDErrorPrinterNotConnected
WDErrorPrinterOperation
WDErrorPrinterUnsupportedDevice
WDErrorDeviceDoesNotSupportPrinting
WDErrorPrinterPaperLow

WDErrorSignatureRejectedFromTerminal
WDErrorInvalidPaymentConfiguration
WDErrorInvalidAIDConfiguration

WDErrorTransactionReversalRequired
WDErrorTransactionReversedByTerminal
WDErrorTransactionReversalFailed
WDErrorTransactionUpdateFailed

WDErrorExtensionClassDoesNotExist
WDErrorExtensionDoesNotSupportMethod
WDErrorInvalidParameter
WDErrorDeviceRooted

WDErrorActiveTerminalNotSet
WDErrorActiveScanPistolNotSet
WDErrorActivePrinterNotSet
WDErrorPinLocked
WDErrorPinInvalid
WDErrorGeneral
WDErrorServerSSLCertificateExpired
WDErrorFailedTerminalBluetoothConnectionNotInPayment

WDErrorMissingMerchant
WDErrorAnotherTransactionIsInProgress

Android Exceptions

SDK will usually returns exception, which extends from EposException and can also contain another exception in cause.

Hierarchy of exceptions: 

EposException (de.wirecard.epos.exceptions)
    DeviceSelectingCanceled (de.wirecard.epos.exceptions.initialization)
    DeviceTypesSelectingCanceled (de.wirecard.epos.exceptions.initialization)
    EposBackendException (de.wirecard.epos.exceptions)
    ExtensionException (de.wirecard.epos.exceptions.extension)
        CardEntryAbortException (de.wirecard.epos.exceptions.extension.general)
        CommunicationException (de.wirecard.epos.exceptions.extension)
            BluetoothConnectionException (de.wirecard.epos.exceptions.extension.communication)
            CommunicationTimeoutException (de.wirecard.epos.exceptions.extension.communication)
                AmountConfirmationTimedOutException (de.wirecard.epos.exceptions.extension.communication)
            ConnectionAfterRestartDeviceException (de.wirecard.epos.exceptions.extension.communication)
            ConnectionFailedException (de.wirecard.epos.exceptions.extension.communication)
            DeviceDisconnectedException (de.wirecard.epos.exceptions.extension.communication)
            NoBluetoothAdminPermissionException (de.wirecard.epos.exceptions.extension.communication)
            NoBluetoothException (de.wirecard.epos.exceptions.extension.communication)
            NoBluetoothPermissionException (de.wirecard.epos.exceptions.extension.communication)
            NoUsbException (de.wirecard.epos.exceptions.extension.communication)
            PairingToTerminalException (de.wirecard.epos.exceptions.extension.communication)
            TerminateAfterConfirmException (de.wirecard.epos.exceptions.extension.communication)
            UnknownCommunicationException (de.wirecard.epos.exceptions.extension.communication)
            UsbConnectionException (de.wirecard.epos.exceptions.extension.communication)
            UsbPermissionDeniedException (de.wirecard.epos.exceptions.extension.communication)
            WrongBluetoothDeviceAddressException (de.wirecard.epos.exceptions.extension.communication)
        InvalidFirmwareVersionException (de.wirecard.epos.exceptions.extension.general)
        InvalidTerminalAppVersionException (de.wirecard.epos.exceptions.extension.general)
        LoadTerminalUpdateException (de.wirecard.epos.exceptions.extension.general)
        TerminalApplicationMismatchException (de.wirecard.epos.exceptions.validation)
        TerminalUpdateFileException (de.wirecard.epos.exceptions.extension.general)
        UnknownExtensionException (de.wirecard.epos.exceptions.extension.general)
    NoInternetException (de.wirecard.epos.exceptions)
    NotPaxDeviceException (de.wirecard.epos.exceptions.extension.communication)
    SaleFailedException (de.wirecard.epos.exceptions)
        PasswordConfirmationRequestCanceledException (de.wirecard.epos.exceptions.sale)
        SaleNotApprovedException (de.wirecard.epos.exceptions.sale)
        SignatureConfirmationCanceledException (de.wirecard.epos.exceptions.sale)
        SignatureRequestCanceledException (de.wirecard.epos.exceptions.sale)
        UnknownSaleFailException (de.wirecard.epos.exceptions.sale)
    UnauthorizedException (de.wirecard.epos.exceptions)
    UnknownException (de.wirecard.epos.exceptions)
    ValidationException (de.wirecard.epos.exceptions)
        AmountFractionDigitsExceededException (de.wirecard.epos.exceptions.validation)
        AmountTooHighException (de.wirecard.epos.exceptions.validation)
        AmountTooLowException (de.wirecard.epos.exceptions.validation)
        DeviceTypeMismatchException (de.wirecard.epos.exceptions.validation)
        InvalidTerminalUpdateException (de.wirecard.epos.exceptions.validation)
        MandatoryParametersException (de.wirecard.epos.exceptions.validation)
        MissingCallbackException (de.wirecard.epos.exceptions.validation)
        MissingConfigurationException (de.wirecard.epos.exceptions.validation)
        MissingContextException (de.wirecard.epos.exceptions.validation)
        MissingCurrencyException (de.wirecard.epos.exceptions.validation)
        MissingDeviceIdException (de.wirecard.epos.exceptions.validation)
        MissingParamException (de.wirecard.epos.exceptions.validation)
        MissingSaleException (de.wirecard.epos.exceptions.validation)
        MissingTerminalConfigurationException (de.wirecard.epos.exceptions.validation)
        NoDeviceTypeException (de.wirecard.epos.exceptions.validation)
        NoNewTerminalUpdateException (de.wirecard.epos.exceptions.validation)
        NoPaymentConfigurationException (de.wirecard.epos.exceptions.validation)
        NoPaymentMethodException (de.wirecard.epos.exceptions.validation)
        NoSelectedDeviceException (de.wirecard.epos.exceptions.validation)
        ParallelSalesException (de.wirecard.epos.exceptions.validation)
        SaleValidationException (de.wirecard.epos.exceptions.validation)
        ServiceChargeQuantityException (de.wirecard.epos.exceptions.validation)
        TerminalAidConfigurationException (de.wirecard.epos.exceptions.validation)
        TerminalApplicationFileException (de.wirecard.epos.exceptions.validation)
        TerminalCapabilityException (de.wirecard.epos.exceptions.validation)
        TerminalConfigUpdateException (de.wirecard.epos.exceptions.validation)
            IncorrectUpdateFilesException (de.wirecard.epos.exceptions.extension.general)
        TerminalConfigurationException (de.wirecard.epos.exceptions.validation)
        TerminalProfileException (de.wirecard.epos.exceptions.validation)
        TerminalProfileForNetworkException (de.wirecard.epos.exceptions.validation)
        ThereIsNoAvailableDevice (de.wirecard.epos.exceptions.initialization)
        ThereIsNoAvailableDeviceType (de.wirecard.epos.exceptions.initialization)
        TipQuantityException (de.wirecard.epos.exceptions.validation)