Class PaymentManager

Method Details

• requestCardInfo

  public void requestCardInfo(android.os.Bundle requestFilter, PaymentManager.CardInfoListener listener)

  API to request card information of the available cards for payment using Samsung Pay.
  The partner app can use this API to query available cards (user already has registered) in Samsung Pay and decide whether to display Samsung Pay button or not on their application.
  For example, if merchant app supports only one specific card brand, but the user has not registered any card with the brand, then merchant app decides not to display the Samsung Pay button with this query.
  
  

   
       // Set the serviceId which is assigned by the Samsung Pay Developer during on boarding.
       String serviceId = "sampleServiceId";
       Bundle bundle = new Bundle();
       bundle.putString(SamsungPay.PARTNER_SERVICE_TYPE, SamsungPay.ServiceType.INAPP_PAYMENT.toString());
  
       PartnerInfo pInfo = New PartnerInfo(serviceId, bundle);
       PaymentManager paymentManager = new PaymentManager(context, pInfo);
       boolean enablePayButton = false;
  
       PaymentManager.CardInfoListener cardInfoListener = new PaymentManager.CardInfoListener(){
          @Override
          public void onResult(List&#60CardInfo&#62 cardList) {
              // CardInfo list for available Cards.
              if(cardList != null && cardList.size() > 0) {
              // This means registered card(s) found in Samsung Pay.
                  for(CardInfo cardInfo : cardList) {
                      if(cardInfo.getBrand() == SpaySdk.Brand.ABCD) {
                          enablePayButton = true;
                          break;
                      }
                  }
              }
          }
          @Override
          public void onFailure(int errorCode, Bundle errorData) {
              Log.e(TAG, "onFail callback is called, errorCode: " + errorCode);
              // To get more reason of the failure,
              // check some extra error codes in the errorData bundle such as SamsungPay.EXTRA_ERROR_REASON (if provided).
          }
      };
  
      Bundle filter = new Bundle();
      ArrayList<PaymentManager.Brand> list = new ArrayList<>();
      list.add(PaymentManager.Brand.VISA);
      list.add(PaymentManager.Brand.MASTERCARD);
      filter.putParcelableArrayList(PaymentManager.EXTRA_KEY_CARD_BRAND_FILTER, list);
      paymentManager.requestCardInfo(filter, cardInfoListener);
   
   

  Parameters:

  requestFilter - Filter to limit return cardInfo list. This is optional parameter. If the caller does not set any value, all the cards which are available for online (in-app) payment on Samsung Pay are returned.

  listener - Callback through which the result is provided.
  On success, PaymentManager.CardInfoListener.onResult(List) is invoked with CardInfo list.
  
  On any failure, the failure code is provided via PaymentManager.CardInfoListener.onFailure(int, Bundle).
  
  Note: Please refer SpaySdk.COMMON_STATUS_TABLE in detail.

  Throws:

  NullPointerException - If the CardInfoListener is null.

  Since:

  API Level 1.1

• updateSheet

  public void updateSheet(CustomSheet sheet)

  API to update sheet on the custom payment sheet.
  
  

   
        @Override
        public void onCardInfoUpdated(CardInfo selectedCardInfo, CustomSheet customSheet) {
            AmountBoxControl amountBoxControl = (AmountBoxControl) customSheet.getSheetControl(AMOUNT_CONTROL_ID);
            if (amountBoxControl == null) {
                Log.d(TAG, "Transaction : Failed / amountBoxControl is null.");
                return;
            }
  
            // You can set updated amount.
            amountBoxControl.updateValue(PRODUCT_ITEM_ID, 1000);
            amountBoxControl.updateValue(PRODUCT_TAX_ID, 50);
            amountBoxControl.updateValue(PRODUCT_SHIPPING_ID, 10);
            amountBoxControl.updateValue(PRODUCT_FUEL_ID, 0, "Pending");
            amountBoxControl.setAmountTotal(1060, AmountConstants.FORMAT_TOTAL_PRICE_ONLY);
            customSheet.updateControl(amountBoxControl);
  
            // Call updateSheet() API method with AmountBoxControl. This is mandatory.
            paymentManager.updateSheet(customSheet);
        }
   
   

  Parameters:

  sheet - CustomSheet is to be updated.

  Throws:

  IllegalStateException - Thrown if service is disconnected.

  NullPointerException - Thrown if the sheetControl is null.

  Since:

  API Level 1.3

