SDK Programming Guide
  • 3.3.12 Updating additional service for registered card
  • Partner apps: Issuer (HK-only feature)

  • The updateAdditionalService() API method of the CardManager class is used to update information about a specific card on Samsung Pay.

    Currently this API is available for the HK Octopus Transit Card (OCL card) only. Essentially, the partner app requests a service with proper card data and Samsung Pay shows an authentication sheet for the operation. Once the user authenticates, the partner app triggers the approved operation through its server.

  • For regions other than Hong Kong, this API currently returns an "ERROR_NOT_ALLOWED" error.
  • For HK only, these services are available for the OCL card:
    • ADDITIONAL_SERVICE_ONLINE_PAY : Request authentication for online payment with OCL card
    • ADDITIONAL_SERVICE_CHARGE : Request authentication for charging OCL card
    • ADDITIONAL_SERVICE_WITHDRAW : Request authentication for a withdrawal from OCL card
    • ADDITIONAL_SERVICE_AAVS : Request authentication for registration AAVS service
  • The result is delivered to CardListener, which provides the following events:
    • onSuccess() - called when the request succeeds; provides the status of the request and extra bundle data related to the request.
    • onFail() - called when the request fails; returns the error code and extra bundle data related to the request.
  • The following example demonstrates the use of the updateAdditionalService() API method.
  • CardManager cardManager = new CardManager(ct, pInfo);
    Bundle bundle = new Bundle();
    setPartnerServiceType(bundle);
    
    // Use-Case : Update additional service for Transit Card.
    TransitCard transitCard = new TransitCard();
    
    // #1 : Set Card Reference ID
    // Partner can get this ID through getAllCards() API.
    transitCard.setCardReferenceId("abcdef");
    
    // #2 : Set Transaction ID
    // Partner can get this ID through their server.
    transitCard.setTransactionId("123456789ABCDEF");
    
    // #3 : Set Service Operation Type
    transitCard.setAdditionalServiceType(TransitCard.ADDITIONAL_SERVICE_CHARGE);
    
    // #4 : Set Service Data (If needed)
    // Partner can set additional data like amount or balance, if partner wants.
    transitCard.setAdditionalServiceData("300.00");
    
    // #5 : Set Service Description (This message will be shown in authentication view)
    // Partner can set partner's own description, if partner wants.
    transitCard.setAdditionalServiceDescription("Leave message to be shown in authentication view.");
    
    cardManager.updateAdditionalService(transitCard, new CardListener() {
    		@OOverride
    		public void onSuccess(int status, Bundle data) {
    			Log.d(TAG, "onSuccess callback is called");
    		}
    
    		@OOverride
    		public void onFail(int error, Bundle errorData) {
    			Log.d(TAG, "onFail callback is called");
    		}
    });