Procare Pay Integration Service

Complete API Documentation for Payment Processing

Get Merchant Information

GET /v1/rest/merchants/{merchantId}

Description: Retrieves detailed information about a specific merchant, including their payment processing capabilities, configuration settings, and account status.

What is this endpoint used for?

This endpoint allows you to look up information about a merchant account. Think of it like checking a store's payment capabilities:

  • Check payment acceptance: See which credit card brands (Visa, Mastercard, Amex, etc.) the merchant accepts
  • Verify ACH capability: Determine if the merchant can process bank account payments
  • Get transaction limits: Find out maximum amounts for card and ACH transactions
  • Validate merchant status: Confirm the merchant is active and properly configured
  • Integration setup: Retrieve merchant details during initial system integration

Path Parameters

merchantId (required)
Type: string
Pattern: Must be an 11-digit number (e.g., "12345678901")
Description: The unique 11-digit merchant identifier (also known as BAM ID)

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;

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

    public MerchantClient(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<string> GetMerchantAsync(string merchantId)
    {
        try
        {
            // Validate merchant ID format
            if (string.IsNullOrEmpty(merchantId) || merchantId.Length != 11)
            {
                throw new ArgumentException("Merchant ID must be 11 digits", nameof(merchantId));
            }

            // Construct the endpoint URL
            string endpoint = $"/v1/rest/merchants/{merchantId}";

            // Make the GET request
            HttpResponseMessage response = await _httpClient.GetAsync(endpoint);

            // Check response status
            if (response.IsSuccessStatusCode)
            {
                string responseBody = await response.Content.ReadAsStringAsync();
                return responseBody;
            }
            else if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
            {
                throw new Exception($"Merchant {merchantId} not found");
            }
            else
            {
                throw new HttpRequestException($"Request failed with status: {response.StatusCode}");
            }
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request error: {e.Message}");
            throw;
        }
    }
}

// Example usage:
var client = new MerchantClient("your-bearer-token-here");
string merchantInfo = await client.GetMerchantAsync("12345678901");
Console.WriteLine(merchantInfo);
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Threading.Tasks

Public Class MerchantClient
    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 GetMerchantAsync(merchantId As String) As Task(Of String)
        Try
            ' Validate merchant ID format
            If String.IsNullOrEmpty(merchantId) OrElse merchantId.Length <> 11 Then
                Throw New ArgumentException("Merchant ID must be 11 digits", NameOf(merchantId))
            End If

            ' Construct the endpoint URL
            Dim endpoint As String = $"/v1/rest/merchants/{merchantId}"

            ' Make the GET request
            Dim response As HttpResponseMessage = Await _httpClient.GetAsync(endpoint)

            ' Check response status
            If response.IsSuccessStatusCode Then
                Dim responseBody As String = Await response.Content.ReadAsStringAsync()
                Return responseBody
            ElseIf response.StatusCode = Net.HttpStatusCode.NotFound Then
                Throw New Exception($"Merchant {merchantId} not found")
            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

