The earlier tutorial, Implementing “Add to Pockets” in an Android Software, confirmed how you can generate and signal a card knowledge token so as to add the cardboard to Samsung Pockets. This tutorial demonstrates how one can carry out server interactions with the Samsung Pockets server and retrieve data reminiscent of the cardboard states on a consumer’s system.

In case you are a Samsung Pockets companion who’s providing Samsung Pockets playing cards to your customers, you may also wish to know how one can observe a offered pockets card’s standing on a consumer’s system. Comply with alongside on this tutorial to be taught how one can make the most of the Ship Card State API and retrieve this data to your individual server. All code examples used on this tutorial might be discovered inside the pattern code offered on the finish of this tutorial for additional reference.

Card states and the Ship Card State API

The Samsung Pockets card’s standing on a consumer’s system is represented by numerous states, reminiscent of ADDED, UPDATED, or DELETED.

Every time the cardboard state of a card modifications on a consumer’s system, Samsung Pockets server sends a notification to the configured companion server informing in regards to the change. This API offered by Samsung is known as the Ship Card State API.

Samsung offers the Ship Card State API as a way of server-to-server communication between the Samsung server and the companion’s server and to let the companion know in regards to the card state of their issued playing cards on consumer’s units. With this API, companions can observe the state of a pockets card on a consumer’s Samsung Galaxy system.

Conditions

Earlier than you possibly can check the Ship Card State API, you must:

1. Full the Samsung Pockets onboarding course of.
2. Create a Samsung Pockets card template.
3. Launch the pockets card template and have it in VERIFYING or ACTIVE standing in order that the cardboard might be added to a consumer’s system.
4. Have an current server to obtain the notifications. You should utilize CodeSandbox or the same on-line internet hosting service for testing.
5. Configure your firewall (when you use any) to simply accept incoming connections from the Samsung Pockets server (34.200.172.231 and 13.209.93.60).

When you will have accomplished all of the stipulations, proceed to the subsequent step to configure your pockets card template to ship requests to your server.

Configure the Pockets card template for the Ship Card State API

To obtain the Ship Card State notifications in your server, you must set your server’s URL within the desired Samsung Pockets card’s choices:

1. Go to the Pockets Companions Portal.
2. From the Pockets Playing cards dropdown, choose “Handle Pockets Card.”
3. Click on the title of the pockets card.
4. Click on “Edit” after which scroll all the way down to the “Companion Ship card state” part to change the Companion server URL.
5. Click on “Save” to set the companion server URL for the cardboard.

Now, at any time when a consumer provides or deletes an issued Samsung Pockets card to their system, the Samsung Pockets server robotically sends a POST notification to the Companion server URL set within the Pockets Companions Portal. Subsequent you must be taught in regards to the specification of the request to be able to deal with it from the server.

Ship Card State API specification and format

For a whole description of the Ship Card State API specification, see Samsung Pockets documentation.

Request methodology

The Ship Card State API makes use of a POST methodology to ship a request to the server. The API path for the request is fastened and makes use of the companion server URL that you simply outlined in part “Configure the Pockets card template for the Ship Card State API.”

API path and URL parameters

The API path on the very finish of the “Companion Ship card state” part is the trail the place the Samsung server sends the Ship card state POST request. So the whole API path URL is: {Companion server URL}/playing cards/{cardId}/{refId}?cc2={cc2}&occasion={occasion}.

Right here, cardId is the Card ID of the pockets card template and refId is the reference ID subject of the issued card knowledge, which is a novel identifier. The cc2 question parameter is the 2-letter nation code (ISO 3166-1 alpha-2) and occasion is the cardboard state occasion (ADDED, DELETED, or UPDATED) occurring within the consumer’s system.

Contemplate the next instance card configuration:

• Companion server URL: https://companion.server.url
• Card id: 123
• Ref id for the issued card: abc
• Nation code: US

On this configuration, at any time when the consumer provides the cardboard to their Samsung Pockets software, the Samsung Pockets server sends a Ship card state notification to the next URL:
https://companion.server.url/playing cards/123/abc?cc2=US&occasion=ADDED.

Equally, if a consumer from the UK deletes a card with the refId xyz, the POST request is shipped to https://companion.server.url/playing cards/123/xyz?cc2=GB&occasion=DELETED.

Due to this fact, you possibly can know if a card was added or faraway from the consumer’s system straight from the question parameters.

POST request physique

The POST request physique doesn’t include any data relating to the cardboard state. Reasonably it simply offers a callback URL that you should use if you wish to ship an replace notification for the cardboard.

{
  "callback": "https://us-tsapi.walletsvc.samsung.com"
}

POST request header

The POST request header incorporates all of the required data for making certain the authenticity of the request. It incorporates a request ID with the title “x-request-id” and a JWT bearer token credential for authentication with the title “Authorization” within the header.

