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 Detail

      • 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.

      • setData

        void setData​(java.lang.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

        java.util.Map<java.lang.String,​java.lang.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 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.

      • setPPSEFci

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