' Example usage:
Dim client As New MerchantClient("your-bearer-token-here")
Dim merchantInfo As String = Await client.GetMerchantAsync("12345678901")
Console.WriteLine(merchantInfo)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class MerchantClient {
    private final HttpClient httpClient;
    private final String baseUrl;
    private final String bearerToken;

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

    public String getMerchant(String merchantId) throws Exception {
        // Validate merchant ID format
        if (merchantId == null || merchantId.length() != 11) {
            throw new IllegalArgumentException("Merchant ID must be 11 digits");
        }

        // Construct the endpoint URL
        String endpoint = baseUrl + "/v1/rest/merchants/" + merchantId;

        // 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 response.body();
        } else if (response.statusCode() == 404) {
            throw new Exception("Merchant " + merchantId + " not found");
        } else {
            throw new Exception("Request failed with status: " + response.statusCode());
        }
    }

    // Example usage
    public static void main(String[] args) {
        try {
            MerchantClient client = new MerchantClient("your-bearer-token-here");
            String merchantInfo = client.getMerchant("12345678901");
            System.out.println(merchantInfo);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
require 'net/http'
require 'uri'
require 'json'

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

  def get_merchant(merchant_id)
    # Validate merchant ID format
    raise ArgumentError, 'Merchant ID must be 11 digits' unless merchant_id&.length == 11

    # Construct the endpoint URL
    uri = URI("#{@base_url}/v1/rest/merchants/#{merchant_id}")

    # Create HTTP request
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true if uri.scheme == 'https'
    http.read_timeout = 30

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

    # Send request and handle response
    response = http.request(request)

    case response.code.to_i
    when 200
      JSON.parse(response.body)
    when 404
      raise "Merchant #{merchant_id} not found"
    else
      raise "Request failed with status: #{response.code} - #{response.message}"
    end
  rescue StandardError => e
    puts "Request error: #{e.message}"
    raise
  end
end

# Example usage:
client = MerchantClient.new('your-bearer-token-here')
merchant_info = client.get_merchant('12345678901')
puts JSON.pretty_generate(merchant_info)

end

def get_merchant(merchant_id)
# Validate merchant ID format
raise ArgumentError, 'Merchant ID must be 11 digits' unless merchant_id&.length == 11

# Construct the endpoint URL
uri = URI("#{@base_url}/v1/rest/merchants/#{merchant_id}")

# Create HTTP request
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true if uri.scheme == 'https'
http.read_timeout = 30

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

# Send request and handle response
response = http.request(request)

case response.code.to_i
when 200
JSON.parse(response.body)
when 404
raise "Merchant #{merchant_id} not found"
else
raise "Request failed with status: #{response.code} - #{response.message}"
end
rescue StandardError => e
puts "Request error: #{e.message}"
raise
end
end

# Example usage:
client = MerchantClient.new('your-bearer-token-here')
merchant_info = client.get_merchant('12345678901')
puts JSON.pretty_generate(merchant_info)
            

Response Fields

Field Type Description
merchantId string The unique 11-digit merchant identifier
merchantName string The merchant's business name
acceptsVisa boolean Indicates whether the merchant accepts Visa credit cards
acceptsMastercard boolean Indicates whether the merchant accepts Mastercard credit cards
acceptsAmericanExpress boolean Indicates whether the merchant accepts American Express credit cards
acceptsDiscover boolean Indicates whether the merchant accepts Discover credit cards
acceptsJcb boolean Indicates whether the merchant accepts JCB credit cards
acceptsAch boolean Indicates whether the merchant accepts ACH (bank account) transactions
maxCardTransaction decimal The maximum transaction amount allowed for credit card payments
maxAchTransaction decimal The maximum transaction amount allowed for ACH payments
merchantCreatedDate string (date-time) The date and time when the merchant account was created
mostRecentAcquirerBoardDate string (date-time) The most recent date the merchant was boarded with the acquirer
mostRecentAcquirerClosedDate string (date-time) The most recent date the merchant's acquirer account was closed (null if active)
teStatus string The Tuition Express status of the merchant account
merchantEmailAddresses string The merchant's email address(es) for notifications
merchantFundingModel string The funding model for the merchant: Unknown, Gross, or Net
customAttributes object Key-value pairs containing additional merchant-specific configuration

Example Response

{
  "merchantId": "12345678901",
  "merchantName": "Sunshine Childcare Center",
  "acceptsVisa": true,
  "acceptsMastercard": true,
  "acceptsAmericanExpress": true,
  "acceptsDiscover": true,
  "acceptsJcb": false,
  "acceptsAch": true,
  "maxCardTransaction": 5000.00,
  "maxAchTransaction": 10000.00,
  "merchantCreatedDate": "2023-06-15T08:30:00Z",
  "mostRecentAcquirerBoardDate": "2023-06-20T10:00:00Z",
  "mostRecentAcquirerClosedDate": null,
  "teStatus": "Active",
  "merchantEmailAddresses": "accounting@sunshinechildcare.com",
  "merchantFundingModel": "Gross",
  "customAttributes": {
    "region": "midwest",
    "accountManager": "Jane Smith",
    "tier": "premium"
  }
}

HTTP Status Codes

Status Code Description
200 Success - Merchant information retrieved successfully
400 Bad Request - Invalid merchant ID format (must be 11 digits)
401 Unauthorized - Missing or invalid authentication token
404 Not Found - Merchant with the specified ID does not exist
500 Internal Server Error - Server encountered an unexpected error

Understanding the Response

For Non-Technical Users

  • Payment Acceptance: The accepts* fields tell you which payment methods you can offer to customers at this merchant location
  • Transaction Limits: The maxCardTransaction and maxAchTransaction fields show the maximum amount you can charge in a single transaction
  • Account Status: The teStatus field indicates if the merchant account is active and able to process payments
  • Funding Model:
    • NextDayFunding: Merchant receives full transaction amount as a deposit on the next business day; fees and returns are withdrawn from the merchant bank account at the end of the month
    • Standard: Merchant receives transaction amount minus fees and returns within 5 business days

For Developers

  • Integration Logic: Use the accepts* flags to dynamically show/hide payment options in your UI
  • Validation: Check maxCardTransaction and maxAchTransaction before allowing users to submit large transactions
  • Configuration: Store merchant information in your application's cache to reduce API calls
  • Error Handling: Always handle 404 responses gracefully - the merchant may have been deactivated
  • Custom Attributes: Use this field for any merchant-specific settings your integration needs

Common Use Cases

1. Initial Application Setup

When a user first connects your application to their Procare Pay merchant account, call this endpoint to:

  • Verify the merchant ID is valid
  • Store merchant capabilities for future reference
  • Configure your UI based on accepted payment methods

2. Payment Method Selection

Before displaying payment options to a customer:

  • Check which card brands the merchant accepts
  • Show/hide ACH payment option based on acceptsAch
  • Display appropriate credit card logos

3. Transaction Validation

Before processing a payment:

  • Compare transaction amount against maxCardTransaction or maxAchTransaction
  • Prevent transactions that exceed merchant limits
  • Display helpful error messages to users

4. Merchant Status Monitoring

Periodically check merchant information to:

  • Detect if account has been closed (mostRecentAcquirerClosedDate)
  • Monitor changes in payment capabilities
  • Update cached merchant data

Additional Notes

  • The merchantId must be exactly 11 digits. The first 8 digits typically represent the BAM ID, and the last 3 digits represent additional configuration.
  • Merchant information is generally static but can change when merchant settings are updated. Consider caching this data with a reasonable TTL (e.g., 24 hours).
  • The teStatus field reflects the merchant's status in the Tuition Express payment gateway. An "Active" status is required for processing transactions.
  • If mostRecentAcquirerClosedDate has a value, the merchant account may be in the process of being closed or has been closed. Check with Procare Pay support before processing transactions.
  • The merchantFundingModel affects how funds are deposited to the merchant's bank account but does not impact API integration.
  • Maximum transaction limits (maxCardTransaction and maxAchTransaction) are set based on the merchant's agreement and risk profile. Transactions exceeding these limits will be declined.
  • The customAttributes field can contain integration-specific configuration. Check with your implementation team about which attributes are relevant to your use case.

Troubleshooting

404 Not Found

  • Verify the merchant ID is correct and exactly 11 digits
  • Confirm the merchant account exists in the Procare Pay system
  • Check if the merchant has been deactivated or deleted

401 Unauthorized

  • Ensure your bearer token is valid and not expired
  • Verify you have the correct authorization to access this merchant
  • Refresh your Cognito authentication token if needed

400 Bad Request

  • Check that the merchant ID is numeric and 11 digits long
  • Remove any spaces, dashes, or special characters from the merchant ID
  • Ensure you're not passing any unexpected query parameters