Android

Step 1: Showing the Add to Wallet button

Your issuer application uses the Push Provisioning SDK to check whether the target xPay Wallet is supported on the device and whether a token already exists for the card. Based on the result, it shows or hides the Add to Wallet button.

Follow these wallet brand guidelines for using Add to Wallet in your issuer application:

• Google Pay https://developers.google.com/pay/api/android/guides/brand-guidelines

• Samsung Pay https://pay.samsung.com/developers/resource/brand

• Huawei Pay Support is available only for domestic schemes.

  Warning

  • Huawei Pay is not supported by international payment networks (for example, Mastercard and Visa). Only domestic schemes can be supported in specific cases. Check with Thales for the conditions of use.

  • Starting June 10, 2024, Google Wallet requires Android 9 or higher.

Using the last four digits of the PAN, the issuer application can retrieve the token for a card that is already provisioned to a wallet on the device (Samsung Pay and Google Pay for Android).

Each token includes:

• The token ID.

• The last four digits of the digital card (DPAN).

• The token state (digitization status).

Android 1.7.0+

OEMPayType type = OEMPayType.GOOGLE_PAY; // or OEMPayType.SAMSUNG_PAY
GetTokenInput input = new GetTokenInput("1234"); // last four digits of the physical card (FPAN)
PushProvisioning pushProvisioning = TPCManager.getInstance().getPushProvisioning(type);
pushProvisioning.getToken(input, new TPCSDKListener<Token>() {
    @Override
    public void onStart() {
    }
    @Override
    public void onSuccess(TPCResult<Token> result) {
        //Token can be retrieved using result.getResult().
        //result.getResult() will return null  if the OEM wallet does not have a corresponding token.
        //Token state is used as follows:
        if(result.getResult()==null || TextUtils.isEmpty(result.getResult().getState())){
            //API did not return a token.
            //Displays the "Add to GPay/SPay" button.
        }else{
            Token token = result.getResult();
            if(type==OEMPayType.GOOGLE_PAY){
                //For Google Pay.
                try {
                    int tokenState = Integer.parseInt(token.getState());
                    switch (tokenState){
                        case CardDigitizationStatus.GOOGLE_PAY_TOKEN_STATE_NEEDS_IDENTITY_VERIFICATION:
                            // Refer to Token life cycle management for Activate action.
                            // card is pending for ID&V. 
                            break;
                        case CardDigitizationStatus.GOOGLE_PAY_TOKEN_STATE_PENDING:
                        case CardDigitizationStatus.GOOGLE_PAY_TOKEN_STATE_SUSPENDED:
                        case CardDigitizationStatus.GOOGLE_PAY_TOKEN_STATE_ACTIVE:
                            //Card is already added.
                            break;
                        case CardDigitizationStatus.GOOGLE_PAY_TOKEN_STATE_UNTOKENIZED:
                            //Display "Add to GPay" button.
                            break;
                    }
                } catch (NumberFormatException e) {
                    //Handles the exception.
                }
            }else if(type==OEMPayType.SAMSUNG_PAY){
                //For Samsung Pay.
                String tokenState = token.getState();
                switch (tokenState){
                    case CardDigitizationStatus.SAMSUNG_PAY_PENDING_PROVISION:
                        // Refer to Token life cycle management for Activate action.
                        // card is pending for ID&V
                        break;
                    case CardDigitizationStatus.SAMSUNG_PAY_ACTIVE:
                    case CardDigitizationStatus.SAMSUNG_PAY_EXPIRED:
                    case CardDigitizationStatus.SAMSUNG_PAY_PENDING_ENROLLED:
                    case CardDigitizationStatus.SAMSUNG_PAY_SUSPENDED:
                    case CardDigitizationStatus.SAMSUNG_PAY_PENDING_ACTIVATION:
                        //Card is already added.
                        break;
                    case CardDigitizationStatus.SAMSUNG_PAY_DISPOSED:
                        //Displays the "Add to SPay" button.
                        break;
                }
            }
        }
    }
    @Override
    public void onError(TPCSDKException exception) {
        // specific for Samsung Pay
        Throwable exceptionCause = exception.getCause();
        if (exceptionCause != null && exceptionCause instanceof TPCSpayException) {
            // get more details of the error for Samsung Pay
            TPCSpayException spayException = (TPCSpayException) exceptionCause;
        }
    }
});

Android 1.6.0-

For Google Pay, the status of the token is as follows:

Google Pay State	Description
GOOGLE_PAY_TOKEN_STATE_NEEDS_IDENTITY_VERIFICATION	Card is digitized, pending for ID&V.
GOOGLE_PAY_TOKEN_STATE_PENDING	Card is digitized.
GOOGLE_PAY_TOKEN_STATE_SUSPENDED	Card is digitized.
GOOGLE_PAY_TOKEN_STATE_ACTIVE	Card is digitized.
GOOGLE_PAY_TOKEN_STATE_UNTOKENIZED	Card is not digitized.
CARD_IS_NOT_DIGITIZED	Card is not digitized.

For Samsung Pay, the status of the token is as follows:

Samsung Pay State	Description
SAMSUNG_PAY_PENDING_PROVISION	Card is digitized, pending for ID&V.
SAMSUNG_PAY_ACTIVE	Card is digitized.
SAMSUNG_PAY_EXPIRED	Card is digitized.
SAMSUNG_PAY_PENDING_ENROLLED	Card is digitized.
SAMSUNG_PAY_PENDING_ACTIVATION	Card is digitized.
SAMSUNG_PAY_SUSPENDED	Card is digitized.
SAMSUNG_PAY_DISPOSED	Card is not digitized.

Caution

• For Google Pay, if the card still appears as NOT_DIGITIZED after digitization, check that the issuer application is configured correctly in the TSP portal.

