Procare Pay Integration Service

Complete API Documentation for Payment Processing

Get Simple Service Status

GET /v1/rest/status

Description: Returns a simple liveness status indicating whether the Integration Service API is up and running. This endpoint performs a lightweight token-only connectivity check against all downstream dependencies.

What is this endpoint used for?

This endpoint provides a quick health check for monitoring and operations:

  • Service Availability: Verify the API is accessible and responding
  • Load Balancer Health Checks: Configure as a health check endpoint for load balancers
  • Monitoring Systems: Integrate with monitoring tools like Pingdom, DataDog, or New Relic
  • Uptime Tracking: Monitor service uptime and availability
  • Quick Diagnostics: Get a fast status check without detailed dependency information
No Authentication Required: This endpoint does NOT require authentication, making it suitable for public health checks and monitoring systems.

Code Examples

using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text.Json;

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

    public StatusClient()
    {
        _httpClient = new HttpClient();
        _httpClient.BaseAddress = new Uri(_baseUrl);
        _httpClient.Timeout = TimeSpan.FromSeconds(5); // Short timeout for health checks
    }

    public async Task<bool> CheckServiceStatusAsync()
    {
        try
        {
            // Make the GET request (no authentication required)
            var response = await _httpClient.GetAsync("/v1/rest/status");

            // Check response status
            if (response.IsSuccessStatusCode)
            {
                var responseBody = await response.Content.ReadAsStringAsync();
                var status = JsonSerializer.Deserialize<StatusResponse>(responseBody);

                return status.Status.Equals("Up", StringComparison.OrdinalIgnoreCase);
            }
            else
            {
                Console.WriteLine($"Service returned status code: {response.StatusCode}");
                return false;
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Health check failed: {ex.Message}");
            return false;
        }
    }
}

public class StatusResponse
{
    public string Status { get; set; }
}

// Example usage:
var statusClient = new StatusClient();
bool isServiceUp = await statusClient.CheckServiceStatusAsync();

if (isServiceUp)
{
    Console.WriteLine("✓ Service is UP and healthy");
}
else
{
    Console.WriteLine("✗ Service is DOWN or unhealthy");
}
Imports System.Net.Http
Imports System.Text.Json

Public Class StatusClient
    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(5) ' Short timeout for health checks
    End Sub

    Public Async Function CheckServiceStatusAsync() As Task(Of Boolean)
        Try
            ' Make the GET request (no authentication required)
            Dim response As HttpResponseMessage = Await _httpClient.GetAsync("/v1/rest/status")

            ' Check response status
            If response.IsSuccessStatusCode Then
                Dim responseBody As String = Await response.Content.ReadAsStringAsync()
                Dim statusObj As StatusResponse = JsonSerializer.Deserialize(Of StatusResponse)(responseBody)

                Return statusObj.Status.Equals("Up", StringComparison.OrdinalIgnoreCase)
            Else
                Console.WriteLine($"Service returned status code: {response.StatusCode}")
                Return False
            End If
        Catch ex As Exception
            Console.WriteLine($"Health check failed: {ex.Message}")
            Return False
        End Try
    End Function
End Class

Public Class StatusResponse
    Public Property Status As String
End Class

' Example usage:
Dim statusClient As New StatusClient()
Dim isServiceUp As Boolean = Await statusClient.CheckServiceStatusAsync()

If isServiceUp Then
    Console.WriteLine("✓ Service is UP and healthy")
Else
    Console.WriteLine("✗ Service is DOWN or unhealthy")
End If
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;

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

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

    public boolean checkServiceStatus() {
        try {
            // Construct the endpoint URL
            String endpoint = baseUrl + "/v1/rest/status";

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

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

            // Check response status
            if (response.statusCode() == 200) {
                StatusResponse status = objectMapper.readValue(
                    response.body(),
                    StatusResponse.class
                );
                return "Up".equalsIgnoreCase(status.status);
            } else {
                System.out.println("Service returned status code: " + response.statusCode());
                return false;
            }
        } catch (Exception e) {
            System.out.println("Health check failed: " + e.getMessage());
            return false;
        }
    }

    public static class StatusResponse {
        public String status;
    }

    // Example usage
    public static void main(String[] args) {
        StatusClient client = new StatusClient();
        boolean isServiceUp = client.checkServiceStatus();

        if (isServiceUp) {
            System.out.println("✓ Service is UP and healthy");
        } else {
            System.out.println("✗ Service is DOWN or unhealthy");
        }
    }
}
require 'net/http'
require 'uri'
require 'json'
require 'timeout'

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

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

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

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

      # Check response status
      if response.is_a?(Net::HTTPSuccess)
        result = JSON.parse(response.body)
        result['status']&.downcase == 'up'
      else
        puts "Service returned status code: #{response.code}"
        false
      end
    rescue StandardError => e
      puts "Health check failed: #{e.message}"
      false
    end
  end
end

# Example usage:
client = StatusClient.new
is_service_up = client.check_service_status

if is_service_up
  puts "✓ Service is UP and healthy"
else
  puts "✗ Service is DOWN or unhealthy"
end

Response Format

Success Response (200 OK)

{
  "status": "Up"
}

Error Response (500 Internal Server Error)

{
  "status": "Down",
  "responseStatus": "Error",
  "responseMessage": "Service is experiencing issues",
  "correlationId": "abc123-def456-ghi789"
}

Response Fields

Field Type Description
status string Service status - either "Up" or "Down"
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. Load Balancer Health Checks

Configure this endpoint as a health check target:

  • Set as the health check URL in AWS ELB, ALB, or NLB
  • Configure with a 5-second timeout
  • Expect HTTP 200 status code for healthy instances
  • Set health check interval to 30 seconds

2. Monitoring and Alerting

Integrate with monitoring systems:

  • Poll this endpoint every 1-5 minutes from your monitoring tool
  • Trigger alerts if status returns "Down" or HTTP 500
  • Track uptime percentage over time
  • Create dashboards showing service availability

3. Circuit Breaker Pattern

Implement circuit breakers in your application:

  • Check status before making expensive API calls
  • Open circuit if service returns "Down"
  • Avoid cascading failures in distributed systems
  • Implement exponential backoff for retries

4. Pre-Flight Checks

Verify service availability before critical operations:

  • Check status before processing batch payments
  • Validate service health during application startup
  • Ensure connectivity before scheduled jobs

Additional Notes

  • No Authentication: This endpoint intentionally does not require authentication for easier monitoring setup.
  • Lightweight Check: This performs only a token-only connectivity check to dependencies, not a full health verification.
  • Fast Response: Designed to respond quickly (typically under 500ms) for timely health assessments.
  • Load Balancer Safe: Can be called frequently without impacting service performance.
  • A "Up" status indicates the service is running but does NOT guarantee all dependencies are fully operational.
  • For detailed dependency health information, use the Shallow Status or Deep Status endpoints.
  • This endpoint returns HTTP 200 even when dependencies have issues (status: "Up" with warnings in other endpoints).
  • HTTP 500 responses indicate the service itself is experiencing critical issues.

Comparison with Other Status Endpoints

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

Troubleshooting

500 Internal Server Error

  • The service is experiencing critical issues
  • 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
  • Service is completely unavailable or experiencing severe load
  • Check DNS resolution for the API domain
  • Verify firewall rules allow outbound HTTPS traffic

Status Returns "Down"

  • Service is running but one or more critical dependencies are unavailable
  • Check Shallow Status for dependency details
  • Wait for automatic recovery (usually 1-5 minutes)
  • Contact support if issue persists beyond 10 minutes