Procare Pay Integration Service

Complete API Documentation for Payment Processing

Get Shallow Dependency Status

GET /v1/rest/status/shallow

Description: Returns the connectivity status of all downstream dependencies using token-only checks. This provides a quick assessment of whether the service can connect to its dependencies without performing deep health validations.

What is this endpoint used for?

This endpoint provides a fast dependency connectivity assessment for operations and monitoring:

  • Quick Dependency Check: Verify that all downstream services are reachable and responding to basic requests
  • Pre-Flight Validation: Confirm dependency connectivity before initiating critical operations such as batch payment processing
  • Monitoring Dashboards: Integrate with monitoring tools to track dependency health over time
  • Automated Alerting: Trigger alerts when one or more dependencies become unreachable
  • Faster Than Deep Check: Completes in approximately 500ms compared to 2-5 seconds for the deep check
No Authentication Required: This endpoint does NOT require authentication, making it suitable for infrastructure monitoring, load balancer health checks, and external monitoring systems.
Token-Only Checks: This endpoint only verifies that the service can establish connectivity with each dependency. It does NOT perform full functional health checks. A dependency may appear "Healthy" in a shallow check but still have issues that would be detected by the Deep Status endpoint.

Code Examples

using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Collections.Generic;

public class ShallowStatusClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://your-api-domain.com";

    public ShallowStatusClient()
    {
        _httpClient = new HttpClient();
        _httpClient.BaseAddress = new Uri(_baseUrl);
        _httpClient.Timeout = TimeSpan.FromSeconds(10);
    }

    public async Task<DependencyCheckResponse> CheckShallowStatusAsync()
    {
        try
        {
            // Make the GET request (no authentication required)
            var response = await _httpClient.GetAsync("/v1/rest/status/shallow");
            var responseBody = await response.Content.ReadAsStringAsync();

            var options = new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            };
            var result = JsonSerializer.Deserialize<DependencyCheckResponse>(responseBody, options);

            // HTTP 200 = all healthy, HTTP 503 = one or more unhealthy
            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("All dependencies are healthy.");
            }
            else if ((int)response.StatusCode == 503)
            {
                Console.WriteLine("One or more dependencies are unhealthy:");
                foreach (var dep in result.Dependencies)
                {
                    if (dep.Status != "Healthy")
                    {
                        Console.WriteLine($"  - {dep.Name}: {dep.Status} ({dep.Message})");
                    }
                }
            }

            return result;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Shallow status check failed: {ex.Message}");
            throw;
        }
    }
}

public class DependencyCheckResponse
{
    public string Status { get; set; }
    public List<DependencyStatus> Dependencies { get; set; }
}

public class DependencyStatus
{
    public string Name { get; set; }
    public string Status { get; set; }
    public string Message { get; set; }
}

// Example usage:
var client = new ShallowStatusClient();
var statusResponse = await client.CheckShallowStatusAsync();

Console.WriteLine($"Overall Status: {statusResponse.Status}");
foreach (var dep in statusResponse.Dependencies)
{
    Console.WriteLine($"  {dep.Name}: {dep.Status} - {dep.Message}");
}
Imports System.Net.Http
Imports System.Text.Json
Imports System.Text.Json.Serialization
Imports System.Collections.Generic

Public Class ShallowStatusClient
    Private ReadOnly _httpClient As HttpClient
    Private ReadOnly _baseUrl As String = "https://your-api-domain.com"

    Public Sub New()
        _httpClient = New HttpClient()
        _httpClient.BaseAddress = New Uri(_baseUrl)
        _httpClient.Timeout = TimeSpan.FromSeconds(10)
    End Sub

    Public Async Function CheckShallowStatusAsync() As Task(Of DependencyCheckResponse)
        Try
            ' Make the GET request (no authentication required)
            Dim response As HttpResponseMessage = Await _httpClient.GetAsync("/v1/rest/status/shallow")
            Dim responseBody As String = Await response.Content.ReadAsStringAsync()

            Dim options As New JsonSerializerOptions()
            options.PropertyNameCaseInsensitive = True
            Dim result As DependencyCheckResponse = JsonSerializer.Deserialize(Of DependencyCheckResponse)(responseBody, options)

            ' HTTP 200 = all healthy, HTTP 503 = one or more unhealthy
            If response.IsSuccessStatusCode Then
                Console.WriteLine("All dependencies are healthy.")
            ElseIf CInt(response.StatusCode) = 503 Then
                Console.WriteLine("One or more dependencies are unhealthy:")
                For Each dep In result.Dependencies
                    If dep.Status <> "Healthy" Then
                        Console.WriteLine($"  - {dep.Name}: {dep.Status} ({dep.Message})")
                    End If
                Next
            End If

            Return result
        Catch ex As Exception
            Console.WriteLine($"Shallow status check failed: {ex.Message}")
            Throw
        End Try
    End Function
