Targeted Offers Java SDK

Amex Targeted Offers API is a capability to request instant pre-qualified , prescreened Card offer(s) for the applicants, if eligible. Targeted Offers API provides an interface to interact with systems of American Express. ​

This Java implementation allows Amex partners to integrate seamlessly to Targeted Offers and reduces complexity out of coding service layer integration to Targeted Offers API. The Targeted Offers Java SDK is a simple wrapper to the API. It assumes you have already set up your credentials with American Express and have your certs prepared. See the authentication and authorization guides for more information.

Table of Contents

• Documentation
• Installation
• Compatibility
• Configuration
• Authentication
• Offers
  • Getting offers
  • Acknowledging Offers
• Token
• Error Handling
• Samples
• Open Source Contribution
• License
• Code of Conduct

Documentation

Please see : documentation for Amex Targeted Offers API

Installation

• Install maven

  brew install maven
  

• Clone repo
• Go inside px-toa-java-sdk and type

   $ mvn clean install
  

Compatibility

targeted-offers-client sdk will support Java Version 8 or higher.

Configuring SDK

SDK needs to be configured with OAuth, Mutual Auth and Payload encryption configurations, below is the sample configuration snippet.

private TargetedOffersClient createTargetedOffersClient() throws IOException, CertificateException,
        NoSuchAlgorithmException, KeyStoreException, UnrecoverableKeyException, KeyManagementException {
    Map<String, String> sampleConfig = buildClientConfig();
    TargetedOffersClient targetedOffersClient = null;

    InputStream inputStream = Thread.currentThread().getContextClassLoader()
            .getResourceAsStream(sampleConfig.get(DEVELOPER_PORTAL_SDK));
    KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
    ks.load(inputStream, sampleConfig.get(OAUTH_KEYSTORE_PASSPHRASE_PROPERTY).toCharArray());
    KeyStore trustStore = KeyStore.getInstance(sampleConfig.get(KEYSTORE_JKS));
    InputStream trustStream = Thread.currentThread().getContextClassLoader()
            .getResourceAsStream(sampleConfig.get(OAUTH_KEYSTORE_TRUST_STREAM));
    trustStore.load(trustStream, sampleConfig.get(OAUTH_KEYSTORE_LOAD_TRUST_STREAM).toCharArray());

    SSLConnectionSocketFactory socketFactory = new SSLConnectionSocketFactory(
            new SSLContextBuilder().loadTrustMaterial(trustStore, (chain, authType) -> false)
                    .loadKeyMaterial(ks, sampleConfig.get(OAUTH_KEYSTORE_PASSPHRASE_PROPERTY).toCharArray(),
                            (aliases, socket) -> sampleConfig.get(OAUTH_KEYSTORE_ALIAS_PROPERTY))
                    .build());

    targetedOffersClient = TargetedOffersClient.Builder
            .build(Config.builder().url(sampleConfig.get(OAUTH_OFFERS_API_ENDPOINT))
            .apiKey(sampleConfig.get(OAUTH_API_KEY))
            .apiSecret(sampleConfig.get(OAUTH_API_SECRET))
            .accessToken(null)
            .socketFactory(socketFactory)
            .jweConfig(new JWEConfig(false))
            .proxyConfig(new ProxyConfig(Boolean.parseBoolean(sampleConfig.get(PROXY_ENABLED)),
                    sampleConfig.get(PROXY_PROTOCOL), sampleConfig.get(PROXY_HOST),
                    Integer.valueOf(sampleConfig.get(PROXY_PORT)))).build());

    return targetedOffersClient;
}

Authentication

Amex Targeted Offers API uses token based authentication. The following examples demonstrates how to generate bearer tokens using the SDK :

AccessTokenResponse accessTokenResponse = getAuthenticationToken(targetedOffersClient); //success response

targetedOffersClient.setAccessToken(accessTokenResponse.getAccessToken()); //set the Access Token for further API calls 

Sample Response :

{
  scope: 'default',
  status: 'approved',
  expires_in: '3599', // token expiry in seconds, you can cache the token for the amount of time specified.
  token_type: 'BearerToken',
  access_token: 'access token example'
}

Note : you can skip this call if you have an active Token in your cache. if you have an active token, you can just set the bearerToken in config under authentication or call setAccessToken('access_token') method to update the config.

Offers :

Getting Offers

Request body and API mandatory fields can be found at API Specifications.

TargetedOffersClient targetedOffersClient = createTargetedOffersClient();

TargetedOffersRequest targetedOffersRequest = objectMapper.readValue(Thread.currentThread().getContextClassLoader().getResourceAsStream("targetedOffersRequest.json"), TargetedOffersRequest.class);

offersResponse = offersService.getOffers(targetedOffersRequest);

//see src/main/resources for a sample header and body

return offersResponse; //successful response

This will return an array of offers, you can find more information on response at reference guide.

Acknowledging Offers

The acknowledgeOffers() method is used to let American Express know that offers were presented to the user. Response will be true if the API call is success.

//applicant_request_tracking_id will be provided as part of the targeted offers response.
acknowledgementRequest.setApplicantRequestTrackingId(offersResponse.getApplicantRequestTrackingId());
				
