Package com.gemalto.mfs.mwsdk.payment.engine

Interface PaymentService

public interface PaymentService
PaymentService is an engine that enables the flow and contains execution information for a payment transaction. Some of the control flows such as activation and deactivation, however, are managed internally by the PaymentBusinessService rather. A typical flow would consist of the following steps:
  1. Contactless Payment
    • Activate a digitalized card for transaction: Done automatically by End-User tapping the phone to POS or via API call to PaymentBusinessService.activate(com.gemalto.mfs.mwsdk.dcm.DigitalizedCard, PaymentType, PaymentServiceListener)
    • Prepare transaction: This consists a few actions to be done after the UI application receive call-back PaymentServiceListener.onAuthenticationRequired(PaymentService, CHVerificationMethod, long) so as to put the digitalized card in the ready state for transaction to take place, in the order of following:
      • Customize payment flow: In some deployment context, the End-User may be allowed to select a few transaction options, such as to use the card as debit or credit card. These features are not supported by the SDK inherently as they can be different between issuers. At the solution level, the SDK provides access to additional data coming from issuer to cater for these custom flows via API getAdditionalData(). With this API, the UI application should be able to show different options to End-User or to make decision on its own. Then the application can call setData(String, byte[]) to "temporarily" alter some of the allowed fields in the transaction details, according to what has been specified by the issuer to implement the custom flows. Note that the changes only take effect for the current transaction and will not be persisted.
      • If requested by SDK, verify CardHolder: Depending on the card profile, the Mobile PIN may be requested for On-Device CardHolder verification. This will be indicated in the parameter CHVerificationMethod of the call-back. The UI application needs to take and pass this parameter to the getCHVerifier(CHVerificationMethod) to get back a corresponding verifier object. Once the UI application has fulfilled the verification step, the verifier object will automatically notify the PaymentService to be ready for the next step. If this step is found to be not needed, the SDK will be automatically put in the ready state.
    • Execute transaction: Indicated by the UI application receiving call-back ContactlessPaymentServiceListener.onReadyToTap(PaymentService), the SDK is in a ready state. At this point of time, the End-User can now tap the phone against the POS. On the another side, the UI application needs to call setCVMResetTimeoutListener(CVMResetTimeoutListener) to be able to track the count-down timer. For security reason, the SDK's ready state will expire after a given amount of time (the exact duration is indeed also returned in the previous call-back PaymentServiceListener.onAuthenticationRequired(PaymentService, CHVerificationMethod, long) ). The CVMResetTimeoutListener will receive every second count-down, that can be useful for display to End-User for his / her awareness. The timer will be invalidated when the End-User taps against the POS and the transaction takes place.
    • Finish transaction: The transaction may finish normally, call-back ContactlessPaymentServiceListener.onTransactionCompleted(TransactionContext), or with some error, call-back PaymentServiceListener.onError(SDKError) . The TransactionContext contains information about the transaction that is worth to be displayed to End-User. It's important to understand that from the perspective of the SDK, the result of the transaction is unknown. Whether the transaction is approved by the issuer can only be known by the validation server. The application will receive a push notification some time later that indicates the result of the transaction.
  2. QR Code Payment
    • Activate a digitalized card for transaction: Done automatically by SDK during PaymentBusinessService.generateQRCodePaymentData(String, PaymentServiceListener) API call.
    • Prepare transaction: This consists a few actions to be done after the UI application receive call-back PaymentServiceListener.onAuthenticationRequired(PaymentService, CHVerificationMethod, long) so as to put the digitalized card in the ready state for transaction to take place, in the order of following:
      • If requested by SDK, verify CardHolder: Depending on the card profile, the wallet PIN or device keyguard authentication may be requested for On-Device CardHolder verification. This will be indicated in the parameter CHVerificationMethod of the call-back. The UI application needs to take and pass this parameter to the getCHVerifier(CHVerificationMethod) to get back a corresponding verifier object. Once the UI application has fulfilled the verification step, the verifier object will automatically notify the PaymentService to be ready for the next step. If this step is found to be not needed, the SDK will be automatically put in the ready state.
    • Generate QR Code Payment Data: Indicated by the UI application receiving call-back QRCodePaymentServiceListener.onDataReadyForPayment(PaymentService, TransactionContext), the SDK is in a ready state. At this point of time, the UI application shall retrieve the generated QR code payment data for QR code generation. QR code payment data generation may completed normally or with some error, call-back PaymentServiceListener.onError(SDKError) . The TransactionContext contains information about the transaction that is worth to be displayed to End-User. It's important to understand that from the perspective of the SDK, the result of the transaction is unknown. Whether the transaction is approved by the issuer can only be known by the validation server. The application will receive a push notification some time later that indicates the result of the transaction.

  • Method Details

    • getType

      PaymentType getType()
      Method to check the type of current transaction, refer to PaymentType. The type is actually the same per requested by the caller of the activation method PaymentBusinessService.activate(com.gemalto.mfs.mwsdk.dcm.DigitalizedCard, PaymentType, PaymentServiceListener)
      Returns:
      Type of the payment transaction.

    • isActivated

      boolean isActivated()
      Method to check the status of the card. In fact, the method shall return true if the UI application has received the call-back PaymentServiceListener.onAuthenticationRequired(PaymentService, CHVerificationMethod, long) . At this time, the card's data has been loaded into memory and now waiting for the next step from UI application.
      Returns:
      Returns true if the digitalized card has been successfully activated.

    • getCHVerifier

      Object getCHVerifier(CHVerificationMethod cvm)
      Method to acquire the CardHolder verifier object corresponding the the value CHVerificationMethod returned in the call-back PaymentServiceListener.onAuthenticationRequired(PaymentService, CHVerificationMethod, long) . Due to the potentiality of different method interfaces of the verifiers, the object is returned in generic type and needs to be cast according to the description in CHVerificationMethod.
      IMPORTANT : This method shall not be called for card-like card profile (always no CDCVM).
      Parameters:
      cvm - The CHVerificationMethod to use. This should be the value returned in the call-back PaymentServiceListener.onAuthenticationRequired(PaymentService, CHVerificationMethod, long) .
      Returns:
      the CHVerifier object.

    • setCVMResetTimeoutListener

      void setCVMResetTimeoutListener(CVMResetTimeoutListener cvmResetTimeoutListener)
      Method to register a listener on the count-down timer for the validity of the verification of CardHolder, if done before.
      IMPORTANT:The UI application must register the listener if a CardHolder verification was asked by the SDK. Refer to the summary of this interface for more details of this method in the whole flow. IMPORTANT : This method shall not be called for card-like card profile (always no CDCVM).
      Parameters:
      cvmResetTimeoutListener - The listener that will receive count-down ticks and notification upon expiration of the CardHolder verification status.

    • getPaymentServiceListener

      PaymentServiceListener getPaymentServiceListener()
      Method to return the listener object that was registered by the UI application for receiving notifications during the transaction execution. See APDUProcessorSetupCallbacks.setupListener()
      Returns:
      The PaymentServiceListener that will be receiving call-backs posted by this PaymentService object.

    • setData

      void setData(String path, byte[] value)
      Method to update the in-memory card profile according to the supported path. The paths are nominal enumerations to some predefined parts of the profile that allow update operations. This is to enable some customized implementation of the transaction while maintaining the best possible the security for the transaction profile data.
      This method is used in conjunction with getAdditionalData(). Refer to the documentation of getAdditionalData() for more details and example of possible use case. IMPORTANT : This method shall not be called for card-like card profile (always no CDCVM).
      Parameters:
      path - One of the predefined path in the card profile that allows update. Refer to the list in ProfileUpdatablePaths.
      value - The value to update. The validity of the data depends on the path.

    • getAdditionalData

      Map<String,String> getAdditionalData()
      Method to get the custom card profile data provided by the issuer for custom purpose. The data in the resulting map contains two always available fields with following key names: In the context of PaymentService, the UI application should use this method to retrieve issuer-related payment alternative options, whereby the End-User can select to adjust their payment.
      An example would be the issuer uses the a key name "payment_options" with value of single byte as following:
      • 0x80 (0b1000000): Profile supporting "pay by debit"
      • 0x40 (0b0100000): Profile supporting "pay by credit"
      • 0xC0 (0b1100000): Profile supporting both
      The following code snippet demonstrate simple parsing of the data: 
       
 final Map<String, String> additionalData = paymentService.getAdditionalData();
 final byte[] paymentOptionBytes = additionalData.get("payment_options").getBytes();
 // UI application needs to validate the paymentOptionBytes before using it
 if (paymentOptionBytes[0] == 0x80) {
        // Calling setData(String, byte[]) to update card profile data for "pay by debit"
        paymentService.setData(..., ...);
 }
 else if (paymentOptionBytes[0] == 0x40) {
        // Calling setData(String, byte[]) to update card profile data for "pay by credit"
        paymentService.setData(..., ...);
 }
 else if (paymentOptionBytes[0] == 0xC0) {
        // Ask the user for his choice, then call setData(String, byte[]) like in the above 2 if-blocks.
        showDebitCreditSelectionDialog();
 }
 else {
        // Handle error case here where the payment options is not in the range.
 }
      IMPORTANT : This method shall not be called for card-like card profile (always no CDCVM).
      Returns:
      a key-value pairs of additional data from issuer. Note that the value of each key may contain any kind of objects, encoded as UTF-8 string. Each deployment context should have a document to explicitly declare the encoding used for each additional field, and that's not part of the SDK to be able to know this custom.

    • getTransactionContext

      TransactionContext getTransactionContext()
      A method to get the TransactionContext object which contains values related to the payment transaction (e.g. amount). This is typically used in TAP-PIN-TAP use case wherein the MPA needs to display that transaction related data during the first tap and before finishing the payment transaction. Ideally, the MPA needs to get the reference when a PaymentService has been activated (see PaymentServiceListener.onAuthenticationRequired(PaymentService, CHVerificationMethod, long)).
      Returns:
      TransactionContext

    • getQRCodeData

      QRCodeData getQRCodeData()
      A method to get the QRCodeData object which contains values related to the QR payment. This is should only be used in case of QR code payment. Thr MPA needs to get the reference when a PaymentService has been activated (see QRCodePaymentServiceListener.onDataReadyForPayment(PaymentService, TransactionContext)
      Returns:
      QRCodeData

    • setPPSEFci

      boolean setPPSEFci(byte[] tlv)
      Parameters:
      tlv - Set the PPSE of the Card
      Returns:
      True if set ppse is Success , False if Failure

    • getRemotePaymentData

      RemotePaymentOutputData getRemotePaymentData()
      A method to get the RemotePaymentOutputData object which contains values related to the Remote(Dsrp) payment. This is should only be used in case of Remote (Dsrp) payment. Thr MPA needs to get the reference when a PaymentService has been activated (see RemotePaymentServiceListener.onDataReadyForPayment(PaymentService, TransactionContext)
      Returns:
      RemotePaymentOutputData