Package com.thalesgroup.gemalto.d1.d1pay

Interface D1PayWallet

public interface D1PayWallet

Entry point to manage the D1Pay wallet

Since:

2.0.0

Method Summary

Modifier and Type	Method	Description
void	addDigitalCard(String cardID, D1Task.Callback<Void> callback)	Adds a digital card for a given cardID for D1 Pay.
void	getCachedCardMetadata(String cardID, D1Task.Callback<CardMetadata> callback)	This API is designed to retrieve fundamental cached card metadata that is used during D1 Pay transactions.
void	getCardDigitizationState(String cardID, D1Task.Callback<CardDigitizationState> callback)	Gets the digital card state of a given cardID for D1 Pay.
void	getDefaultPaymentDigitalCard(D1Task.Callback<String> callback)	Retrieves the card identifier cardID of default D1 Pay digital card.
void	getDigitalCard(String cardID, D1Task.Callback<D1PayDigitalCard> callback)	Retrieves D1 Pay digital card for a given cardID.
void	getDigitalCardList(D1Task.Callback<Map<String,D1PayDigitalCard>> callback)	Retrieves D1 Pay digital card list.
void	getTransactionHistory(String cardID, D1Task.Callback<TransactionHistory> callback)	Retrieves D1 Pay digital card's transaction history for a given cardID.
void	registerD1PayDataChangedListener(D1PayDataChangedListener listener)	Registers to receive notification for the following events: Digitization is completed.
void	replenish(String cardID, boolean isForced, DeviceAuthenticationCallback authCallback, D1Task.Callback<Void> completionCallback)	To replenish the given card identifier.
void	replenishODA(String cardID, D1Task.Callback<Void> callback)	For Visa only.
static void	reset(Context context)	It is recommended to call this API when the Mobile Payment Application (MPA) receives an unrecoverable error D1Exception.ErrorCode.ERROR_D1PAY_UNRECOVERABLE, in order to reset all the internal local data, and retry the operation.
void	setContactlessTransactionAllowed(boolean allowTransaction)	This API is used to enable contactless payment.
void	setDefaultPaymentDigitalCard(String cardID, D1Task.Callback<Void> callback)	Sets the DigitalizedCard as the default payment card.
void	setPaymentExperience(D1PaymentExperience experience)	This API is used to switch payment experience.
void	startManualModePayment(String cardID)	To start proximity payment from the application.
void	unRegisterD1PayDataChangedListener()	Unregisters D1PayDataChangedListener that has been registered previously
void	unsetDefaultPaymentDigitalCard(D1Task.Callback<Void> callback)	Remove the current default D1 Pay digital card.
void	updateDigitalCard(String cardID, D1PayDigitalCard d1PayDigitalCard, CardAction cardAction, D1Task.Callback<Boolean> callback)	Update D1 Pay digital card status for a cardID

Method Detail

registerD1PayDataChangedListener

void registerD1PayDataChangedListener(@NonNull
                                      D1PayDataChangedListener listener)

Registers to receive notification for the following events:

• Digitization is completed. It is in the Active state.
• D1Pay Digital Card state is updated.
• Virtual/Physical Card is renewed.

Note: Only foreground applications will be notified.

Therefore, the application should update the token status not only when receiving this callback but also when it launches or returns to the foreground.

Parameters:

listener - The callback to receive the notification from SDK.

unRegisterD1PayDataChangedListener

void unRegisterD1PayDataChangedListener()

Unregisters D1PayDataChangedListener that has been registered previously

See Also:

D1PayDataChangedListener

addDigitalCard

void addDigitalCard(@NonNull
                    String cardID,
                    @NonNull
                    D1Task.Callback<Void> callback)

Adds a digital card for a given cardID for D1 Pay. If this is the first card, it will be automatically set as the default card for payment.

D1Task.login(byte[], D1Task.Callback) is required before invoking this API.

Integrator must register listener on registerD1PayDataChangedListener(D1PayDataChangedListener) to receive notification when the operation is completed.

Parameters:

cardID - The card identifier.

