Procare Pay Integration Service

Complete API Documentation for Payment Processing

Get Deep Dependency Status

GET /v1/rest/status/deep

Description: Returns comprehensive connectivity and health status of all downstream dependencies by performing full health checks. This provides detailed diagnostics about each dependency's operational status.

What is this endpoint used for?

This endpoint provides thorough dependency health validation for diagnostics and troubleshooting:

  • Detailed Diagnostics: Perform full operational health checks against all downstream services, not just connectivity
  • Troubleshooting: Identify the root cause of failures by exercising actual dependency operations
  • Manual Investigation: Use during incident response to determine if a dependency is partially or fully degraded
  • Post-Deployment Validation: Confirm that all dependencies are fully functional after a deployment or configuration change
  • Comprehensive Health Report: Get a complete picture of the service ecosystem health
No Authentication Required: This endpoint does NOT require authentication, making it accessible for operations teams and monitoring systems.
Performance Consideration: This endpoint performs full health checks against all dependencies, which takes approximately 2-5 seconds to complete. It should NOT be used for frequent automated polling or load balancer health checks. For regular monitoring, use the Shallow Status endpoint instead.

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 DeepStatusClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://your-api-domain.com";

    public DeepStatusClient()
    {
        _httpClient = new HttpClient();
        _httpClient.BaseAddress = new Uri(_baseUrl);
        // Longer timeout for deep checks (2-5 seconds expected)
        _httpClient.Timeout = TimeSpan.FromSeconds(30);
    }

    public async Task<DependencyCheckResponse> CheckDeepStatusAsync()
    {
        try
        {
            // Make the GET request (no authentication required)
            var response = await _httpClient.GetAsync("/v1/rest/status/deep");
            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 passed deep health checks.");
            }
            else if ((int)response.StatusCode == 503)
            {
                Console.WriteLine("One or more dependencies failed deep health checks:");
                foreach (var dep in result.Dependencies)
                {
                    if (dep.Status != "Healthy")
                    {
                        Console.WriteLine($"  - {dep.Name}: {dep.Status}");
                        Console.WriteLine($"    Message: {dep.Message}");
                    }
                }
            }

            return result;
        }
        catch (TaskCanceledException)
        {
            Console.WriteLine("Deep status check timed out. The service may be under heavy load.");
            throw;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Deep 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 DeepStatusClient();
var statusResponse = await client.CheckDeepStatusAsync();

Console.WriteLine($"Overall Status: {statusResponse.Status}");
Console.WriteLine("Dependency Details:");
foreach (var dep in statusResponse.Dependencies)
{
    var indicator = dep.Status == "Healthy" ? "[OK]" : "[FAIL]";
    Console.WriteLine($"  {indicator} {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 DeepStatusClient
    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)
        ' Longer timeout for deep checks (2-5 seconds expected)
        _httpClient.Timeout = TimeSpan.FromSeconds(30)
    End Sub

    Public Async Function CheckDeepStatusAsync() As Task(Of DependencyCheckResponse)
        Try
            ' Make the GET request (no authentication required)
            Dim response As HttpResponseMessage = Await _httpClient.GetAsync("/v1/rest/status/deep")
            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 passed deep health checks.")
            ElseIf CInt(response.StatusCode) = 503 Then
                Console.WriteLine("One or more dependencies failed deep health checks:")
                For Each dep In result.Dependencies
                    If dep.Status <> "Healthy" Then
                        Console.WriteLine($"  - {dep.Name}: {dep.Status}")
                        Console.WriteLine($"    Message: {dep.Message}")
                    End If
                Next
            End If

            Return result
        Catch ex As TaskCanceledException
            Console.WriteLine("Deep status check timed out. The service may be under heavy load.")
            Throw
        Catch ex As Exception
            Console.WriteLine($"Deep 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 DeepStatusClient()
Dim statusResponse As DependencyCheckResponse = Await client.CheckDeepStatusAsync()

Console.WriteLine($"Overall Status: {statusResponse.Status}")
Console.WriteLine("Dependency Details:")
For Each dep In statusResponse.Dependencies
    Dim indicator As String = If(dep.Status = "Healthy", "[OK]", "[FAIL]")
    Console.WriteLine($"  {indicator} {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 DeepStatusClient {
    private final HttpClient httpClient;
    private final String baseUrl;
    private final ObjectMapper objectMapper;

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

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

        // Build the HTTP request (no authentication required)
        // Use a longer timeout for deep checks (2-5 seconds expected)
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(endpoint))
            .timeout(Duration.ofSeconds(30))
            .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 passed deep health checks.");
        } else if (response.statusCode() == 503) {
            System.out.println("One or more dependencies failed deep health checks:");
            for (DependencyStatus dep : result.dependencies) {
                if (!"Healthy".equals(dep.status)) {
                    System.out.println("  - " + dep.name + ": " + dep.status);
                    System.out.println("    Message: " + 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 {
            DeepStatusClient client = new DeepStatusClient();
            DependencyCheckResponse result = client.checkDeepStatus();

            System.out.println("Overall Status: " + result.status);
            System.out.println("Dependency Details:");
            for (DependencyStatus dep : result.dependencies) {
                String indicator = "Healthy".equals(dep.status) ? "[OK]" : "[FAIL]";
                System.out.println("  " + indicator + " " + dep.name + ": " + dep.status + " - " + dep.message);
            }
        } catch (Exception e) {
            System.out.println("Deep status check failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
require 'net/http'
require 'uri'
require 'json'
require 'timeout'

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

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

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

    # Send the request with a longer timeout for deep checks (2-5 seconds expected)
    response = Timeout.timeout(30) do
      Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
        http.read_timeout = 30
        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 passed deep health checks.'
    when 503
      puts 'One or more dependencies failed deep health checks:'
      result['dependencies']&.each do |dep|
        unless dep['status'] == 'Healthy'
          puts "  - #{dep['name']}: #{dep['status']}"
          puts "    Message: #{dep['message']}"
        end
      end
    else
      raise "Unexpected status code: #{response.code}"
    end

    result
  rescue Timeout::Error
    puts 'Deep status check timed out. The service may be under heavy load.'
    raise
  rescue StandardError => e
    puts "Deep status check failed: #{e.message}"
    raise
  end
end

# Example usage:
client = DeepStatusClient.new
result = client.check_deep_status

puts "Overall Status: #{result['status']}"
puts 'Dependency Details:'
result['dependencies']&.each do |dep|
  indicator = dep['status'] == 'Healthy' ? '[OK]' : '[FAIL]'
  puts "  #{indicator} #{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": "Full health check passed - transaction processing operational"
    },
    {
      "name": "Database",
      "status": "Healthy",
      "message": "Full health check passed - read/write operations verified"
    },
    {
      "name": "AWS Cognito",
      "status": "Healthy",
      "message": "Full health check passed - authentication service operational"
    },
    {
      "name": "Cache Service",
      "status": "Healthy",
      "message": "Full health check passed - cache read/write operations verified"
    }
  ]
}

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

{
  "status": "Unhealthy",
  "dependencies": [
    {
      "name": "TransIT Gateway",
      "status": "Healthy",
      "message": "Full health check passed - transaction processing operational"
    },
    {
      "name": "Database",
      "status": "Unhealthy",
      "message": "Health check failed - read operation timed out after 5000ms"
    },
    {
      "name": "AWS Cognito",
      "status": "Healthy",
      "message": "Full health check passed - authentication service operational"
    },
    {
      "name": "Cache Service",
      "status": "Unhealthy",
      "message": "Health check failed - write operation returned error: connection refused"
    }
  ]
}

Error Response (500 Internal Server Error)

{
  "status": "Unhealthy",
  "responseStatus": "Error",
  "responseMessage": "An unexpected error occurred while performing deep health checks",
  "correlationId": "abc123-def456-ghi789"
}

Response Fields

Field Type Description
status string Overall status - "Healthy" if all dependencies pass deep checks, "Unhealthy" if any dependency fails
dependencies array Array of dependency status objects detailing each downstream service's full health check result
dependencies[].name string Name of the downstream dependency (e.g., "TransIT Gateway", "Database")
dependencies[].status string Dependency status - "Healthy" or "Unhealthy"
dependencies[].message string Detailed message describing the full health check result, including specific operations verified 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

Shallow vs. Deep Checks

Understanding the difference between shallow and deep checks is important for choosing the right endpoint:

Aspect Shallow Check Deep Check
What it tests Token-only connectivity (can the service reach the dependency?) Full operational health (can the dependency perform its actual functions?)
Response time ~500ms ~2-5 seconds
Performance impact Minimal Moderate - performs actual operations on dependencies
Suitable for automation Yes - safe for frequent polling (every 1-5 minutes) No - use sparingly (manual or infrequent scheduled checks)
Failure detection Detects connectivity failures and complete outages Detects connectivity failures, partial degradation, and functional errors

Common Use Cases

1. Detailed Diagnostics

Investigate dependency health when issues are suspected:

  • Use when the shallow check reports an unhealthy dependency
  • Get specific details about what operations are failing
  • Identify partial degradation that shallow checks cannot detect
  • Provide detailed health reports to operations teams

2. Troubleshooting and Incident Response

Diagnose issues during active incidents:

  • Run a deep check to determine the exact state of each dependency
  • Use the detailed messages to identify root causes
  • Correlate dependency failures with application errors
  • Document dependency health state for incident reports

3. Post-Deployment Validation

Confirm full system health after changes:

  • Run a deep check after deploying new service versions
  • Verify that configuration changes have not broken dependency connectivity
  • Confirm that all dependencies are fully operational before routing traffic
  • Include in deployment runbooks as a validation step

4. Scheduled Health Reports

Generate periodic comprehensive health reports:

  • Schedule deep checks once per hour or less frequently
  • Store results for historical health trend analysis
  • Generate SLA compliance reports based on deep check results
  • Compare deep check results over time to identify degradation patterns

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, post-deployment validation

Additional Notes

  • No Authentication: This endpoint intentionally does not require authentication for easier operations access during incident response.
  • Full Health Checks: Unlike the shallow check, the deep check exercises actual operations on each dependency (e.g., database read/write, gateway connectivity tests).
  • Longer Response Time: Expect 2-5 seconds for a complete response. Set client-side timeouts of at least 30 seconds to account for slow dependencies.
  • Performance Impact: Deep checks perform real operations on dependencies. Do not use this endpoint for frequent automated polling, as it can add unnecessary load to downstream services.
  • HTTP Status Codes: Returns HTTP 200 when all dependencies pass deep checks, HTTP 503 when one or more fail, and HTTP 500 for unexpected errors.
  • The dependencies array always includes all monitored downstream services, regardless of their individual status.
  • The message field provides detailed context about what was tested and the specific result or error encountered.
  • For routine monitoring, prefer the Shallow Status endpoint. Reserve deep checks for diagnostics and troubleshooting.
  • A dependency that passes shallow checks but fails deep checks may have partial functionality issues (e.g., read-only mode, degraded performance).

Troubleshooting

503 Service Unavailable

  • One or more dependencies failed their full health check
  • Inspect the dependencies array to identify which specific dependencies are unhealthy
  • Review the message field for each unhealthy dependency to understand the specific failure
  • Check whether the dependency is experiencing a known outage or maintenance window
  • Verify network connectivity between the Integration Service and the failing dependency

500 Internal Server Error

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

Timeout / No Response

  • Deep checks take 2-5 seconds normally; ensure your client timeout is at least 30 seconds
  • If the check times out, the service may be under severe load or a dependency check is hanging
  • Try the Shallow Status endpoint first to quickly identify unreachable dependencies
  • Check DNS resolution for the API domain
  • Verify firewall rules allow outbound HTTPS traffic

Dependency Passes Shallow but Fails Deep

  • The dependency is reachable but not fully operational
  • Common causes: database in read-only mode, gateway rejecting operations, cache returning stale data
  • Review the message field for the specific operation that failed
  • Contact the dependency team or vendor with the specific error details
  • Contact Procare Pay support if the issue persists and appears to be on the Integration Service side

Intermittent Failures

  • If a dependency shows "Unhealthy" intermittently, it may be experiencing load-related issues
  • Run the deep check 2-3 times in succession to confirm the failure is persistent
  • Compare with shallow check results to determine if the issue is connectivity or functionality
  • Contact support with the correlation IDs from multiple failed checks for investigation