• updateSheet

  public void updateSheet(CustomSheet sheet, int errorCode, String customErrorMessage)

  API to update sheet on the custom payment sheet and display a custom error message.
  
  

   
       @Override
       public void onCardInfoUpdated(CardInfo selectedCardInfo, CustomSheet customSheet) {
            AmountBoxControl amountBoxControl = (AmountBoxControl) customSheet.getSheetControl(AMOUNT_CONTROL_ID);
            if (amountBoxControl == null) {
                Log.d(TAG, "Transaction : Failed / amountBoxControl is null.");
                return;
            }
  
            // You can set updated amount.
            amountBoxControl.updateValue(PRODUCT_ITEM_ID, 1000);
            amountBoxControl.updateValue(PRODUCT_TAX_ID, 50);
            amountBoxControl.updateValue(PRODUCT_SHIPPING_ID, 10);
            amountBoxControl.updateValue(PRODUCT_FUEL_ID, 0, "Pending");
            amountBoxControl.setAmountTotal(1060, AmountConstants.FORMAT_TOTAL_PRICE_ONLY);
            customSheet.updateControl(amountBoxControl);
  
            // If merchant want to display error message, call updateSheet() API method with CUSTOM_MESSAGE error code and
            text message.
            paymentManager.updateSheet(customSheet, PaymentManager.CUSTOM_MESSAGE, "Phone number is not valid. Please
            change your phone number!");
       }
   
   

  Parameters:

  sheet - CustomSheet is to be updated.

  errorCode - This code should be CUSTOM_MESSAGE if merchant wants to use its own message.

  customErrorMessage - If errorCode is set to CUSTOM_MESSAGE then this parameter will be used to display the message on the payment sheet, else it will be ignored.

  Throws:

  IllegalStateException - Thrown if service is disconnected.

  NullPointerException - Thrown if the sheetControl is null.

  Since:

  API Level 1.5

• startSimplePay

  public void startSimplePay(CardInfo cardInfo, StatusListener listener)

  API to request payment with Simple Pay.
  Using this API, partner app can start the Samsung Pay payment screen for a specific card.
  For example, user can login to partner app (example: bank app), view the list of cards, and select a card (which is already registered in Samsung Pay) to make in-store payment. Samsung Pay is launched with the selected card for payment. The user can authenticate and start the payment.

  Partner app needs to obtain an usage permission of startSimplePay() API in server-side. Without the permission, calling of startSimplePay() API would be failed.
  

   
      // Set the serviceId which is assigned by the Samsung Pay Developer during on boarding.
      String serviceId = "sampleServiceId";
      Bundle bundle = new Bundle();
      bundle.putString(SamsungPay.PARTNER_SERVICE_TYPE, SamsungPay.ServiceType.APP2APP.toString());
  
      PartnerInfo pInfo = new PartnerInfo(serviceId, bundle);
      PaymentManager paymentManager = new PaymentManager(context, pInfo);
  
      String cardId = "cardId_test";
      Bundle metaData = new Bundle();
      //
      // Set values in metaData bundle.
      //
      CardInfo cardInfo = new CardInfo.Builder().setCardId(cardId).setCardMetaData(metaData).build();
  
      paymentManager.startSimplePay(cardInfo, new StatusListener() {
         @Override
          public void onSuccess(int status, Bundle data) {
             // Called when start Samsung Pay Simple Pay is showed to user with specified card.
             Log.d (TAG, "Simple Pay is shown");
          }
  
         @Override
         public void onFail(int errorCode, Bundle errorData) {
             Log.e(TAG, "onFail callback is called, errorCode: " + errorCode);
             // To get more reason of the failure,
             // check some extra error codes in the errorData bundle such as SamsungPay.EXTRA_ERROR_REASON (if provided).
         }
     });
   
   

  How to set metaData in CardInfo:
  - Case 1. Requesting in-store payment

      metaData.putString(PaymentManager.EXTRA_PAY_OPERATION_TYPE,
              PaymentManager.PAY_OPERATION_TYPE_PAYMENT);
      metaData.putString(PaymentManager.EXTRA_ISSUER_NAME, "issuerName_test");
      metaData.putInt(PaymentManager.EXTRA_TRANSACTION_TYPE,
              PaymentManager.TRANSACTION_TYPE_MST | PaymentManager.TRANSACTION_TYPE_NFC);
  
      // Set Logo image and background color for Simple Pay screen
      metaData.putString(PaymentManager.EXTRA_LOGO_IMAGE_URL, "http://testbank.com/logo.png");
  
   

  - Case 2. Requesting refund for in-store payment (for Korean issuers only)

      metaData.putString(PaymentManager.EXTRA_PAY_OPERATION_TYPE,
              PaymentManager.PAY_OPERATION_TYPE_REFUND);
      metaData.putString(PaymentManager.EXTRA_ISSUER_NAME, "issuerName");
      metaData.putString(PaymentManager.EXTRA_TRANSACTION_DATE, "yyyyMMddHHmm");
      metaData.putString(PaymentManager.EXTRA_TRANSACTION_NUMBER, "1234567890");
      metaData.putInt(PaymentManager.EXTRA_TRANSACTION_TYPE,
              PaymentManager.TRANSACTION_TYPE_MST | PaymentManager.TRANSACTION_TYPE_NFC);
  
   

  Parameters:

  cardInfo - Card information to pay. cardMetaData bundle key-value pairs can be defined as follows:
  
  

  Keys	Values
  SamsungPay#EXTRA_ISSUER_NAME	String issuerName (issuerCode for Korean issuers)
  EXTRA_PAY_OPERATION_TYPE	PAY_OPERATION_TYPE_PAYMENT
  	PAY_OPERATION_TYPE_REFUND (for Korean issuers only)
  EXTRA_TRANSACTION_TYPE - For Korean issuers: effective as requested. - For other country issuers: effective depends on device configuration(i.e in UK, only NFC supported) or card meta-data(token profile) from Card Network.	TRANSACTION_TYPE_MST
  	TRANSACTION_TYPE_NFC
  	TRANSACTION_TYPE_MST | TRANSACTION_TYPE_NFC
  EXTRA_TRANSACTION_DATE	String transaction date for refund(for Korean issuers only)
  EXTRA_TRANSACTION_NUMBER	String transaction number for refund(for Korean issuers only)
  EXTRA_LOGO_IMAGE_URL	String issuer logo image URL

  listener - StatusListener instance. Callback through which the result is provided.
  On success, StatusListener.onSuccess(int status, Bundle data) is invoked with SpaySdk.ERROR_NONE status code.
  
  On any failure, the failure code is provided via StatusListener.onFail(int errorCode, Bundle errorData).
  
  Note: Please refer SpaySdk.COMMON_STATUS_TABLE in detail.
  

  Throws:

  NullPointerException - Thrown if cardInfo or StatusListener is null.

  IllegalArgumentException - Thrown if cardInfo.getCardMetaData() does not have EXTRA_PAY_OPERATION_TYPE and EXTRA_TRANSACTION_TYPE.

  Since:

  API Level 1.1

• startInAppPayWithCustomSheet

  public void startInAppPayWithCustomSheet(CustomSheetPaymentInfo customSheetPaymentInfo, PaymentManager.CustomSheetTransactionInfoListener listener)

  API to request online(in-app) payment with Samsung Pay.
  Partner app can use this API to make in-app purchase using Samsung Pay from their application with custom payment sheet.
  You can refer to startInAppPay(PaymentInfo, TransactionInfoListener) in case of normal payment sheet.

   
  
      // Create {@link CustomSheet} to contain SheetControls.
      CustomSheet sheet = new CustomSheet();
  
      // Make SheetControls you want and add to custom sheet.
      // Each SheetControl is located in sequence.
      // There must be a AmountBoxControl and it must be located on last.
  
      // Add {@link AddressControl} on custom payment sheet.
      sheet.addControl(new AddressControl());
  
      // Add {@link PlainTextControl} on custom payment sheet.
      sheet.addControl(new PlainTextControl());
  
      // Add {@link SpinnerControl} on custom payment sheet.
      sheet.addControl(new SpinnerControl());
  
      // Add {@link AmountBoxControl} on custom payment sheet.
      sheet.addControl(new AmountBoxControl());
  
      // Create {@link CustomSheetPaymentInfo} with in-app details
      CustomSheetPaymentInfo customPaymentReq = new CustomSheetPaymentInfo.Builder()
              .setMerchantId( merchantId )
              .setMerchantName( merchantName )
              .setOrderNumber( orderNumber ) // The allowed characters are [A-Z][a-z][0-9,-] & up to 36 characters
              .setPaymentProtocol( protocol )
              .setAddressInPaymentSheet( addressInPaymentSheet )
              .setAllowedCardBrands ( brandList )
              .setCardHolderNameEnabled ( isCardHolderNameEnabled )
              .setCustomSheet( sheet )
  
      // Set the serviceId which is assigned by the Samsung Pay Developer during on boarding.
      String serviceId = "sampleServiceId";
      Bundle bundle = new Bundle();
      bundle.putString(SamsungPay.PARTNER_SERVICE_TYPE, SamsungPay.ServiceType.INAPP_PAYMENT.toString());
  
      PartnerInfo pInfo = New PartnerInfo(serviceId, bundle);
  
      // Create {@link PaymentManager#PaymentManager(Context, PartnerInfo)}
      PaymentManager paymentManger = new PaymentManager(this, pInfo);
  
      // Set {@link CustomSheetTransactionInfoListener}
      PaymentManager.CustomSheetTransactionInfoListener transactionListener = new PaymentManager
      .CustomSheetTransactionInfoListener {
          @Override
          public void onCardInfoUpdated(CardInfo selectedCardInfo, CustomSheet customSheet) {
              Log.d(TAG, "onCardInfoUpdated");
              // Called when the user changes the card in Samsung Pay.
              // newly selected cardInfo is passed and partner app
              // can update transaction amount based on new card (if needed)
          }
  
          @Override
          public void onSuccess(CustomSheetPaymentInfo customSheetPaymentInfo,
              String paymentCredential,  Bundle extraPaymentData) {
              Log.d(TAG, "Transaction : successfully received paymentCredential from Samsung Pay");
              // Called when Samsung Pay able to create in-app cryptogram successfully
              // Partner app will send this cryptogram to Partner server/Payment Gateway and complete
              // in-app payment.
          }
  
          @Override
          public void onFailure(int errorCode, Bundle errorData) {
              Log.e(TAG, "onFail callback is called, errorCode: " + errorCode);
              // To get more reason of the failure,
              // check some extra error codes in the errorData bundle such as SamsungPay.EXTRA_ERROR_REASON (if provided).
          }
      }
  
      // Execute startInAppPayWithCustomSheet to show custom payment sheet.
      try {
          paymentManger.startInAppPayWithCustomSheet(customPaymentReq, transactionListener);
      } catch (NullPointerException e | IllegalStateException e | IllegalArgumentException e) {
          e.printStackTrace();
      }
   
   

  Parameters:

  customSheetPaymentInfo - Custom sheet and payment information from partner app(merchant app).

  listener - Callback through which the result is provided.
  On success, PaymentManager.CustomSheetTransactionInfoListener.onSuccess(CustomSheetPaymentInfo, String, Bundle) is invoked with payment credential.
  PaymentManager.CustomSheetTransactionInfoListener.onCardInfoUpdated(CardInfo, CustomSheet) is invoked when user changes the card on the payment sheet in Samsung Pay.
  
  On any failure, the failure error code and error data are provided via PaymentManager.CustomSheetTransactionInfoListener.onFailure(int, Bundle).
  The failure code can be one of the following codes with bundle data:

  Status
  SpaySdk.ERROR_USER_CANCELED (-7)
  SpaySdk.ERROR_DUPLICATED_SDK_API_CALLED (-105)
  ERROR_NOT_READY_PAYMENT (-108)
  ERROR_TRANSACTION_TIMED_OUT (-111)
  ERROR_TRANSACTION_CLOSED (-112)
  ERROR_CARD_NOT_SUPPORTED_ONLINE_PAY (-402)
  ERROR_ADDRESS_UPDATED_TIME_OUT (-113)
  ERROR_MAKING_SHEET_FAILED (-115)

  Note: Please refer SpaySdk.COMMON_STATUS_TABLE for other status.
  

  Throws:

  NullPointerException - Thrown if parameters are null.

  IllegalStateException - Thrown if Samsung Pay SDK Service is not available.

  IllegalArgumentException - Thrown if mandatory custom sheet information and payment information values are not set.

  Since:

  API Level 1.3