End Class

Public Class DependencyCheckResponse
    Public Property Status As String
    Public Property Dependencies As List(Of DependencyStatus)
End Class

Public Class DependencyStatus
    Public Property Name As String
    Public Property Status As String
    Public Property Message As String
End Class

' Example usage:
Dim client As New ShallowStatusClient()
Dim statusResponse As DependencyCheckResponse = Await client.CheckShallowStatusAsync()

Console.WriteLine($"Overall Status: {statusResponse.Status}")
For Each dep In statusResponse.Dependencies
    Console.WriteLine($"  {dep.Name}: {dep.Status} - {dep.Message}")
Next
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.List;

public class ShallowStatusClient {
    private final HttpClient httpClient;
    private final String baseUrl;
    private final ObjectMapper objectMapper;

    public ShallowStatusClient() {
        this.baseUrl = "https://your-api-domain.com";
        this.httpClient = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
        this.objectMapper = new ObjectMapper();
    }

    public DependencyCheckResponse checkShallowStatus() throws Exception {
        // Construct the endpoint URL
        String endpoint = baseUrl + "/v1/rest/status/shallow";

        // Build the HTTP request (no authentication required)
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(endpoint))
            .timeout(Duration.ofSeconds(10))
            .GET()
            .build();

        // Send the request and get response
        HttpResponse<String> response = httpClient.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        DependencyCheckResponse result = objectMapper.readValue(
            response.body(),
            DependencyCheckResponse.class
        );

        // HTTP 200 = all healthy, HTTP 503 = one or more unhealthy
        if (response.statusCode() == 200) {
            System.out.println("All dependencies are healthy.");
        } else if (response.statusCode() == 503) {
            System.out.println("One or more dependencies are unhealthy:");
            for (DependencyStatus dep : result.dependencies) {
                if (!"Healthy".equals(dep.status)) {
                    System.out.println("  - " + dep.name + ": " + dep.status + " (" + dep.message + ")");
                }
            }
        } else {
            throw new Exception("Unexpected status code: " + response.statusCode());
        }