callback - The callback for the intermediate result. As this API requires a push notification, the final status will be given on D1PayDataChangedListener. The returned argument of D1Task.Callback.onSuccess(Object) is always null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_NOT_LOGGED_IN
• D1Exception.ErrorCode.ERROR_NOT_AUTHORIZED
• D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE
• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_D1PAY
• D1Exception.ErrorCode.ERROR_D1PAY_NO_PUSH_TOKEN
• D1Exception.ErrorCode.ERROR_D1PAY_DIGITIZATION_COMPLETED
• D1Exception.ErrorCode.ERROR_D1PAY_DELETION_IN_PROGRESS
• D1Exception.ErrorCode.ERROR_D1PAY_MOBILE_GATEWAY
• D1Exception.ErrorCode.ERROR_D1PAY_PROVISIONING_SERVICE

getCardDigitizationState

void getCardDigitizationState(@NonNull
                              String cardID,
                              @NonNull
                              D1Task.Callback<CardDigitizationState> callback)

Gets the digital card state of a given cardID for D1 Pay.

This API will trigger the resynchronisation of the card id after a successful card renewal if the following conditions are satisfied:

• User is logged in.
• Card renewal is successful.
• Contactless Payment is not ongoing.
• There is at least one card exists in the wallet.
• Card Renewal is performed after last resynchronisation.
• Last resynchronisation was performed more than 30 minutes ago.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API. When user is not logged in or user login is required, resynchronisation of the card id will be skipped even if it is required but retrieves D1 Pay digital card state for a given cardID.

Parameters:

cardID - The card identifier.

callback - The callback for the CardDigitizationState state. The returned argument of the D1Task.Callback.onSuccess(Object) is non-null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_D1PAY_NOT_SUPPORTED
• D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE
• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_D1PAY
• D1Exception.ErrorCode.ERROR_D1PAY_DELETION_IN_PROGRESS
• D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND

It is possible D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND error code could be returned if this API is invoked using old cardId after resynchronisation of the card id is successful.

reset

static void reset(@NonNull
                  Context context)
           throws D1Exception

It is recommended to call this API when the Mobile Payment Application (MPA) receives an unrecoverable error D1Exception.ErrorCode.ERROR_D1PAY_UNRECOVERABLE, in order to reset all the internal local data, and retry the operation.

Parameters:

context - The application context.

Throws:

D1Exception - If the error occurs while resetting the local storage, it is recommended that the application to stop calling the D1 Pay API and ask for technical support with the detailed log.

See Also:

D1Exception.ErrorCode.ERROR_D1PAY_UNRECOVERABLE

replenish

void replenish(@NonNull
               String cardID,
               boolean isForced,
               @NonNull
               DeviceAuthenticationCallback authCallback,
               @NonNull
               D1Task.Callback<Void> completionCallback)

To replenish the given card identifier.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API.

Parameters:

cardID - The card identifier.

isForced - The replenishment is forced or not.

authCallback - The callback for device CVM (if needed). For VISA only!

completionCallback - The callback for the replenishment result. The returned argument of the D1Task.Callback.onSuccess(Object) is always null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND
• D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE
• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_D1PAY
• D1Exception.ErrorCode.ERROR_D1PAY_PROVISIONING_SERVICE
• D1Exception.ErrorCode.ERROR_D1PAY_VISA_REPLENISHMENT_AUTHENTICATION
• D1Exception.ErrorCode.ERROR_D1PAY_VISA_REPLENISHMENT_PREPARATION

replenishODA

void replenishODA(@NonNull
                  String cardID,
                  @NonNull
                  D1Task.Callback<Void> callback)

For Visa only.

Requests Offline Data Authentication (ODA) replenishment for the given card.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API.

Parameters:

cardID - The card identifier.

callback - The callback for the replenishment result. The returned argument of the D1Task.Callback.onSuccess(Object) is always null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND
• D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE
• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_D1PAY
• D1Exception.ErrorCode.ERROR_D1PAY_PROVISIONING_SERVICE
• D1Exception.ErrorCode.ERROR_D1PAY_NOT_SUPPORTED

