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
merchantIdmust 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
savedPaymentMethodsarray. - Sensitive payment information (full account numbers, CVV) is never returned - only masked values are included.
- The
correlationIdis useful for troubleshooting and should be provided when contacting support. - The
isDeletedflag 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.