Android SDK - Offers Module

The offers module of the SDK exposes the functionality related to managing how offer campaigns are presented in the wallet and activated for eventual redemption against a purchase.

Use the methods described here to retrieve and display offer campaigns that are relevant to the user, filter offer lists based on user location, provide a means for the user to activate desired offers for redemption during a qualified transaction, or remove offers that are no longer desired.

Throughout this chapter, offer campaign denotes an available offer that has not been activated by the user, while just offer designates an offer that the user has activated to make it viable for redemption.

Implementation Description
UI Service com.paydiant.android.ui.service.offer.OfferRetrievalService
Core Service com.paydiant.android.core.facade.OfferManagerFacade

Set UI Package Offer Service Listeners

To invoke the callback methods returned by the Paydiant service in response to the methods invoked by the Offers module of the SDK, set an implementation of the applicable listener interfaces in the UI service class.

Item Description
Offer Retrieval Listener void setOfferRetrievalListener(IOfferRetrievalListener listener);
Listener Interfaces com.paydiant.android.ui.service.offer.IOfferRetrievalListener

or an overridden instance of com.paydiant.android.ui.service.offer.OfferRetrievalListenerAdapter
Remove Listener void removeListener();
Call this method to remove the offer retrieval listener and set it to null.

Retrieve Available Offer Campaign Summaries

Invoke this method to retrieve the set of offer campaign summaries that subscribed advertisers have made available to the wallet, filtered by the specifications in the request. A user can view the offer in the app and, if desired, activate the offer so it can be redeemed for qualifying purchases made through the mobile wallet.

This method retrieves only high-level overview information for each offer campaign, in order to reduce the initial payload. If a user taps a specific offer campaign of interest, retrieving the details of that campaign can then be performed at that time.

Item Description
UI Method void retrieveAvailableOfferCampaignsSummary(OfferCampaignSummaryFilterParameters campaignFilterParameters);

campaignFilterParameters - Specifies the attributes by which the list of returned offers are limited, such as status, geographical location, redeem period, category, maximum items, etc. in order to keep the list relevant and manageable.
Success void onAvailableOfferCampaignsSummaryRetrievalSuccess(OfferCampaignSummaryList offerCampaignSummaryList);

offerCampaignSummaryList - An array of OfferCampaignSummary instances representing overviews of the available offer campaigns that matched the filtering criteria specified in the request.
Failure void onOfferRetrievalError(PaydiantException exception);

exception - An instance of PaydiantException relative to the RETRIEVE_AVAILABLE_OFFERS_SUMMARY_EVENT, detailing the nature of the failure identified by relevant error codes.
Core Method OfferCampaignSummaryList retrieveAvailableOfferCampaignsSummary (OfferCampaignSummaryFilterParameters campaignFilterParameters);

campaignFilterParameters - Specifies the attributes by which the list of returned summaries are limited, such as status, geographical location, redeem period, category, maximum items, etc. in order to keep the list relevant and manageable. Returns raw output for the set of campaign summaries or relevant exception.

Errors

When retrieving offers, the following errors are applicable for the RETRIEVE_AVAILABLE_OFFERS_SUMMARY_EVENT:

Error Description
400 Offer retrieval failed.
500 An internal server error has occurred.

Retrieve Available Offer Campaign Detail with APs

Invoke this method to get the full content details for a specific offer campaign that is available, but not yet activated by the user. This level of information may be desirable when a user selects an available offer campaign from the list to see more information about it. The returned instance includes the set of acceptance partners for which the offer campaign is supported.

Since the returned offer campaign includes the higher level list of acceptance partners that support the offer, it is ideal for use with large national retail chains. For example, the list might include "National Drug Store" but not the thousands of individual locations nationwide.

Item Description
UI Method void retrieveAvailableOfferCampaignWithAcceptancePartners(String offerCampaignUri);

offerCampaignUri - The string value that uniquely identifies the offer campaign for which details are requested. This value can be obtained from the offerCampaignSummary instance returned in the Retrieve Available Offer Campaign Summaries call.
Success void onOfferWithAcceptancePartnersRetrievalSuccess(OfferCampaign offerCampaign);

domain.offer.offerCampaign - An instance of OfferCampaign containing all the details for the requested offer campaign, including the list of acceptance partners for which the offer is valid.
Failure void onOfferRetrievalError(PaydiantException exception);

exception - An instance of PaydiantException relevant to the RETRIEVE_AVAILABLE_OFFER_WITH_ACCEPTANCE_PARTNERS_EVENT, detailing the nature of the failure identified by relevant error codes.
Core Method OfferCampaign retrieveAvailableOfferCampaignWithAcceptancePartners (String offerCampaignUri);

