Procare Pay Integration Service

Complete API Documentation for Payment Processing

Get Payor by ID

GET /v1/rest/merchants/{merchantId}/payors/{payorId}

Description: Gets the payor's information and saved payment methods for a specific merchant and payor combination.

Path Parameters

merchantId (required)
Type: string
Pattern: Must be an 11-digit number (e.g., "12345678901")
Description: The 11-digit merchant identifier
payorId (required)
Type: string
Description: The unique payor identifier

Authentication

This endpoint requires bearer token authentication using the Authorization header.

Note: The bearer token must be a valid Cognito token.

Code Examples

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

public class PayorClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://your-api-domain.com"; // Replace with actual base URL
    private readonly string _bearerToken;

    public PayorClient(string bearerToken)
    {
        _bearerToken = bearerToken;
        _httpClient = new HttpClient();
        _httpClient.BaseAddress = new Uri(_baseUrl);

        // Set the Authorization header with bearer token
        _httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", _bearerToken);

        // Set Accept header to request JSON
        _httpClient.DefaultRequestHeaders.Accept.Add(
            new MediaTypeWithQualityHeaderValue("application/json"));
    }

    public async Task<string> GetPayorByIdAsync(string merchantId, string payorId)
    {
        try
        {
            // Construct the endpoint URL
            string endpoint = $"/v1/rest/merchants/{merchantId}/payors/{payorId}";

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

            // Ensure the request was successful
            response.EnsureSuccessStatusCode();

            // Read and return the response content as a string
            string responseBody = await response.Content.ReadAsStringAsync();
            return responseBody;
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request error: {e.Message}");
            throw;
        }
    }
}

// Example usage:
var client = new PayorClient("your-bearer-token-here");
string result = await client.GetPayorByIdAsync("12345678901", "payor123");
Console.WriteLine(result);
Imports System
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Threading.Tasks

Public Class PayorClient
    Private ReadOnly _httpClient As HttpClient
    Private ReadOnly _baseUrl As String = "https://your-api-domain.com" ' Replace with actual base URL
    Private ReadOnly _bearerToken As String

    Public Sub New(bearerToken As String)
        _bearerToken = bearerToken
        _httpClient = New HttpClient()
        _httpClient.BaseAddress = New Uri(_baseUrl)

        ' Set the Authorization header with bearer token
        _httpClient.DefaultRequestHeaders.Authorization = _
            New AuthenticationHeaderValue("Bearer", _bearerToken)

        ' Set Accept header to request JSON
        _httpClient.DefaultRequestHeaders.Accept.Add( _
            New MediaTypeWithQualityHeaderValue("application/json"))
    End Sub

    Public Async Function GetPayorByIdAsync(merchantId As String, payorId As String) As Task(Of String)
        Try
            ' Construct the endpoint URL
            Dim endpoint As String = $"/v1/rest/merchants/{merchantId}/payors/{payorId}"

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

            ' Ensure the request was successful
            response.EnsureSuccessStatusCode()

            ' Read and return the response content as a string
            Dim responseBody As String = Await response.Content.ReadAsStringAsync()
            Return responseBody

        Catch e As HttpRequestException
            Console.WriteLine($"Request error: {e.Message}")
            Throw
        End Try
    End Function
End Class