• For Samsung Pay, some issuers must register multiple ISSUER NAME values in the portal. This depends on the issuer application and/or TSP requirements. Make sure the ISSUER NAME value in the API matches the value registered in the portal. The API returns only exact matches.

• The getToken API is not supported for Huawei Pay. Use isCardDigitized to check the digitization status.

Step 2: Provisioning a request

On Android, the success result varies by OEMPayType. For Google Pay, the SDK returns a token ID. For Samsung Pay, it returns a Card object. For Huawei Pay, it returns a boolean.

Note

Since TPC SDK v1.9.0, Google Pay push provisioning can use the new API: addCard(Activity activity, CardInfo cardInfo, TPCSDKListener<T> listener).

CardInfo cardInfo = new CardInfo();
cardInfo.setScheme(scheme);
cardInfo.setEncryptedPayload(encryptedPayload);
cardInfo.setAuthorizationCode(authorizationCode);
cardInfo.setLast4PanDigits("1234"); // Set the last four digits of the PAN.
cardInfo.setIssuerAppId("TPC_ISSUER"); // Test issuer ID.
cardInfo.setCardType("DEBIT"); // Only for Samsung Pay
cardInfo.setProductId("PRODUCTID"); // Only for domestic schemes. Retrieve from the issuer CMS.

UserDetails userDetails = new UserDetails();
userDetails.setAddress1("Address line 1");
userDetails.setAddress2("Address line 2");
userDetails.setAdministrativeArea("state");
userDetails.setLocality("city name");			// name of city or town
userDetails.setCountryCode("SG");					// Set the country code.
userDetails.setPostalCode("828126"); 			// Set the postal code.
userDetails.setPhoneNumber("123456789"); 	// Set the phone number.
userDetails.setName("name");							// Set the person name at the address.
cardInfo.setUserDetails(userDetails);

//Since TPC SDK V1.9.0
Activity activity;

PushProvisioning pushProvisioning = TPCManager.getInstance().getPushProvisioning();

TPCSDKListener<String> addCardListenerGPay = new TPCSDKListener<String>() {
        @Override
        public void onStart() {
            // do something
        }

        @Override
        public void onSuccess(TPCResult<String> result) {
            Log.i("TAG", "Push Provision Successful with result : " + result.getResult());
        }

        @Override
        public void onError(TPCSDKException exception) {
            Log.e("TAG", "Push Provision Failed. Error : " + exception.getMessage());
        }
}

TPCSDKListener<Card> addCardListenerSPay = new TPCSDKListener<Card>() {
        @Override
        public void onStart() {
            // do something
        }

        @Override
        public void onSuccess(TPCResult<Card> result) {
            Card card = (Card)result.getResult();
            Log.d(TAG, "last4FPan: " + card.getLast4FPAN() +
                             "\nlast4DPan:" + card.getLast4DPAN() +
                             "\nApp2AppPayLoad: " + card.getApp2AppPayLoad() +
                             "\ntype: " + card.getType() +
                             "\nissuerName: " + card.getIssuerName() +
                             "\nid: " + card.getId() +
                             "\nstate: " + card.getState() +
                             "\nscheme: " + card.getCardScheme());
        }

        @Override
        public void onError(TPCSDKException exception) {
            Log.e("TAG", "Push Provision Failed. Error : " + exception.getMessage());
            if (exception.getExceptionType() == TPCSDKExceptionType.TPC_SPAY_APP_NEED_TO_UPDATE) {
                // Show a Samsung Pay update UI
                pushProvisioning.updateSamsungPay();
            } else if (exception.getExceptionType() == TPCSDKExceptionType.TPC_SPAY_APP_SETUP_NOT_COMPLETED) {
                // Show a Samsung Pay activation UI
                pushProvisioning.activateSamsungPay();
            } 
            Throwable exceptionCause = exception.getCause();
            if (exceptionCause != null && exceptionCause instanceof TPCSpayException) {
                // get more details of the error for Samsung Pay
                TPCSpayException spayException = (TPCSpayException) exceptionCause;
            }
        }
};

TPCSDKListener<Boolean> addCardListenerHPay = new TPCSDKListener<Boolean>() {
        @Override
        public void onStart() {
            // do something
        }

        @Override
        public void onSuccess(TPCResult<Boolean> result) {
            Log.i("TAG", "Push Provision Successful");
        }

        @Override
        public void onError(TPCSDKException exception) {
            Log.e("TAG", "Push Provision Failed. Error : " + exception.getMessage());
        }
};

TPCSDKListener addCardListener = null;
switch (oemPayType) {
    case OEMPayType.GOOGLE_PAY:
        addCardListener = addCardListenerGPay;
        break;
    case OEMPayType.SAMSUNG_PAY:
        addCardListener = addCardListenerSPay;
        break;
    case OEMPayType.HUAWEI_PAY:
        addCardListener = addCardListenerHPay;
        break;
}

try {
  if (oemPayType == OEMPayType.GOOGLE_PAY) {
    // Since TPC SDK V1.9.0
    pushProvisioning.addCard(activity, cardInfo, addCardListener);
  } else {
    pushProvisioning.addCard(cardInfo, addCardListener);
  }
} catch (TPCSDKException e) {
    e.printStackTrace();
}

// When the issuer application receives onActivityResult from the Google Pay SDK, pass it to the SDK to handle the result.
@Override
public void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    pushProvisioning.handleWalletResult(requestCode, resultCode, data);
}

// When the issuer application receives onNewIntent from Huawei Pay, pass the intent to the SDK to handle the result.
@Override
protected void onNewIntent(Intent intent) {
    pushProvisioning.handleWalletResult(intent);
}