Procare Pay Integration Service

Complete API Documentation for Payment Processing

Get Upcoming Holidays

GET /v1/rest/holidays

Description: Retrieves a list of upcoming U.S. banking holidays that may affect ACH payment processing and settlement timing.

What is this endpoint used for?

This endpoint provides information about upcoming banking holidays to help you plan payment processing:

  • ACH Processing Planning: ACH transactions do not process on banking holidays
  • Settlement Timing: Understand when funds will be available after banking holidays
  • User Communication: Inform customers about potential delays during holiday periods
  • Scheduling Automation: Avoid scheduling automatic payments on banking holidays
  • Business Logic: Build holiday-aware payment scheduling features
Important Banking Holiday Notes:
  • ACH transactions submitted on or before a banking holiday will not be processed until the next business day
  • Credit card transactions are typically processed normally on banking holidays
  • Settlement timing may be delayed by 1-2 business days when holidays fall on processing days
  • This list includes Federal Reserve Banking Holidays recognized by the U.S. banking system

Authentication

This endpoint requires bearer token authentication using the Authorization header.

Note: The bearer token must be a valid Cognito token obtained through the OAuth2 authentication flow.

Code Examples

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

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

    public HolidaysClient(string bearerToken)
    {
        _bearerToken = bearerToken;
        _httpClient = new HttpClient();
        _httpClient.BaseAddress = new Uri(_baseUrl);
        _httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", _bearerToken);
        _httpClient.DefaultRequestHeaders.Accept.Add(
            new MediaTypeWithQualityHeaderValue("application/json"));
    }

    public async Task<HolidaysResponse> GetUpcomingHolidaysAsync()
    {
        try
        {
            // Make the GET request
            var response = await _httpClient.GetAsync("/v1/rest/holidays");

            // Check response status
            if (response.IsSuccessStatusCode)
            {
                var responseBody = await response.Content.ReadAsStringAsync();
                var holidays = JsonSerializer.Deserialize<HolidaysResponse>(responseBody);
                return holidays;
            }
            else
            {
                throw new HttpRequestException($"Request failed with status: {response.StatusCode}");
            }
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"Request error: {ex.Message}");
            throw;
        }
    }
}

public class HolidaysResponse
{
    public List<Holiday> Holidays { get; set; }
}

public class Holiday
{
    public string Date { get; set; }
    public string Name { get; set; }
}

// Example usage:
var client = new HolidaysClient("your-bearer-token-here");
var response = await client.GetUpcomingHolidaysAsync();

foreach (var holiday in response.Holidays)
{
    Console.WriteLine($"{holiday.Date}: {holiday.Name}");
}
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Text.Json

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

    Public Sub New(bearerToken As String)
        _bearerToken = bearerToken
        _httpClient = New HttpClient()
        _httpClient.BaseAddress = New Uri(_baseUrl)
        _httpClient.DefaultRequestHeaders.Authorization = _
            New AuthenticationHeaderValue("Bearer", _bearerToken)
        _httpClient.DefaultRequestHeaders.Accept.Add( _
            New MediaTypeWithQualityHeaderValue("application/json"))
    End Sub

    Public Async Function GetUpcomingHolidaysAsync() As Task(Of HolidaysResponse)
        Try
            ' Make the GET request
            Dim response As HttpResponseMessage = Await _httpClient.GetAsync("/v1/rest/holidays")

            ' Check response status
            If response.IsSuccessStatusCode Then
                Dim responseBody As String = Await response.Content.ReadAsStringAsync()
                Dim holidays As HolidaysResponse = JsonSerializer.Deserialize(Of HolidaysResponse)(responseBody)
                Return holidays
            Else
                Throw New HttpRequestException($"Request failed with status: {response.StatusCode}")
            End If
        Catch ex As HttpRequestException
            Console.WriteLine($"Request error: {ex.Message}")
            Throw
        End Try
    End Function
End Class

Public Class HolidaysResponse
    Public Property Holidays As List(Of Holiday)
End Class

Public Class Holiday
    Public Property [Date] As String
    Public Property Name As String
End Class

' Example usage:
Dim client As New HolidaysClient("your-bearer-token-here")
Dim response As HolidaysResponse = Await client.GetUpcomingHolidaysAsync()

