Google is committed to advancing racial equity for Black communities. See how.

How to establish connectivity with Plex APIs in Java

This is a self-guided codelab that will walk you through how to establish connectivity with Plex APIs.

Prerequisites

  • You have completed steps 1 and 2 of the Implementation Process.
  • You can host the provided Java server with TLS termination by using either Google App Engine or your own solution at the domain configured with Google.
  • Java is installed on your environment.

What You'll Learn

Download the Application

Download the Java sample code.

Application Structure Overview

The Java sample code integrates with Google's Standard Payments API and Google's Plex API. The sample code project structure contains a standardpayments directory as well as a plex directory to reflect these components. Both of these directories contain a similar hierarchy in packaging by layer. The three main layers are controller, service, and domain.

  • The controller package contains the APIs.
  • The service package is responsible for business logic, base64url encoding, and encryption.
  • The domain package contains POJOs.

Install Dependencies

Navigate to the project directory and run the following command to install the required dependencies using the Maven Wrapper. If you are using App Engine, you can skip this step.

./mvnw install

The Payment Integrator Account ID (PIAID) is an identifier used to uniquely identify your integrations. You should have received your PIAID from Google by completing the prerequisites before starting this tutorial.

  1. Navigate to src/main/resources/application.properties in the project directory.
  2. Set the property payment.integrator.account.id to the PIAID that was issued to you by Google.
payment.integrator.account.id={YOUR_PAYMENT_INTEGRATOR_ACCOUNT_ID}

As shown below, add your PGP keys to enable PGP encryption.

  • Navigate to src/resources/publicKey1.gpg and add the ASCII armored public key to the file.
  • Navigate to src/resources/privateKey1.gpg and add the ASCII armored private key to the file.
  • Navigate to src/resources/passphrase1.txt and add the secret passphrase to the file.

Adding PGP keys

To enable dual key encryption, add your second public key to publicKey2.gpg add your second private key to privateKey2.gpg, and add your second passphrase to passphrase.txt. After ading the second keys, uncomment the commented out lines of code that are responsible for loading the second pair of keys in KeyConfig.addPrivateKeyAndPassphrase(...) and KeyConfig.addPublicKeys(...).

Great, you are all set to run the application!

To start the application, execute the following command.

  $ ./mvnw spring-boot:run

If you are running a pre-configured App Engine instance, run this command instead.

$ gcloud app deploy

By default, the server will listen on port 8080. To view the Open API Swagger UI, navigate to the URL below.

https://{APPLICATION_HOST}/swagger-ui.html

Now that the application is running, it is time to test connectivity with the Google Standard Payments echo API.

Either Swagger UI or the CLI can be used to run the following command to initiate a call from your instance of the sample application to Google's servers. The sample application echo API accepts a POST request in plaintext. After receiving the request, a subsequent request is sent to the Google-hosted API.

Send a request through the command line

Replace the HOSTNAME with the name of your server host before executing the command.

  $ curl -X POST -H 'Content-Type: text/plain' -d 'Hello from Bank Little Bear!' https://{HOSTNAME}/echo

Send a request in Swagger UI

To send a request with Swagger UI, go to https://{APPLICATION_HOST}/swagger-ui and set the client message in the request body. Click the ‘Execute' button when you are ready to send the request to Google.

Submitting a GSP Echo request through Swagger

Receive the response

A successful API request will result in the following response from Google.

{
   "responseHeader":{
      "responseTimestamp":"1606710026723"
   },
   "clientMessage":"Hello from  Bank Little Bear!",
   "serverMessage":"Server message."
}

Step-by-step

Now that a request has been successfully sent by your server, let's review how that worked.

Build the request

createEchoRequestWithMessage in StandardPaymentsEchoService builds the echo request sent to Google's API.

String jsonEchoRequestMessage = objectMapper.writeValueAsString(createEchoRequestWithMessage(message));

The generated request includes the clientMessage, as well as several default value fields.

{
   "requestHeader":{
      "protocolVersion":{
         "major":1,
         "minor":0,
         "revision":0
      },
      "requestId":"ddfe0fd0-ffdc-4fcf-991a-f0611ec83970",
      "requestTimestamp":"1606715389040"
   },
   "clientMessage":"Hello from Bank Little Bear!"
}

Base64url encode and encrypt the request

All Plex requests are encrypted and base64url encoded. In this sample, PgpEncryptor.java contains helper methods that perform encryption and decryption as well as base64url encoding for you. The below method encodes the request and performs encryption using Google's public key.

String encryptedMessage = pgpEncryptor.encrypt(jsonEchoRequestMessage);

Send the POST request

The encrypted message is sent via a POST request.

postStandardPaymentsEchoApi(encryptedMessage)

Decrypt and base64url decode the response and return the response

Google's successful response is base64url encoded and encrypted, so it needs to be decoded and decrypted as well before it can be returned in plaintext. The decrypt method base64url decodes and decrypts the response.

String decryptedData =
     pgpEncryptor.decrypt(postStandardPaymentsEchoApi(encryptedMessage).getBody());

Return the response

The response is returned with a 202 HTTP Response Status Code.

return new ResponseEntity<>(decryptedData, HttpStatus.ACCEPTED);

To test Plex echo API Connectivity, Google will send a request to the Bank Hosted echo API.

When you are ready, please work with your Google point of contact to trigger this request from Google.

The echo test is complete when you are able to read the inbound echo request from Google and respond with a valid echo response.

Step-by-step

Now that a request has been successfully received and handled by your server, let's review how that worked.

Base64url decode and decrypt the request

When a request is received, PgpEncryptor.java will call decrypt which will base64url decode and decrypt the request.

String decryptedRequest = pgpEncryptor.decrypt(cacheEchoRequest);

Receive the request

Google sent a message payload that is similar to the following once it was decoded and decrypted.

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "G1MQ0YERJ0Q7LPM",
    "requestTimestamp": {
      "epochMillis":1481899949606
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "clientMessage": "paycache.echo Me"
}

Build the response

Once you have successfully read the inbound echo request, you are ready to build the response.

private CacheEchoResponse convertEchoRequestStringToEchoResponse(String decryptedRequest);

The response includes the message from Google, as well as a timestamp and message from the server.

{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis":1481899950236
    }
  },
  "clientMessage": "paycache.echo Me",
  "serverMessage": "Debug ID 12345"
}

Base64url encode and encrypt the response

Since all Plex requests are encrypted and base64url encoded, PgpEncryptor.java calls encrypt to base64url encode and encrypt the request.

pgpEncryptor.encrypt(echoResponseString)

Return the response

The response is returned with a 202 HTTP Response Status Code.

return new ResponseEntity<>(pgpEncryptor.encrypt(echoResponseString), HttpStatus.ACCEPTED);

In this codelab, you've successfully established connectivity with the Plex API!