offerCampaignUri - The string value that uniquely identifies the offer campaign for which details are requested. Returns raw output for the offer campaign or relevant exception.

Errors

When retrieving offers, the following errors are applicable for the RETRIEVE_AVAILABLE_OFFER_WITH_ACCEPTANCE_PARTNERS_EVENT:

Error Description
400 (BAD_REQUEST) Offer customer suspended.
Specified offer could not be located.
Specified offer no longer exists.
500 (INTERNAL_SERVER_ERROR) This error is returned for the following use cases:
An internal server error has occurred.
A processing error has occurred.
Transaction not supported.

Retrieve My Offer Detail with APs

Invoke this method to get the full content details for a specific offer that has been activated by the user in the wallet. The returned instance includes the set of AcceptancepPartners by which the offer is supported.

This call returns the list of higher level acceptance partners that support the offer, making it ideal for large national retail chains where the list might include "National Drug Store" but not every individual location.

Item Description
UI Method void retrieveOfferWithAcceptancePartners(String offerUri);

offerUri - The string value that uniquely identifies the requested offer. This value can be obtained from the offerSummary instance returned in the Retrieve My Offer Summaries call.
Success void onOfferWithAcceptancePartnersRetrievalSuccess(Offer offer);

domain.offer.offer - An instance of Offer containing all the details for the requested offer, including the list of acceptance partners for which the offer is valid.
Failure void onOfferRetrievalError(PaydiantException exception);
Core Method Offer retrieveOfferWithAcceptancePartners(String offerUri);

offerUri - The string value that uniquely identifies the requested offer. Returns raw output for the offer instance or relevant exception.

Errors

When retrieving offers, the following errors are applicable for the RETRIEVE_OFFER_WITH_ACCEPTANCE_PARTNERS_EVENT:

Error Description
400 (BAD_REQUEST) Offer customer suspended.
Specified offer could not be located.
Specified offer no longer exists.
500 (INTERNAL_SERVER_ERROR) This error is returned for the following use cases:
An internal server error has occurred.
A processing error has occurred.
Transaction not supported.

Retrieve My Offer Summaries

Invoke this method to obtain a set of only high level information for each offer that the user has activated in her wallet in order to make it available for redemption during a qualified purchase. As with other offer list retrievals, this request can specify filters to limit the returned set of offers.

Item Description
UI Method void retrieveOffersSummary (OfferSummaryFilterParameters offerSummaryFilterParameters);

offerSummaryFilterParameters - An instance of OfferSummaryFilterparameters.java class that specifies the attributes by which the list of returned offers are limited, such as status, geographical location, redeem period, category, maximum items, etc. in order to keep the list relevant and manageable.
Success void onOffersSummaryRetrievalSuccess(OfferSummaryList offerSummaryList);
offerSummaryList - An array of OfferSummary instances representing overviews of the offers that the user has activated which also matched the filtering criteria specified in the request.
Failure void onOfferRetrievalError(PaydiantException exception);

exception - An instance of PaydiantException relative to the RETRIEVE_OFFERS_SUMMARY_EVENT, detailing the nature of the failure identified by relevant error codes.
Core Method OfferSummaryList retrieveOffersSummary (OfferSummaryFilterParameters offerSummaryFilterParameters);

offerSummaryFilterParameters - Specifies the attributes by which the list of returned summaries are limited, such as status, geographical location, redeem period, category, maximum items, etc. in order to keep the list relevant and manageable. Returns raw output for the set of offer summaries or relevant exception.

Errors

When retrieving offers, the following errors are applicable for the RETRIEVE_OFFERS_SUMMARY_EVENT:

Error Description
400 Offer retrieval failed.
500 An internal server error has occurred.

Retrieve Campaigns Associated with a Coupon Code

Invoke this method to retrieve a list of campaigns associated with a coupon code.

Coupons are a customer-agnostic offer type in the Paydiant platform that can be distributed to and used by customers through a variety of channels such as email and social media. If a wallet user obtains a coupon code and wants to convert it to an active offer for use in mobile wallet transactions, this method will find the associated campaign data needed.

Coupon codes are not required to be unique for an issuing partner, so it is possible to have multiple campaigns returned. However, a coupon code can only be associated with one active campaign per acceptance partner, so it may be helpful to set filter parameters in the request that specify the AP (merchant) and start/end dates to optimize the match.

Item Description
UI Method void retrieveOfferCampaignSummaryUsingCouponCode(OfferCampaignSummaryFilterParameters OfferCampaignSummaryFilterParameters);