Since:

2.2.0

getDigitalCard

void getDigitalCard(@NonNull
                    String cardID,
                    @NonNull
                    D1Task.Callback<D1PayDigitalCard> callback)

Retrieves D1 Pay digital card for a given cardID.

This API will trigger the resynchronisation of the card id after a successful card renewal if the following conditions are satisfied:

• User is logged in.
• Card renewal is successful.
• Contactless Payment is not ongoing.
• There is at least one card exists in the wallet.
• Card Renewal is performed after last resynchronisation.
• Last resynchronisation was performed more than 30 minutes ago.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API. When user is not logged in or user login is required, resynchronisation of the card id will be skipped even if it is required but retrieves D1 Pay digital card for a given cardID.

Parameters:

cardID - The card identifier.

callback - The callback for the result. The returned argument of the D1Task.Callback.onSuccess(Object) is non-null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND
• D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE
• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_D1PAY
• D1Exception.ErrorCode.ERROR_D1PAY_MOBILE_GATEWAY
• D1Exception.ErrorCode.ERROR_D1PAY_VISA_REPLENISHMENT_AUTHENTICATION

It is possible D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND error code could be returned if this API is invoked using old cardId after resynchronisation of the card id is successful.

getDigitalCardList

void getDigitalCardList(@NonNull
                        D1Task.Callback<Map<String,D1PayDigitalCard>> callback)

Retrieves D1 Pay digital card list.

This API will trigger the resynchronisation of the card id after a successful card renewal if the following conditions are satisfied:

• User is logged in.
• Card renewal is successful.
• Contactless Payment is not ongoing.
• There is at least one card exists in the wallet.
• Card Renewal is performed after last resynchronisation.
• Last resynchronisation was performed more than 30 minutes ago.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API. When the user is not logged in or user login is required, resynchronisation of the card id will be skipped even if it is required but retrieves D1 Pay digital list.

Parameters:

callback - The callback for the result which contains the map of cardID and D1PayDigitalCard. The returned argument of the D1Task.Callback.onSuccess(Object) is non-null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE
• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_D1PAY
• D1Exception.ErrorCode.ERROR_D1PAY_MOBILE_GATEWAY
• D1Exception.ErrorCode.ERROR_D1PAY_VISA_REPLENISHMENT_AUTHENTICATION

getDefaultPaymentDigitalCard

void getDefaultPaymentDigitalCard(@NonNull
                                  D1Task.Callback<String> callback)

Retrieves the card identifier cardID of default D1 Pay digital card.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API.

Parameters:

callback - The callback for the result containing cardID if default card has been set previously, or null if it has not been set.
Possible errors:

• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_D1PAY

setDefaultPaymentDigitalCard

void setDefaultPaymentDigitalCard(@NonNull
                                  String cardID,
                                  @NonNull
                                  D1Task.Callback<Void> callback)

Sets the DigitalizedCard as the default payment card.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API.

Parameters:

cardID - The card identifier

callback - The callback for result. The returned argument of the D1Task.Callback.onSuccess(Object) is always null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND
• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_D1PAY

unsetDefaultPaymentDigitalCard

void unsetDefaultPaymentDigitalCard(@NonNull
                                    D1Task.Callback<Void> callback)

Remove the current default D1 Pay digital card.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API.

Parameters:

callback - The callback for result. The returned argument of the D1Task.Callback.onSuccess(Object) is null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_D1PAY

updateDigitalCard

void updateDigitalCard(@NonNull
                       String cardID,
                       @NonNull
                       D1PayDigitalCard d1PayDigitalCard,
                       @NonNull
                       CardAction cardAction,
                       @NonNull
                       D1Task.Callback<Boolean> callback)

Update D1 Pay digital card status for a cardID