For Each holiday In response.Holidays
    Console.WriteLine($"{holiday.Date}: {holiday.Name}")
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 HolidaysClient {
    private final HttpClient httpClient;
    private final String baseUrl;
    private final String bearerToken;
    private final ObjectMapper objectMapper;

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

    public HolidaysResponse getUpcomingHolidays() throws Exception {
        // Construct the endpoint URL
        String endpoint = baseUrl + "/v1/rest/holidays";

        // Build the HTTP request
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(endpoint))
            .header("Authorization", "Bearer " + bearerToken)
            .header("Accept", "application/json")
            .GET()
            .build();

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

        // Check response status
        if (response.statusCode() == 200) {
            return objectMapper.readValue(response.body(), HolidaysResponse.class);
        } else {
            throw new Exception("Request failed with status: " + response.statusCode());
        }
    }

    public static class HolidaysResponse {
        public List<Holiday> holidays;
    }

    public static class Holiday {
        public String date;
        public String name;
    }

    // Example usage
    public static void main(String[] args) {
        try {
            HolidaysClient client = new HolidaysClient("your-bearer-token-here");
            HolidaysResponse response = client.getUpcomingHolidays();

            for (Holiday holiday : response.holidays) {
                System.out.println(holiday.date + ": " + holiday.name);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
require 'net/http'
require 'uri'
require 'json'

class HolidaysClient
  def initialize(bearer_token)
    @bearer_token = bearer_token
    @base_url = 'https://your-api-domain.com'
  end

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

    # Create the HTTP request
    request = Net::HTTP::Get.new(uri)
    request['Authorization'] = "Bearer #{@bearer_token}"
    request['Accept'] = 'application/json'

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

    # Check response status
    if response.is_a?(Net::HTTPSuccess)
      JSON.parse(response.body)
    else
      raise "Request failed with status: #{response.code}"
    end
  rescue StandardError => e
    puts "Request error: #{e.message}"
    raise
  end
end

# Example usage:
client = HolidaysClient.new('your-bearer-token-here')
response = client.get_upcoming_holidays

response['holidays'].each do |holiday|
  puts "#{holiday['date']}: #{holiday['name']}"
end

Response Format

Success Response (200 OK)

{
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day"
    },
    {
      "date": "2026-01-19",
      "name": "Martin Luther King Jr. Day"
    },
    {
      "date": "2026-02-16",
      "name": "Presidents' Day"
    },
    {
      "date": "2026-05-25",
      "name": "Memorial Day"
    },
    {
      "date": "2026-07-03",
      "name": "Independence Day (Observed)"
    },
    {
      "date": "2026-09-07",
      "name": "Labor Day"
    },
    {
      "date": "2026-10-12",
      "name": "Columbus Day"
    },
    {
      "date": "2026-11-11",
      "name": "Veterans Day"
    },
    {
      "date": "2026-11-26",
      "name": "Thanksgiving Day"
    },
    {
      "date": "2026-12-25",
      "name": "Christmas Day"
    }
  ]
}

Response Fields

Field Type Description
holidays array Array of holiday objects
holidays[].date string (date) Date of the holiday in ISO 8601 format (YYYY-MM-DD)
holidays[].name string Name of the holiday

Common Use Cases

1. Holiday-Aware Payment Scheduling

Check if a scheduled payment date falls on a banking holiday:

  • Fetch the holidays list and cache it
  • Compare scheduled payment dates against the holiday list
  • Adjust ACH payment dates to skip holidays automatically
  • Display warnings to users when scheduling payments near holidays

2. Settlement Date Calculation

Calculate accurate settlement dates considering holidays:

  • Add business days to transaction date, skipping weekends and holidays
  • Display expected deposit dates to merchants
  • Set appropriate expectations for fund availability

3. Customer Communication

Inform customers about processing delays:

  • Display upcoming holidays that may affect payment processing
  • Send proactive notifications about holiday-related delays
  • Provide accurate information in help documentation

4. Automated Payment Systems

Build intelligent recurring payment systems:

  • Automatically skip banking holidays for ACH payments
  • Move scheduled payments to the previous or next business day
  • Maintain consistent payment cadence despite holidays

Additional Notes

  • The holidays returned are U.S. Federal Reserve Banking Holidays recognized by the American banking system.
  • The list typically includes holidays for the current year and the next 12-18 months.
  • When a holiday falls on a weekend, the observed date (usually Friday or Monday) is returned.
  • This endpoint can be called frequently as the data is relatively static. Consider caching the response for 24-48 hours.
  • ACH-specific impact: ACH transactions submitted on a holiday will not process until the next business day. Plan accordingly for time-sensitive payments.
  • Credit card processing: Credit card transactions are generally not affected by banking holidays, though settlement timing may be delayed.
  • Regional or state-specific holidays are not included; only federally recognized banking holidays are returned.
  • The holiday list is maintained by Procare Pay and updated annually to reflect any changes to the Federal Reserve holiday schedule.

Troubleshooting

500 Internal Server Error

  • This is a rare error for this endpoint as it has no parameters
  • Retry the request after a brief delay
  • If the error persists, contact Procare Pay support

401 Unauthorized

  • Ensure your bearer token is valid and not expired
  • Refresh your Cognito authentication token if needed
  • Verify you're using the correct authentication endpoint

Empty Holidays Array

  • If the holidays array is empty, it may indicate a data synchronization issue
  • Contact support if you receive an empty response
  • As a fallback, you can hardcode major U.S. banking holidays in your application