OfferCampaignSummaryFilterParameters - An object that specifies the coupon code for which campaigns are requested and any parameters by which the returned list is to be filtered, such as offer category, merchant, dates, etc.).
Success void onOfferCampaignSummaryRetrievalUsingCouponCodeSuccess(OfferCampaignSummaryList offerCampaignSummaryList);

offerCampaignSummaryList - An instance of OfferCampaignSummaryList containing the set of offer campaign summaries that match the coupon code and filtering criteria in the request.
Failure void onOfferRetrievalError(PaydiantException exception);

exception - An instance of PaydiantException relevant to the RETRIEVE_OFFER_CAMPAIGN_USING_COUPON_CODE_EVENT, detailing the nature of the failure identified by relevant error codes.
Core Method OfferCampaignSummaryList retrieveOfferCampaignSummaryUsingCouponCode (OfferCampaignSummaryFilterParameters OfferCampaignSummaryFilterParameters);

OfferCampaignSummaryFilterParameters - The object that encapsulates the coupon code and filtering parameters for which matching campaigns are requested. Returns raw output for the set of matching offer campaigns or relevant exception.

Errors

When retrieving offers, the following errors are applicable for the RETRIEVE_OFFER_CAMPAIGN_USING_COUPON_CODE_EVENT:

Error Description
400 (BAD_REQUEST) Offer customer suspended.
Specified offer could not be located.
Specified offer no longer exists.
500 (INTERNAL_SERVER_ERROR) This error is returned for the following use cases:
An internal server error has occurred.
A processing error has occurred.
Transaction not supported.

Activate an Offer

Invoke this method to convert an available offer campaign or coupon code into an activated offer that is able to be redeemed in a qualifying mobile transaction. Once an offer campaign is activated, it ceases to be retrievable as an offer campaign instance and becomes retrievable as an activated offer.

Item Description
UI Method void activateOffer(PickOfferCampaign pickOfferCampaign);

pickOfferCampaign - An instance of the PickOfferCampaign class that identifies the campaign to be activated by its OfferCampaignUri, couponCode, or the checkoutTokenValue associated with the transaction in which the offer campaign was promoted.
Success void onPickedOfferRetrievalSuccess(Offer offer);

domain.offer - An instance of Offer containing all the details for the requested offer, including the list of individual acceptance locations at which the offer can be redeemed.
Failure void onOfferRetrievalError(PaydiantException exception);

exception - An instance of PaydiantException for the PICK_OFFER_EVENT, detailing the nature of the failure identified by relevant error codes.
Core Method Offer activateOffer(PickOfferCampaign pickOfferCampaign);

pickOfferCampaign - An instance of the PickOfferCampaign class that identifies the campaign to be activated by its OfferCampaignUri, couponCode, or the checkoutTokenValue associated with the transaction in which the offer campaign was promoted. Returns raw output for the offer instance or relevant exception.

Note: There is currently no alternative method that will return the offer instance containing the list of valid acceptance partners instead of acceptance locations upon offer activation.

Errors

When activating offers, the following errors are applicable for the PICK_OFFER_EVENT:

Error Description
404 The specified offer could not be located.
410 The specified offer is no longer available.
414 The specified offer is not redeemable.
500 An internal server error has occurred.

Deactivate My Offer

Invoke this method to convert a previously activated offer back to an available offer campaign, thus removing it from the My Offers list and rendering it unable to be redeemed during a qualified mobile transaction until it is reactivated.

Item Description
UI Method void removeOffer(string offerUri);

offerUri - The string value that uniquely identifies the activated offer in the Paydiant system.
Applicable Listener Callbacks void onCancelPickedOfferSuccess(boolean offerCancelled);
Called when the offer is successfully reverted to inactive.

void onOfferRetrievalError(PaydiantException exception);
Called when the offer could not be reverted due to an error.
Success void onCancelPickedOfferSuccess(boolean offerCancelled);

offerCancelled - A Boolean value indicating the activation cancellation status of the offer.
Failure void onOfferRetrievalError(PaydiantException exception);

exception - An instance of PaydiantException for the REMOVE_OFFER_EVENT, detailing the nature of the failure identified by relevant error codes.
Core Method public boolean removeOffer(String offerUri;

offerUri - The string value that uniquely identifies the activated offer in the Paydiant system. Returns raw output for the boolean value or relevant exception.

Errors

When deactivating offers, the following errors are applicable for the REMOVE_OFFER_EVENT:

Error Description
404 The specified offer could not be located.
410 The specified offer is no longer available
414 The specified offer is not redeemable.
500 An internal server error has occurred.

Other Resources

javadocs

Feedback