• D1Task.login(byte[], D1Task.Callback) is required before invoking this API.
• is required on initialization {@link D1Task#configure(D1Task.ConfigCallback, D1Params...)} before invoking this API.

Parameters:

cardID - The card identifier.

d1PayDigitalCard - The digital card received from getDigitalCard(String, D1Task.Callback) or getDigitalCardList(D1Task.Callback).

cardAction - The card action to be performed: active, suspend or delete.

callback - The callback is returned when the command is sent successfully to the server. The final status update is sent through push notification on D1PayDataChangedListener. The returned argument of the D1Task.Callback.onSuccess(Object) is non-null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_NOT_LOGGED_IN
• D1Exception.ErrorCode.ERROR_NOT_AUTHORIZED
• D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE
• D1Exception.ErrorCode.ERROR_CORE
• D1Exception.ErrorCode.ERROR_CARD

startManualModePayment

void startManualModePayment(@NonNull
                            String cardID)

To start proximity payment from the application.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API.

This API allows payment to be manually triggered when the end user selects a card manually.

Sets the listener by calling D1PayConfigParams.setManualModeContactlessTransactionListener(ContactlessTransactionListener) to listen to the transaction events:

• ContactlessTransactionListener.onAuthenticationRequired(VerificationMethod)
• ContactlessTransactionListener.onReadyToTap()
• ContactlessTransactionListener.onTransactionCompleted()
• ContactlessTransactionListener.onError(D1Exception)

Parameters:

cardID - The card identifier.

Since:

2.2.0

setContactlessTransactionAllowed

void setContactlessTransactionAllowed(boolean allowTransaction)

This API is used to enable contactless payment.

Contactless payment is enabled by default whenever the application runs in the foreground or when the service runs in the background. By using this API, the application can block contactless payment for any transaction, unless explicitly requested by the end user. Hence, the application needs to enable payment for every transaction request and disable it once the transaction has been completed or cancelled.

Parameters:

allowTransaction - set to false to forbid contactless payment.

Since:

2.2.0

getTransactionHistory

void getTransactionHistory(@NonNull
                           String cardID,
                           @NonNull
                           D1Task.Callback<TransactionHistory> callback)

Retrieves D1 Pay digital card's transaction history for a given cardID.

D1Task.login(byte[], D1Task.Callback) is not required before invoking this API.

Parameters:

cardID - The card identifier.

callback - The callback for the result. The returned argument of the D1Task.Callback.onSuccess(Object) is non-null when the process is successful.
Possible errors:

• D1Exception.ErrorCode.ERROR_CORE
Which can be due to storage (unlikely) or network failure
• D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND
Which can be due to card has not been digitization
• D1Exception.ErrorCode.ERROR_DEVICE_ENVIRONMENT_UNSAFE
• D1Exception.ErrorCode.ERROR_D1PAY_MOBILE_GATEWAY
• D1Exception.ErrorCode.ERROR_D1PAY_PROVISIONING_SERVICE

Since:

2.3.0

setPaymentExperience

void setPaymentExperience(D1PaymentExperience experience)

This API is used to switch payment experience. D1PaymentExperience.ONE_TAP_ENABLED is used by default. Application can change the mode to allow D1PaymentExperience.TWO_TAP_ALWAYS experience.

Parameters:

experience - mode of payment experience

Since:

2.3.0

getCachedCardMetadata

void getCachedCardMetadata(@NonNull
                           String cardID,
                           @NonNull
                           D1Task.Callback<CardMetadata> callback)

This API is designed to retrieve fundamental cached card metadata that is used during D1 Pay transactions. This API retrieves the last 4 digits of the PAN and Scheme to ensure that the information is always available. If the cached card metadata is not synchronised with the backend, this API may not return data for Card State, card expiry date and card artwork. If this API does not provide the required details, the integrator can call the GetCardMetadata API to update the local cache. Authentication or login credentials are not required to access and utilize this API.

Parameters:

cardID - The card identifier

callback - The callback for the result. When it succeeds, the returned argument of the D1Task.Callback.onSuccess(Object) is always null.
Possible errors:

• D1Exception.ErrorCode.ERROR_D1PAY_NO_CARD_METADATA_CACHE

Since:

4.0.0