return offersService.acknowledgeOffers(acknowledgementRequest); //successful response

Token

The getSessionToken() method is used to get a session token. Session Token is required to maintain the session of the user and is only of one time use.

//applicant_request_tracking_id will be provided as part of the targeted offers response. please pass the value to get session token.
 
TokenRequest tokenRequest = objectMapper.readValue(
	Thread.currentThread().getContextClassLoader().getResourceAsStream("sessionTokenRequest.json"), TokenRequest.class);

TokenResponse tokenResponse = tokenService.getSessionToken(tokenRequest);
				
return objectMapper.writeValueAsString(tokenResponse)); //successful response

Sample Success response:

{
  SessionToken: eyJhbGciOiJSUzI1NiJ9.eyJjbGFpbXNfcmVxIjoidHJ1ZSIsImFjY2Vzc190eXBlIjoiUyIsInRva2VuX2lkIjoiYXBwbGljYW50X3JlcXVlc3RfdHJhY2tpbmdfaWQiLCJyZXNvdXJjZV9pZCI6IjUyMjRhNjMzLTczNDQtNGZjZi1hOGVkLWU2MzE0NmM2ZmVhOCIsInRva2VuX3R5cGUiOiJTIiwiZXhwIjoxNTgyODY3MTQzLCJqdGkiOiI1YzUyYmNlYi1mNmExLTQ0YTEtOTk4ZS0yYTBjNmFmMDhiYmQiLCJjbGllbnRfaWQiOiJDbGllbnRfSUQifQ.NnmzkiiB08YWZQKWKFvAwAHdcNoqjmkSBc4vNwr0TXu1SBWgEhC4J_3mbunQ_PV8FUq6-n4YI4ogPSTuy570AZJ4sq9e86gE-dIuuOMs2AzsLukeIz5PHuHUP9friqpcKHbOqJFMohBNwsA0IGwA96aB9BJ0yPDqcGgiOtju_QekGJRk6LByHUQevuPsHdZjGCgXpXiqHjOFA3SFycE0NUi2pLnC5VISgG-OFFr0HaoqskcM843UMyGb_MGDKcgMJUhDuHaqqsI4oJ-SmGYs6r88vIlxLvPX-JWuSjI8uLITOYvCq8CQPoKEasLhhu93I_YlZO4B423oJ_OQoIvePw
}

Error Handling

In case of exceptions encountered while calling American Express APIs, the SDK will throw Errors.

Possible exceptions :

- ResourceNotFoundError // ResourceNotFoundError will be raised when the user is not qualified for PreQualified or PreScreened Offers
 
- OffersAuthenticationError // Authentication errors with the API -- example : invalid API Key or Secret is sent to the API

- OffersRequestValidationError // Request Validation Error -- request or configs provided to the SDK are invalid, you can see more info in err.fields for the fields that failed validations.

- NoOffersAvailable // NoOffersAvailable will be raised when the user is not qualified for a PreQual or PreScreened Offers. 

- OffersAPIError // Is a generic type of error, It will be raised when there is an Internal server error or any other error which is not covered by any of the named errors.

- PayloadEncryptionError // PayloadEncryptionError is a generic type of error for Encryption errors,It will be raised when there is an Exception raised at the Payload encryption. More information will be present in the error message.

Running Samples

See TargetedOffersSample.java for sample usages of Targeted Offers SDK. There are four different samples included to demonstrate the different scenarios in which Targeted Offers API can be used:

• Logged In (only PII available)
• Logged In (PII and session data available)
• Logged Out Warm (Partner account number and session data available)
• Logged Out Full (only session data available)

Each sample includes an example request JSON. Please update the example values with actual values before running the sample.

The "sample.properties" resource file contains the variables needed to run the sample. Please replace the example values with actual values before running the sample.

developer.portal.sdk=jks_file_example.jks           // SDK keystore
keystore.jks=jks                                    // Java keystore format type
oauth.keystore.trust.stream=trust_file_example.jks  // Path to trust store file
oauth.keystore.load.trust.stream=trust_user_example // Keystore username
oauth.keystore.passphrase.property=password_example // Keystore password
oauth.keystore.alias.property=alias_example         // Alias (or name) under which the key is stored in the keystore
oauth.offers.api.endpoint=https://example.aexp.com  // TargetedOffersAPI SDK endpoint
oauth.api.key=auth_key_example                      // OAuth Client ID/Key
oauth.api.secret=secret_example                     // OAuth Secret 
proxy.protocol=http                                 // Protocol Client uses to connect to proxy/load balancer
proxy.enabled=true                                  // Enabled or disabled proxy
proxy.host=proxy.example.com                        // Proxy host
proxy.port=8080                                     // Proxy port

Contributing

We welcome your interest in the American Express Open Source Community on Github. Any Contributor to any Open Source Project managed by the American Express Open Source Community must accept and sign an Agreement indicating agreement to the terms below. Except for the rights granted in this Agreement to American Express and to recipients of software distributed by American Express, You reserve all right, title, and interest, if any, in and to Your Contributions. Please fill out the Agreement.

License

Any contributions made under this project will be governed by the Apache License 2.0.

Code of Conduct

This project adheres to the American Express Community Guidelines. By participating, you are expected to honor these guidelines.