' Example usage:
Dim client As New PayorClient("your-bearer-token-here")
Dim result As String = Await client.GetPayorByIdAsync("12345678901", "payor123")
Console.WriteLine(result)
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

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

    public PayorClient(String baseUrl, String bearerToken) {
        this.baseUrl = baseUrl;
        this.bearerToken = bearerToken;
        this.httpClient = HttpClient.newHttpClient();
    }

    public String getPayorById(String merchantId, String payorId)
            throws IOException, InterruptedException {
        try {
            // Construct the endpoint URL
            String endpoint = String.format("%s/v1/rest/merchants/%s/payors/%s",
                baseUrl, merchantId, payorId);

            // 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 if request was successful (status code 200-299)
            if (response.statusCode() < 200 || response.statusCode() >= 300) {
                throw new RuntimeException("HTTP Error: " + response.statusCode() +
                    " - " + response.body());
            }

            // Return the response body
            return response.body();

        } catch (IOException | InterruptedException e) {
            System.err.println("Request error: " + e.getMessage());
            throw e;
        }
    }

    // Example usage
    public static void main(String[] args) {
        try {
            PayorClient client = new PayorClient(
                "https://your-api-domain.com",
                "your-bearer-token-here"
            );

            String result = client.getPayorById("12345678901", "payor123");
            System.out.println(result);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
require 'net/http'
require 'uri'
require 'json'

class PayorClient
  def initialize(base_url, bearer_token)
    @base_url = base_url
    @bearer_token = bearer_token
  end

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

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

    # Make the request
    response = Net::HTTP.start(uri.hostname, uri.port,
                               use_ssl: uri.scheme == 'https') do |http|
      http.request(request)
    end

    # Check response status
    unless response.is_a?(Net::HTTPSuccess)
      raise "HTTP Error: #{response.code} - #{response.message}\n#{response.body}"
    end

    # Return the response body
    response.body

  rescue StandardError => e
    puts "Request error: #{e.message}"
    raise
  end
end

# Example usage
begin
  client = PayorClient.new(
    'https://your-api-domain.com',
    'your-bearer-token-here'
  )

  result = client.get_payor_by_id('12345678901', 'payor123')
  puts result

rescue => e
  puts "Error: #{e.message}"
end

Response Fields

Field Type Description
responseStatus string Indicates the status of the request (e.g., TransactionApproved, Error, SavedPaymentMethodCreated, etc.)
responseMessage string Human-readable, customer-facing message suitable for displaying to end users
responseCode string Alpha-numeric response code that represents the description of the response
responseReason string Actionable, descriptive message of any action that can be taken by the integrator to make a resubmission succeed
responseResult string Response result - can be "success", "failure", or "retry"
legacyResponseCode string Deprecated response code for faster integration (supported until v2)
correlationId string The logging correlation ID for the request, useful for troubleshooting
customAttributes object Name/value collection of custom attributes for the transaction
payorId string The unique identifier for the payor
payorIdLimitedBitFlag boolean Indicates whether the Payor ID uses 64-bit integer format (true) or GUID format (false)
applicationId string The identifier of the application that initiated creation of the payor profile
customerAccountId string The external customer ID for this payor profile
createdDate string (date-time) The date and time when the payor record was created
isDeleted boolean Indicates whether the payor profile record is marked as deleted
accountStatus string The current status of the payor account
deletedDate string (date-time) The date and time when the record was flagged as deleted (null if not deleted)
defaultSavedPaymentMethodId string The ID of the default payment method for this payor (can be ACH or credit card)
savedPaymentMethodIds array of strings A list of all saved payment method IDs associated with this payor
savedPaymentMethods array of objects The complete list of saved payment method details (see SavedPaymentMethodResponse schema)
customerData object Key-value pairs containing additional custom customer data

Example Response

{
  "responseStatus": "Accepted",
  "responseCode": "200",
  "responseResult": "Success",
  "legacyResponseCode": "A",
  "correlationId": "abc123-def456-ghi789",
  "payorId": "5513027774438108364",
  "payorIdLimitedBitFlag": true,
  "applicationId": "14",
  "customerAccountId": "CUST-12345",
  "createdDate": "2024-01-15T10:30:00Z",
  "isDeleted": false,
  "accountStatus": "Active",
  "deletedDate": null,
  "defaultSavedPaymentMethodId": "PM-001",
  "savedPaymentMethodIds": [
    "5513027774438108365",
    "5513027774438108366"
  ],
  "savedPaymentMethods": [
    {
      "savedPaymentMethodId": "5513027774438108365",
      "accountType": "VISA",
      "maskedAccountNumber": "************1234",
      "lastFour": "1234",
      "cardExpiry": "1225",
      "accountHolderFirstName": "John",
      "accountHolderLastName": "Doe",
      "accountHolderStreetLine1": "123 Main St",
      "accountHolderCity": "Springfield",
      "accountHolderRegion": "IL",
      "accountHolderPostalCode": "62701",
      "accountHolderEmail": "john.doe@example.com",
      "isDeleted": false,
      "isDefaultAccount": true,
      "createdDate": "2024-01-15T10:30:00Z"
    },
    {
      "savedPaymentMethodId": "5513027774438108366",
      "accountType": "ECHK",
      "maskedAccountNumber": "******7890",
      "lastFour": "7890",
      "abaRoutingNumber": "123456789",
      "accountHolderFirstName": "John",
      "accountHolderLastName": "Doe",
      "isDeleted": false,
      "isDefaultAccount": false,
      "createdDate": "2024-02-01T14:20:00Z"
    }
  ],
  "customerData": {
    "preferredContact": "email",
    "vipCustomer": "true"
  }
}

HTTP Status Codes

Status Code Description
200 Success - Payor information retrieved successfully
400 Bad Request - Invalid merchantId or payorId format
404 Not Found - Payor with the specified ID does not exist for this merchant
500 Internal Server Error - Server encountered an unexpected error

Additional Notes

  • The merchantId must be exactly 11 digits. Requests with invalid formats will return a 400 Bad Request error.
  • The response includes both a summary of saved payment method IDs and the full details in the savedPaymentMethods array.
  • Sensitive payment information (full account numbers, CVV) is never returned - only masked values are included.
  • The correlationId is useful for troubleshooting and should be provided when contacting support.
  • The isDeleted flag indicates soft-deleted records that may still be retrievable but are no longer active.
  • Custom attributes allow you to store additional metadata specific to your integration needs.