Package com.thalesgroup.gemalto.d1.d1pay

Interface D1PayWallet

public interface D1PayWallet

This is the entry point to manage the D1 Pay wallet.

Since:

2.0.0

Method Summary

Modifier and Type	Method	Description
void	addDigitalCard(String cardID, D1Task.Callback<Void> callback)	Adds a digital card of a given cardID for D1 Pay.
void	getCachedCardMetadata(String cardID, D1Task.Callback<CardMetadata> callback)	This API is designed to retrieve the 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 the default D1 Pay digital card.
void	getDigitalCard(String cardID, D1Task.Callback<D1PayDigitalCard> callback)	Retrieves the digital card of a given cardID for D1 Pay.
void	getDigitalCardList(D1Task.Callback<Map<String,D1PayDigitalCard>> callback)	Retrieves the list of D1 Pay digital cards.
void	getTransactionHistory(String cardID, D1Task.Callback<TransactionHistory> callback)	Retrieves the digital card transaction history of a given cardID for D1 Pay.
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)	When Mobile Payment Application (MPA) receives an unrecoverable error D1Exception.ErrorCode.ERROR_D1PAY_UNRECOVERABLE, it is recommended to call this API 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 the payment experience.
void	startManualModePayment(String cardID)	To start a proximity payment from the application.
void	unRegisterD1PayDataChangedListener()	Unregisters `D1PayDataChangedListener` that has been registered previously.
void	unsetDefaultPaymentDigitalCard(D1Task.Callback<Void> callback)	Removes the current default D1 Pay digital card.
void	updateDigitalCard(String cardID, D1PayDigitalCard d1PayDigitalCard, CardAction cardAction, D1Task.Callback<Boolean> callback)	Updates the digital card status of cardID for D1 Pay.

Method Details

registerD1PayDataChangedListener

void registerD1PayDataChangedListener(@NonNull
 D1PayDataChangedListener listener)

Registers to receive notification for the following events:

• Digitization is completed. It is in the `Active` state.
• The state of D1 Pay digital card is updated.
• Virtual/physical card is renewed.

Note: Only foreground applications will be notified.

Therefore, the application should update the token status when it receives this callback, and 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 of a given cardID for D1 Pay. If this is the first card, it will be automatically be set as the default card for payment.

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

The issuer application no longer waits for a push notification as there will be no push notification sent after the addDigitalCard() API invocation. Therefore, it is no longer necessary for integrators to register a D1PayDataChangedListener using registerD1PayDataChangedListener(com.thalesgroup.gemalto.d1.d1pay.D1PayDataChangedListener). However, to maintain backward compatibility, integrators can still rely on the `onDataChanged` callback within registerD1PayDataChangedListener(com.thalesgroup.gemalto.d1.d1pay.D1PayDataChangedListener).

Parameters:

cardID - The card identifier.

callback - Status of the digitization. As there will be no push notifications sent, the callback will not return the status of the digitization immediately. The returned argument of D1Task.Callback.onSuccess(Object) is always a null value when the digitization 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 if the following conditions are satisfied after a successful card renewal:

• User is logged in.
• Card renewal is successful.
• There is no ongoing contactless payment.
• There is at least one card in the wallet.
• Card nenewal is performed after the 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 end user is not logged in or a user login is required, resynchronisation of the card ID will be skipped even if it is required but the D1 Pay digital card state is retrieved for a given cardID.

Parameters:

cardID - The card identifier.

callback - The callback for the CardDigitizationState state. The returned argument of D1Task.Callback.onSuccess(Object) is a non-null value 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 that D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND error code may 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

When Mobile Payment Application (MPA) receives an unrecoverable error D1Exception.ErrorCode.ERROR_D1PAY_UNRECOVERABLE, it is recommended to call this API 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 request 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 - Indicates if this is a forced replenishment.

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

completionCallback - The callback for the replenishment result. The returned argument of D1Task.Callback.onSuccess(Object) is always a null value 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 D1Task.Callback.onSuccess(Object) is always a null value 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 the digital card of a given cardID for D1 Pay.

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

• User is logged in.
• Card renewal is successful.
• There is no ongoing contactless payment.
• There is at least one card in the wallet.
• Card Renewal is performed after the 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 end user is not logged in or a user login is required, resynchronisation of the card ID will be skipped even if it is required but the D1 Pay digital card is retrieved for a given cardID.

Parameters:

cardID - The card identifier.

callback - The callback for the result. The returned argument of D1Task.Callback.onSuccess(Object) is a non-null value 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 that D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND error code may be returned if this API is invoked using old card ID after resynchronisation of the card ID is successful.

getDigitalCardList

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

Retrieves the list of D1 Pay digital cards.

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

• User is logged in.
• Card renewal is successful.
• There is no ongoing contactless payment.
• There is at least one card in the wallet.
• Card Renewal is performed after the 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 end user is not logged in or user login is required, resynchronisation of the card ID will be skipped even if it is required but the list of D1 Pay digital cards is retrieved.

Parameters:

callback - The callback for the result which contains the map of cardID and D1PayDigitalCard. The returned argument of D1Task.Callback.onSuccess(Object) is a non-null value 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 the default D1 Pay digital card.

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

Parameters:

callback - The result containing cardID if the default card has been set previously, or a null value 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 a null value 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)

Removes 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 a null value 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)

Updates the digital card status of cardID for D1 Pay.

• D1Task.login(byte[], D1Task.Callback) is required before invoking this API.
• is required on initialization of 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 a non-null value 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 a 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 manually select a card .

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 the payment for every transaction request and disable it once the transaction has been completed or cancelled.

Parameters:

allowTransaction - This is set to false to forbid contactless payment.

Since:

2.2.0

getTransactionHistory

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

Retrieves the digital card transaction history of a given cardID for D1 Pay.

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

Parameters:

cardID - The card identifier.

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

• D1Exception.ErrorCode.ERROR_CORE
Which may be due to storage (unlikely) or network failure.
• D1Exception.ErrorCode.ERROR_CARD_NOT_FOUND
Which may 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 the payment experience. D1PaymentExperience.ONE_TAP_ENABLED is set as the default payment experience. The application can change the mode to allow the 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 the 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 metadata of the cached card is not synchronised with the backend, this API may not return the 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 utilise this API.

Parameters:

cardID - The card identifier.

callback - The callback to inform the result. When this API succeeds, the returned argument of the D1Task.Callback.onSuccess(Object) is always a null value.
Possible errors:

• D1Exception.ErrorCode.ERROR_D1PAY_NO_CARD_METADATA_CACHE

Since:

4.0.0