Backend Integration: Handling SSO Requests

To authorize operations and manage user access, you must expose an API endpoint on your backend system. The Tap on Phone platform calls this endpoint to verify Single Sign-On (SSO) permissions whenever your client app requests a sensitive operation, such as initializing the terminal or processing a refund.

This guide shows you how to implement and configure this endpoint to receive, validate, and respond to SSO requests.

Step 1: Configure your endpoint requirements

Your backend endpoint must meet specific technical requirements to successfully communicate with the Tap on Phone platform:

• Protocol: The endpoint must use HTTPS.

• Response Time: The endpoint must process the request and respond within a maximum of 5 seconds. Any delay beyond this results in a timeout error.

• IP Whitelisting: You must configure your firewall or reverse proxy to allow incoming requests from the following Tap on Phone platform IP addresses:
  Test Environment IPs:

  • 35.156.130.116
  • 35.156.242.206

  Production Environment IPs:

  • 3.124.56.20
  • 63.176.190.170
  • 18.158.202.149
  • 18.197.125.190

Step 2: Handle the incoming request

When a user triggers an action that requires authorization (like launching the InitActivity), the Tap on Phone platform sends a POST request to your endpoint.

Headers

The platform passes the user’s authentication token in the request header. This token matches the userToken string your client application passes during the Intent call.

X-Auth-Token: 1234567

Request Body

The request includes a JSON body detailing the requested operation and its metadata.

{
  "operation": "serviceInitialisation",
  "operationMetadata": {
    "ClientID": "4bac0922d476436697283b8238ba282b"
  }
}

• operation: The type of operation the user is attempting to perform. Supported values include serviceInitialisation and refund.
• operationMetadata: Contains contextual metadata, including your organization’s ClientID.

Step 3: Validate the request

Upon receiving the request, your backend must perform the following validation steps:

1. Authenticate the user: Read the X-Auth-Token header and verify that the user’s session is active and valid within your system.
2. Authorize the operation: Check the operation field. Determine if the authenticated user has the necessary permissions to perform this specific action (for example, ensuring only admin users can perform a refund).

Step 4: Return the appropriate response

After validating the request, you must return an HTTP response to instruct the Tap on Phone platform on how to proceed.

Successful Response

If you approve the request, return an HTTP 200 OK status code with a JSON payload containing the following mandatory fields:

• merchantId: The integer Tap to Pay ID of the merchant business registered on the platform (obtained during the onboarding process).
• userId: The unique identifier for the user. This must match the userId originally passed by your client app in the Intent.

{
  "merchantId": 19,
  "userId": "19"
}

Unsuccessful Responses

If the request is unauthorized or encounters an error during processing, your backend must return one of the following standard HTTP status codes:

• 401 Unauthorized: Use this if the X-Auth-Token is invalid, expired, or if the user lacks the required permissions for the requested operation.
• 405 Method Not Allowed: Use this if the endpoint receives a request method other than POST.
• 500 Internal Server Error: Use this if your backend encounters an unexpected issue while processing the validation.

Next Steps

Once your SSO endpoint is active and correctly processing authorization requests, you are ready to start initiating intents from your Android application.

Proceed to Quick Start: Your First Initialization to initialize the POS session.