        return result;
    }

    public static class DependencyCheckResponse {
        public String status;
        public List<DependencyStatus> dependencies;
    }

    public static class DependencyStatus {
        public String name;
        public String status;
        public String message;
    }

    // Example usage
    public static void main(String[] args) {
        try {
            ShallowStatusClient client = new ShallowStatusClient();
            DependencyCheckResponse result = client.checkShallowStatus();

            System.out.println("Overall Status: " + result.status);
            for (DependencyStatus dep : result.dependencies) {
                System.out.println("  " + dep.name + ": " + dep.status + " - " + dep.message);
            }
        } catch (Exception e) {
            System.out.println("Shallow status check failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
require 'net/http'
require 'uri'
require 'json'
require 'timeout'

class ShallowStatusClient
  def initialize
    @base_url = 'https://your-api-domain.com'
  end

  def check_shallow_status
    # Construct the endpoint URL
    uri = URI("#{@base_url}/v1/rest/status/shallow")

    # Create the HTTP request (no authentication required)
    request = Net::HTTP::Get.new(uri)

    # Send the request with timeout
    response = Timeout.timeout(10) do
      Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
        http.request(request)
      end
    end

    result = JSON.parse(response.body)

    # HTTP 200 = all healthy, HTTP 503 = one or more unhealthy
    case response.code.to_i
    when 200
      puts 'All dependencies are healthy.'
    when 503
      puts 'One or more dependencies are unhealthy:'
      result['dependencies']&.each do |dep|
        unless dep['status'] == 'Healthy'
          puts "  - #{dep['name']}: #{dep['status']} (#{dep['message']})"
        end
      end
    else
      raise "Unexpected status code: #{response.code}"
    end

    result
  rescue StandardError => e
    puts "Shallow status check failed: #{e.message}"
    raise
  end
end

# Example usage:
client = ShallowStatusClient.new
result = client.check_shallow_status

puts "Overall Status: #{result['status']}"
result['dependencies']&.each do |dep|
  puts "  #{dep['name']}: #{dep['status']} - #{dep['message']}"
end

Response Format

Success Response (200 OK) - All Dependencies Healthy

{
  "status": "Healthy",
  "dependencies": [
    {
      "name": "TransIT Gateway",
      "status": "Healthy",
      "message": "Connection established successfully"
    },
    {
      "name": "Database",
      "status": "Healthy",
      "message": "Connection established successfully"
    },
    {
      "name": "AWS Cognito",
      "status": "Healthy",
      "message": "Connection established successfully"
    },
    {
      "name": "Cache Service",
      "status": "Healthy",
      "message": "Connection established successfully"
    }
  ]
}

Service Unavailable Response (503) - One or More Dependencies Unhealthy

{
  "status": "Unhealthy",
  "dependencies": [
    {
      "name": "TransIT Gateway",
      "status": "Healthy",
      "message": "Connection established successfully"
    },
    {
      "name": "Database",
      "status": "Unhealthy",
      "message": "Connection timed out after 5000ms"
    },
    {
      "name": "AWS Cognito",
      "status": "Healthy",
      "message": "Connection established successfully"
    },
    {
      "name": "Cache Service",
      "status": "Healthy",
      "message": "Connection established successfully"
    }
  ]
}

Error Response (500 Internal Server Error)

{
  "status": "Unhealthy",
  "responseStatus": "Error",
  "responseMessage": "An unexpected error occurred while checking dependency status",
  "correlationId": "abc123-def456-ghi789"
}

Response Fields

Field Type Description
status string Overall status - "Healthy" if all dependencies pass, "Unhealthy" if any dependency fails
dependencies array Array of dependency status objects detailing each downstream service
dependencies[].name string Name of the downstream dependency (e.g., "TransIT Gateway", "Database")
dependencies[].status string Dependency status - "Healthy" or "Unhealthy"
dependencies[].message string Human-readable message describing the check result or error details
responseStatus string (Error responses only) Status indicator
responseMessage string (Error responses only) Human-readable error message
correlationId string (Error responses only) Correlation ID for support tracking

Common Use Cases

1. Quick Dependency Connectivity Check

Rapidly verify that all downstream services are reachable:

  • Use as a pre-flight check before starting batch operations
  • Verify connectivity after network changes or deployments
  • Completes in approximately 500ms for fast feedback
  • Suitable for automated checks running every 1-5 minutes

2. Monitoring and Alerting

Integrate with monitoring systems for dependency tracking:

  • Poll this endpoint at regular intervals from monitoring tools
  • Trigger alerts when any dependency transitions from "Healthy" to "Unhealthy"
  • Track individual dependency health over time
  • Build dashboards showing per-dependency availability

3. Pre-Flight Validation

Confirm dependency connectivity before critical operations:

  • Check all dependencies before processing batch payments
  • Validate connectivity during application startup
  • Ensure all services are reachable before scheduled jobs
  • Fail fast with specific dependency information rather than encountering errors mid-operation

4. Incident Response

Quickly identify which dependencies are affected during an outage:

  • Run a shallow check to narrow down which dependency is unreachable
  • Correlate dependency failures with application errors
  • Follow up with the Deep Status endpoint for detailed diagnostics

Comparison with Other Status Endpoints

Endpoint Check Type Response Time Dependencies Detail Use Case
/status Simple liveness ~100ms None Load balancer health checks, uptime monitoring
/status/shallow Token-only dependency check ~500ms Per-dependency connectivity Quick dependency connectivity verification, automated monitoring
/status/deep Full dependency health check ~2-5s Full operational health Detailed diagnostics, manual troubleshooting

Additional Notes

  • No Authentication: This endpoint intentionally does not require authentication for easier infrastructure monitoring and operations tooling.
  • Token-Only Checks: The shallow check verifies connectivity only. It confirms that each dependency is reachable but does not exercise full functionality.
  • Fast Response: Designed to respond in approximately 500ms, making it suitable for frequent automated polling.
  • HTTP Status Codes: Returns HTTP 200 when all dependencies are healthy, HTTP 503 when one or more are unhealthy, and HTTP 500 for unexpected errors.
  • A "Healthy" result from the shallow check does NOT guarantee that dependencies are fully operational. Use the Deep Status endpoint for comprehensive validation.
  • The dependencies array always includes all monitored downstream services, regardless of their individual status.
  • The message field provides human-readable context about each dependency's connectivity result.
  • This endpoint is safe to call frequently and has minimal performance impact on the service.

Troubleshooting

503 Service Unavailable

  • One or more dependencies are unreachable or not responding
  • Inspect the dependencies array to identify which specific dependencies are unhealthy
  • Check network connectivity between the Integration Service and the failing dependency
  • Verify that the dependency service is running and accepting connections
  • For detailed diagnostics, follow up with the Deep Status endpoint

500 Internal Server Error

  • The service experienced an unexpected error while performing the health check
  • Check the correlationId in the response for support tracking
  • Alert your operations team immediately
  • Check service logs for detailed error information

Timeout / No Response

  • Network connectivity issues between your system and the API
  • The service itself is completely unavailable or under severe load
  • Check DNS resolution for the API domain
  • Verify firewall rules allow outbound HTTPS traffic
  • Consider setting a client-side timeout of 10 seconds for this endpoint

Individual Dependency Shows "Unhealthy"

  • The specific dependency may be experiencing an outage or network partition
  • Shallow checks verify connectivity only - the dependency process may be running but unreachable
  • Wait 1-2 minutes and retry to rule out transient network issues
  • Use the Deep Status endpoint for additional diagnostic detail
  • Contact support if the issue persists beyond 10 minutes