The Samsung Pockets server makes use of a bearer authorization token to make sure the authenticity of the requests being despatched to the companion server. For particulars of the safety components, see Authorization Token.

The bearer token is encoded in base64 following the JWT specification. It has three components: JWS Header containing authentication associated data, JWS Payload containing the API path, methodology, and refID, and JWS Signature, which validates that the bearer token is signed by the Samsung server.

JWS Header format:

{
  "cty": "AUTH", // At all times “AUTH”
  "ver": "3", // May also be “2” for legacy card knowledge token
  "partnerId": "4048012345678938963", // Your companion ID
  "utc": 1728995805104, // Time of signing in milliseconds
  "alg": "RS256",
  "certificateId": "A123" // Solely offered for token model 3
}

JWS Payload format:

{
  "API": 
  {
    "path": "/playing cards/3h844qgbhil00/2e19cd17-1b3e-4a3a-b904?cc2=GB&occasion=ADDED",
    "methodology": "POST"
  },
  "refId": "2e19cd17-1b3e-4a3a-b904-f30dc91ac264"
}

Lastly, the bearer token incorporates a signature to confirm the token. That is signed utilizing the Samsung Non-public Key and might be validated utilizing the Public Key offered by Samsung Pockets through the onboarding course of.

After receiving any request from the Samsung Pockets server, your server ought to ship again an HTTP standing code as a response. Samsung Server expects one of many following codes as a response:

• 200 OK
• 401 Unauthorized
• 500 Inner Server Error
• 503 Service Unavailable

That is the whole specification of the Ship Card State API that you simply want to concentrate on earlier than you implement the server.

Subsequent, you must configure your server to simply accept the POST request within the specified format.

Configure the Spring server to obtain the POST request

To obtain and interpret the Ship Card State POST notifications despatched by the Samsung Pockets server, you must configure a companion server and host the server on the URL you specified earlier.

To obtain the POST requests, this tutorial extends an current server created utilizing the Spring Boot framework. If you wish to know the way the Spring server is configured, try the “Generate signed Pockets card knowledge” part within the Implementing “Add to Pockets” in an Android Software tutorial. This CData era server is used as the bottom server software for this tutorial, so the dependencies are the identical as effectively. Now you can begin implementing the tutorial.

Create a controller class to intercept the POST request

Samsung Pockets at all times sends the Ship card state POST notification to the fastened API path URL: {Companion server URL}/playing cards/{cardId}/{refId}.

1. Create a brand new controller class in your Spring server to intercept any POST request that’s despatched to this API path.

   @RestController
   @RequestMapping("/playing cards")
   class CardStateController {
     @PostMapping(path = ["/{cardId}/{refId}"])
     enjoyable handleCardState(@PathVariable cardId: String,
                         @PathVariable refId: String): HttpStatusCode {
         // Implement your logic right here to course of the cardboard state.
   
         println("Obtained card state notification for card ID $cardId and reference ID $refId.")
         
         return HttpStatus.OK
     }
   }
   
   

2. Run the server after which add or delete a card out of your Samsung Pockets.

   If the companion server URL was set accurately in part “Configure the Pockets card template for the Ship Card State API,” your server ought to obtain a POST request from the Samsung server and print the next message to the console: “Obtained card state notification.”

Replace the controller class to obtain the question parameters

1. Deal with the question parameters from the request by including the next parameters because the operate’s parameters: @RequestParam("cc2") cc2: String, @RequestParam("occasion") occasion: String
2. Obtain and print the request physique utilizing the @RequestBody physique: String parameter.

The operate ought to now seem like this:

@PostMapping(path = ["/{cardId}/{refId}"], params = ["cc2", "event"])
enjoyable handleCardState(@PathVariable cardId: String,
                   @PathVariable refId: String,
                   @RequestParam("cc2") cc2: String,
                   @RequestParam("occasion") occasion: String,
                   @RequestBody physique: String): HttpStatusCode {

   // Implement your logic right here to course of the cardboard state.

   println("Nation code: $cc2")
   println("Pockets Card State Occasion: $occasion")

   println("Request physique: $physique")

   return HttpStatus.OK 
}

Now at any time when the Samsung server sends a request to the server, it prints the system’s nation code and the pockets card’s state occasion on the system.

Confirm the POST request

That is the ultimate and a very powerful step of this tutorial. Earlier than accepting any incoming POST request, it’s best to at all times validate the request by following the API specification talked about earlier within the tutorial.

The safety procedures can embody however are usually not restricted to:

• Matching your PartnerID with the acquired partnerId customized parameter.
• Checking the token model with the ver customized parameter. For token model 3, match your CertificateID utilizing the certificateId customized parameter.
• Checking the time of signing utilizing the utc customized parameter.
• Matching the opposite JWS Header parameters with the values talked about within the specification.
• Matching the Path from the JWS Payload with the acquired URL.
• Verifying the JWT.

This part exhibits how one can implement every of those one after the other.

First, parse the authentication token and skim the header.

val signedJWT : SignedJWT = SignedJWT.parse(authToken)
val jwsHeader : JWSHeader = signedJWT.header

Match PartnerId and JWS Header parameters:

val ownPartnerId = "4048012345678938963" // Your companion ID from Samsung Pockets Companion Portal
val receivedPartnerId = jwsHeader.customParams["partnerId"]
val cType = jwsHeader.contentType
val alg = jwsHeader.algorithm.title

// Test if the JWS header parameters match the anticipated values
if (cType == "AUTH" && alg == "RS256" && receivedPartnerId == ownPartnerId ) {
    println("JWS Header parameters matched")
    // Proceed with additional verification
}

Test the token model and match CertificateId:

val ver = jwsHeader.customParams["ver"]
val ownCertificateId = "A123" // Your certificates ID from Samsung Pockets Companion Portal
val receivedCertificateId = jwsHeader.customParams["certificateId"]?: ""

// If companion makes use of token model 3 within the JWS header of the CDATA,
// Then Samsung server additionally returns model 3 response together with the certificates ID
if(ver == "3" && receivedCertificateId == ownCertificateId){
    println("JWS Header certificates ID matched")
    // Proceed with additional verification
}

Test if the token was generated just lately:

// Test if the timestamp is inside acceptable vary
val utc = jwsHeader.customParams["utc"] as Lengthy
val timeDelta = System.currentTimeMillis() - utc
println("Time Delta: $timeDelta")
if (timeDelta < 600000L) {
    println("UTC Timestamp is inside final 1 minute. Time delta = $timeDelta ms.")
    // Proceed with additional verification
}

Match the API path with the acquired API path from the payload:

val receivedAPIValue = signedJWT.payload.toJSONObject()["API"]?.toString()?: ""
val receivedAPIPath = receivedAPIValue.substring(6, receivedAPIValue.size - 14)
val expectedPath = "/playing cards/$cardId/$refId?cc2=$cc2&occasion=$occasion"

// Match the trail within the payload with the anticipated path
if (receivedAPIPath == expectedPath) {
    println("Path matched")
    // Proceed with additional verification
}

Lastly, validate the token utilizing the Samsung Certificates offered to you through the onboarding course of:

1. Learn the Samsung Certificates from a file after which extract the general public key. For directions, check with the CData era server pattern code at Implementing “Add to Pockets” in an Android Software.
2. Construct an RSAKey object utilizing the extracted public key.
3. Create an RSASSAVerifier object with the RSAKey to confirm the token.
4. Confirm the token utilizing the verifier.

// Confirm the signature of the JWT token utilizing the general public key offered by Samsung Pockets.
val samsungPublicKey = readCertificate(getStringFromFile("pattern/securities/Samsung.crt"))
val rsaKey = RSAKey.Builder(samsungPublicKey as RSAPublicKey).construct()
val verifier: RSASSAVerifier = RSASSAVerifier(rsaKey)

if(signedJWT.confirm(verifier)){
    println("Verification profitable")
    // Implement your logic right here to course of the cardboard state notification.
    // For instance, you possibly can replace the cardboard standing in your database or set off a notification to the consumer.
    // On this instance, we merely return a 200 OK response indicating that the notification was efficiently processed.
    return HttpStatus.OK
} else {
    println("Verification Failed")
    // Return an acceptable HTTP standing code indicating that the notification couldn't be verified.
    return HttpStatus.UNAUTHORIZED
}

Now the whole implementation of the Controller class to obtain and confirm the Ship card state request is full. As soon as a Ship card state request is totally verified, you possibly can settle for the request as a legitimate card state replace and make any modifications as required. For instance, you possibly can replace the cardboard standing data in your individual database or set off a notification to the consumer.

Abstract

By finishing this tutorial, you at the moment are in a position to obtain card state updates from the Samsung Pockets server utilizing the Ship Card State API and validate them. In a future tutorial, we are going to talk about how one can increase the server interplay performance even additional and how one can replace Samsung Pockets card data on consumer units by the Get Card Knowledge API.

If you wish to talk about or ask questions on this tutorial, you possibly can share your ideas or queries on the Samsung Builders Discussion board or contact us straight for any implementation-related points by the Samsung Developer Assist Portal. If you wish to maintain up-to-date with the newest developments within the Samsung Builders Ecosystem, subscribe to the Samsung Builders E-newsletter.

Pattern Code

You may click on on the hyperlink given beneath to obtain the whole pattern code used on this tutorial.