Class PaymentManager

java.lang.Object
com.samsung.android.sdk.samsungpay.v2.SpaySdk
com.samsung.android.sdk.samsungpay.v2.payment.PaymentManager

public final class PaymentManager extends SpaySdk
This class provides APIs for payment related operations (example: in-app payment).
Partner (Merchants and other third party) applications can use these APIs to perform variety of payment operations.

For instance, partner apps can:
- Request in-app payment
- Start Simple Pay on Samsung Pay
- Fetch available cards on Samsung Pay for payment
Since:
API Level 1.1
  • Field Details

    • EXTRA_PAY_OPERATION_TYPE

      public static final String EXTRA_PAY_OPERATION_TYPE
      Key to represent start Simple Pay operation type.
      The possible values are:
      PAY_OPERATION_TYPE_PAYMENT
      PAY_OPERATION_TYPE_REFUND
      See Also:
    • PAY_OPERATION_TYPE_PAYMENT

      public static final String PAY_OPERATION_TYPE_PAYMENT
      Indicates start Simple Pay option to make payment.
      See Also:
    • PAY_OPERATION_TYPE_REFUND

      public static final String PAY_OPERATION_TYPE_REFUND
      Indicates start Simple Pay option to make refund.
      This is for Korean issuers only.
      See Also:
    • EXTRA_TRANSACTION_DATE

      public static final String EXTRA_TRANSACTION_DATE
      Key to represent transaction date value when start Simple Pay to refund.
      This is for Korean issuers only.

      Example value mapped with this key : 201906211428(yyyyMMddHHmm)
      See Also:
    • EXTRA_TRANSACTION_NUMBER

      public static final String EXTRA_TRANSACTION_NUMBER
      Key to represent transaction number value when start Simple Pay to refund.
      This is for Korean issuers only.

      Maximum length is 14.
      See Also:
    • EXTRA_TRANSACTION_TYPE

      public static final String EXTRA_TRANSACTION_TYPE
      Key to represent transaction type.
      The possible values are:
      TRANSACTION_TYPE_MST
      TRANSACTION_TYPE_NFC
      See Also:
    • TRANSACTION_TYPE_MST

      public static final int TRANSACTION_TYPE_MST
      Indicates that transaction type is MST.
      See Also:
    • TRANSACTION_TYPE_NFC

      public static final int TRANSACTION_TYPE_NFC
      Indicates that transaction type is NFC.
      See Also:
    • ERROR_NOT_READY_PAYMENT

      public static final int ERROR_NOT_READY_PAYMENT
      Indicates that online payment is not ready to complete because of various types of errors.
      For example, internal error, unexpected error from Samsung Pay app, and so on.
      See Also:
    • EXTRA_LOGO_IMAGE_URL

      public static final String EXTRA_LOGO_IMAGE_URL
      Key to represent the URL of partner logo image on Simple Pay.
      Image width: Max. 330 pixels.
      Image height: 72 pixels.
      See Also:
    • EXTRA_KEY_TEST_MODE

      public static final String EXTRA_KEY_TEST_MODE
      Key to represent PG test mode to prevent payment transaction being processed.
      If the value is true, Samsung-PG interface server redirects payment info to test PG server.
      This is only for PG-Indirect model.
      Since:
      API Level 2.3
      See Also:
    • EXTRA_KEY_ADDITIONAL_DATA

      public static final String EXTRA_KEY_ADDITIONAL_DATA
      Key to represent additional data.
      Partner can use this key to put tagged data to a bundle before sending to Samsung Pay.
      Since:
      API Level 2.4
      See Also:
    • EXTRA_KEY_CARD_BRAND_FILTER

      public static final String EXTRA_KEY_CARD_BRAND_FILTER
      Key to represent request card filter list.
      Partner can use this key to put filter into bundle for requestCardInfo(Bundle, CardInfoListener)
      Since:
      API Level 2.7
      See Also:
    • ERROR_TRANSACTION_TIMED_OUT

      public static final int ERROR_TRANSACTION_TIMED_OUT
      Indicates that online payment processing has timed out.
      See Also:
    • ERROR_TRANSACTION_CLOSED

      public static final int ERROR_TRANSACTION_CLOSED
      Indicates that transaction UI has closed.
      See Also:
    • ERROR_ADDRESS_UPDATED_TIME_OUT

      public static final int ERROR_ADDRESS_UPDATED_TIME_OUT
      Indicates that online payment address updating is timed out.
      See Also:
    • ERROR_INTERNAL_ADDRESS_UPDATED

      public static final int ERROR_INTERNAL_ADDRESS_UPDATED
      Indicates address update internal error.
      See Also:
    • ERROR_MAKING_SHEET_FAILED

      public static final int ERROR_MAKING_SHEET_FAILED
      Indicates that making sheet has failed.
      See Also:
    • ERROR_SPAY_RESET

      public static final int ERROR_SPAY_RESET
      Indicates that spay will be reset.
      See Also:
    • ERROR_SHIPPING_ADDRESS_INVALID

      public static final int ERROR_SHIPPING_ADDRESS_INVALID
      The merchant can call the updateAmountFailed(int) or updateSheet(CustomSheet, int, String) API with this error when the shipping address shared by Samsung Pay to the merchant is invalid.
      See Also:
    • ERROR_SHIPPING_ADDRESS_UNABLE_TO_SHIP

      public static final int ERROR_SHIPPING_ADDRESS_UNABLE_TO_SHIP
      The merchant can call the updateAmountFailed(int) or updateSheet(CustomSheet, int, String) API with this error when the shipping address shared by Samsung Pay is not available for delivery by the merchant.
      See Also:
    • ERROR_SHIPPING_ADDRESS_NOT_EXIST

      public static final int ERROR_SHIPPING_ADDRESS_NOT_EXIST
      The merchant can call the updateAmountFailed(int) or updateSheet(CustomSheet, int, String) API with this error when the shipping address shared by Samsung Pay does not exist.
      See Also:
    • ERROR_BILLING_ADDRESS_INVALID

      public static final int ERROR_BILLING_ADDRESS_INVALID
      The merchant can call the updateAmountFailed(int) or updateSheet(CustomSheet, int, String) API with this error when the billing address shared by Samsung Pay to the merchant is invalid.
      See Also:
    • ERROR_BILLING_ADDRESS_NOT_EXIST

      public static final int ERROR_BILLING_ADDRESS_NOT_EXIST
      The merchant can call the updateAmountFailed(int) or updateSheet(CustomSheet, int, String) API with this error when the billing address shared by Samsung Pay does not exist.
      See Also:
    • CUSTOM_MESSAGE

      public static final int CUSTOM_MESSAGE
      The merchant can call the updateSheet(CustomSheet, int, String) API with this error when it wants to Display a custom error message on CustomSheet.
      See Also:
    • ERROR_CARD_NOT_SUPPORTED_ONLINE_PAY

      public static final int ERROR_CARD_NOT_SUPPORTED_ONLINE_PAY
      Indicates that this card does not support online pay.
      Since:
      API Level 2.5
      See Also:
  • Constructor Details

    • PaymentManager

      public PaymentManager(android.content.Context context, PartnerInfo partnerInfo)
      Constructor of PaymentManager class.
      The caller should set a valid serviceId in PartnerInfo. PartnerInfo is passed to Samsung Pay for caller verification.
       
          Context ct = activity;
          // or Context ct = service;
      
          // 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(ct, pInfo);
       
       
      Parameters:
      context - Activity Context or Service Context.
      partnerInfo - Partner information.
      Throws:
      NullPointerException - If the context or partnerInfo is null.
      Since:
      API Level 1.1
  • 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