Replenish payment keys

Overview

Visa uses Limited Use Key (LUK) credentials that remain valid for a limited period, such as 10 days or 1 month.

If a LUK expires before any payment, the D1 SDK cannot replenish it without end user authentication. The LUK value is protected in the Android Keystore. Visa also requires the previous LUK data during replenishment to authorize retrieval of new credentials.

Mastercard uses Single Use Key (SUK) credentials for each transaction. Replenish SUK credentials when the remaining number is low.

Although this scenario is rare, the issuer application must handle it for end users who rarely open the application. Implement this check during issuer application startup, after the D1 SDK is initialized and before displaying the digital card list.

Flow

Replenishment with push notification

Push notifications are data messages handled silently by the issuer application. When the issuer application receives a push notification, it must forward it to the D1 SDK.

The D1 SDK processes the message and returns the message type PushResponseKey.TYPE_REPLENISHMENT and the related cardId when no error occurs. This indicates that the card requires replenishment.

The issuer application should then call the replenish API with isForced set to true.

See Message Handling.

Digital card list

D1PayDigitalCard provides the isReplenishmentNeeded() flag to indicate whether the issuer application must call the replenish API. If this method returns true, call replenish with isForced set to false.

See Digital card list.

SDK

This example shows how to trigger replenishment.

Android Java

private void replenishment(String cardIdToReplenish, boolean isForced) {
    /**
     * Visa may require device authentication during replenishment.
     * The issuer application may need to check whether it is in the
     * background or foreground.
     */
    DeviceAuthenticationCallback cvmCallback = new DeviceAuthenticationCallback() {
        @Override
        public void onSuccess() {
            // User authentication succeeded.
        }

        @Override
        public void onFailed() {
            // User authentication failed. The issuer application may ask the
            // end user to retry.
        }

        @Override
        public void onHelp(int fpCode, @NonNull CharSequence fpDetail) {
            // For biometric only.

            // The issuer application may show the fpDetail message to the
            // end user.
        }

        @Override
        public void onError(int fpErrorCode) {
            // For biometric only.

            // An error occurred during biometric authentication, for example
            // if the wrong finger is used too many times and the sensor locks.
            // Depending on fpErrorCode, the issuer application should guide
            // the end user.
        }
    };

    if (cardIdToReplenish != null) {
        D1PayWallet d1PayWallet = d1Task.getD1PayWallet();
        d1PayWallet.replenish(cardIdToReplenish, isForced, cvmCallback,
            new D1Task.Callback<Void>() {
                @Override
                public void onSuccess(Void ignored) {
                    // Replenishment completed.
                }

                @Override
                public void onError(@NonNull D1Exception exception) {
                    // Refer to the D1 SDK error management section.
                }
            });
    }
}