Push Provisioning

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-

CardInfo cardInfo = new CardInfo();
cardInfo.setScheme(scheme);
cardInfo.setEncryptedPayload(encryptedPayload);
cardInfo.setLast4PanDigits(last4DigitsOfPAN); // Only for Samsung Pay

TPCManager.getInstance().getPushProvisioning()
	.isCardDigitized(cardInfo, new TPCSDKListener<CardDigitizationStatus>() {
    @Override
    public void onStart() {
        //On Start 
    }

    @Override
    public void onSuccess(TPCResult<CardDigitizationStatus> result) {
        if (result != null) {
          	CardDigitizationStatus digitizedStatus = result.getResult();

            if (digitizedStatus.getOemPayType() == OEMPayType.GOOGLE_PAY) {
                int cardState = digitizedStatus.getGpayDigitizationStatus();
                String tokenReferenceId = digitizedStatus.getTokenReferenceId();

                if (cardState == CardDigitizationStatus.GOOGLE_PAY_TOKEN_STATE_NEEDS_IDENTITY_VERIFICATION)
                    // card is pending for ID&V
                } else if (cardState == CardDigitizationStatus.CARD_IS_NOT_DIGITIZED) {
                    // card not added
                } else {
                    // card added
                }
            }
          
            if (digitizedStatus.getOemPayType() == OEMPayType.HUAWEI_PAY) {
                Boolean isCardDigitized = cardDigitizationStatus.getHpayDigitizationStatus();
                String hPayDeviceId = cardDigitizationStatus.getHPayDeviceId();
            }
            
          	if (digitizedStatus.getOemPayType() == OEMPayType.SAMSUNG_PAY) {
                String cardState = digitizedStatus.getSpayDigitizationStatus(); 
            }
        }
    }

    @Override
    public void onError(TPCSDKException exception) {
        Log.e("TAG", "On Error in card digitized status");
    }
});

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 Samsung Pay, it returns a Card object. For Huawei Pay, it returns a Boolean. For Google Pay, SDK 2.0.0 and later return a GoogleProvisioningResult, which contains the token ID when available.

Wallet	Success result
Samsung Pay	Card
Google Pay	GoogleProvisioningResult
Huawei Pay	Boolean

Android 2.0.0+

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.
cardInfo.setBounceProvisioned(true); // Only for Google Pay

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 V2.0.0
Activity activity;

PushProvisioning pushProvisioning;
try {
    pushProvisioning = TPCManager.getInstance().getPushProvisioning();
} catch (TPCSDKException e) {
    e.printStackTrace();
    return;
}

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

        @Override
        public void onSuccess(TPCResult<GoogleProvisioningResult> result) {
            GoogleProvisioningResult provisioningResult = result.getResult();
            Log.i("TAG", "Push Provision Successful with token ID: "
                    + provisioningResult.getTokenID());
            // Optionally can check the following
            if (!provisioningResult.isCardSavedToGoogle()) {
                Log.w("TAG", "Google Pay did not save the card. Status code: "
                    + provisioningResult.googleCardSavedStatusCode());
            }
        }

        @Override
        public void onError(TPCSDKException exception) {
            logGoogleProvisioningDiagnostic(exception.getAdditionalData());
        }
};

private void logGoogleProvisioningDiagnostic(final Object additionalData) {
        if (additionalData instanceof GoogleProvisioningResult) {
            final GoogleProvisioningResult result = (GoogleProvisioningResult) additionalData;
            Log.w(TAG, "Google provisioning diagnostic. Token Id: " + result.getTokenID()
                    + ", cardSaved: " + result.isCardSavedToGoogle()
                    + ", cardSavedStatusCode: " + result.getGoogleCardSavedStatusCode());
        }
    }

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 GOOGLE_PAY:
        addCardListener = addCardListenerGPay;
        break;
    case SAMSUNG_PAY:
        addCardListener = addCardListenerSPay;
        break;
    case HUAWEI_PAY:
        addCardListener = addCardListenerHPay;
        break;
}


if (oemPayType == OEMPayType.GOOGLE_PAY) {
  // Since TPC SDK V2.0.0
  pushProvisioning.addCard(activity, cardInfo, addCardListenerGPay);
} else {
  pushProvisioning.addCard(cardInfo, addCardListener);
}

// 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);
}

Android 2.0.0-

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;

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:
    case GOOGLE_PAY:
        addCardListener = addCardListenerGPay;
        break;
    case OEMPayType.SAMSUNG_PAY:
    case SAMSUNG_PAY:
        addCardListener = addCardListenerSPay;
        break;
    case OEMPayType.HUAWEI_PAY:
    case HUAWEI_PAY:
        addCardListener = addCardListenerHPay;
        break;
}

try {
    if (oemPayType == OEMPayType.GOOGLE_PAY) {
        // Since TPC SDK V1.9.0
        pushProvisioning.addCard(activity, cardInfo, addCardListenerGPay);
    } 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);
}