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
maxCardTransactionandmaxAchTransactionfields show the maximum amount you can charge in a single transaction - Account Status: The
teStatusfield 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
maxCardTransactionandmaxAchTransactionbefore 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
maxCardTransactionormaxAchTransaction - 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
merchantIdmust 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
teStatusfield reflects the merchant's status in the Tuition Express payment gateway. An "Active" status is required for processing transactions. - If
mostRecentAcquirerClosedDatehas 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
merchantFundingModelaffects how funds are deposited to the merchant's bank account but does not impact API integration. - Maximum transaction limits (
maxCardTransactionandmaxAchTransaction) are set based on the merchant's agreement and risk profile. Transactions exceeding these limits will be declined. - The
customAttributesfield 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