Procare Pay Integration Service

Complete API Documentation for Payment Processing

Get Saved Payment Method by ID

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

Description: Gets the saved payment method details for a specific payment method associated with a payor under a merchant.

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
savedPaymentMethodId (required)
Type: string
Description: The unique identifier for the saved payment method

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 SavedPaymentMethodClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://your-api-domain.com"; // Replace with actual base URL
    private readonly string _bearerToken;

    public SavedPaymentMethodClient(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> GetSavedPaymentMethodByIdAsync(
        string merchantId,
        string payorId,
        string savedPaymentMethodId)
    {
        try
        {
            // Construct the endpoint URL
            string endpoint = $"/v1/rest/merchants/{merchantId}/payors/{payorId}" +
                            $"/savedPaymentMethods/{savedPaymentMethodId}";

            // 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 SavedPaymentMethodClient("your-bearer-token-here");
string result = await client.GetSavedPaymentMethodByIdAsync(
    "12345678901",      // merchantId
    "5513027774438108364",  // payorId
    "5513027774438108365"   // savedPaymentMethodId
);
Console.WriteLine(result);
Imports System
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Threading.Tasks

Public Class SavedPaymentMethodClient
    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 GetSavedPaymentMethodByIdAsync(
        merchantId As String,
        payorId As String,
        savedPaymentMethodId As String) As Task(Of String)

        Try
            ' Construct the endpoint URL
            Dim endpoint As String = $"/v1/rest/merchants/{merchantId}/payors/{payorId}" & _
                                    $"/savedPaymentMethods/{savedPaymentMethodId}"

            ' 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 SavedPaymentMethodClient("your-bearer-token-here")
Dim result As String = Await client.GetSavedPaymentMethodByIdAsync(
    "12345678901",              ' merchantId
    "5513027774438108364",      ' payorId
    "5513027774438108365"       ' savedPaymentMethodId
)
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 SavedPaymentMethodClient {
    private final HttpClient httpClient;
    private final String baseUrl;
    private final String bearerToken;

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

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

            // 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 {
            SavedPaymentMethodClient client = new SavedPaymentMethodClient(
                "https://your-api-domain.com",
                "your-bearer-token-here"
            );

            String result = client.getSavedPaymentMethodById(
                "12345678901",          // merchantId
                "5513027774438108364",  // payorId
                "5513027774438108365"   // savedPaymentMethodId
            );
            System.out.println(result);

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

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

  def get_saved_payment_method_by_id(merchant_id, payor_id, saved_payment_method_id)
    # Construct the endpoint URL
    endpoint = "#{@base_url}/v1/rest/merchants/#{merchant_id}/payors/#{payor_id}" \
               "/savedPaymentMethods/#{saved_payment_method_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 = SavedPaymentMethodClient.new(
    'https://your-api-domain.com',
    'your-bearer-token-here'
  )

  result = client.get_saved_payment_method_by_id(
    '12345678901',          # merchantId
    '5513027774438108364',  # payorId
    '5513027774438108365'   # savedPaymentMethodId
  )
  puts result

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

Response Fields

Field Type Description
responseStatus string Indicates the status of the request (e.g., SavedPaymentMethodCreated, SavedPaymentMethodUpdated, Error, 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
payorId string The unique identifier for the payor that owns this payment method
savedPaymentMethodId string The unique identifier for this saved payment method
savedPaymentMethodIdLimitedBitFlag boolean Indicates whether the ID uses 64-bit integer format (true) or GUID format (false)
createdDate string (date-time) The date and time when the payment method was created
accountType string The type of account - credit card brand (VISA, MC, DISC, AMEX) or ACH type (ECHK for checking, SAV for savings)
customerAccountId string The external customer ID for the associated payor profile
customerAccountType string The external account type (user-defined)
binId string Bank Identification Number (BIN) identifier for credit card accounts. Used to look up card issuer information.
maskedAccountNumber string The masked account number with only the last 4 digits visible (e.g., "************1234" for cards or "******7890" for ACH)
lastFour string The last four digits of the account number
cardExpiry string Credit card expiration date (for credit card accounts only). Format: MMyy, MMyyyy, or yyyyMMdd
abaRoutingNumber string The bank routing (ABA) number (for ACH accounts only)
accountHolderFirstName string The first name of the account holder
accountHolderLastName string The last name of the account holder
accountHolderStreetLine1 string The first line of the account holder's street address
accountHolderStreetLine2 string The second line of the account holder's street address (optional, for apartment/suite numbers)
accountHolderCity string The city of the account holder's address
accountHolderRegion string The region/state/province of the account holder's address
accountHolderPostalCode string The postal/ZIP code of the account holder's address
accountHolderPhoneNumber string The phone number of the account holder
accountHolderEmail string The email address of the account holder
binInformation object Detailed Bank Identification Number information (see BinResponse schema). Includes card type, brand name, issuer details, and surcharge eligibility
isDeleted boolean Indicates whether the payment method has been soft-deleted
deletedDate string (date-time) The date and time when the payment method was flagged as deleted (null if not deleted)
customerData object Key-value pairs containing additional custom customer data
isDefaultAccount boolean Indicates whether this payment method is the default payment method for the payor
sponsorKey string The sponsor key associated with this payment method (max 8 characters)
allowTransactionalEmails boolean Indicates whether transactional emails are allowed for this payor

BIN Information Object Fields

The binInformation field contains detailed information about the credit card (when applicable):

Field Type Description
binId string The URL-safe Base64 encoded BIN ID (128-bit GUID)
cardType string The card type: Unknown, Credit, Debit, Prepaid, or Charge
brandName string The card brand name (e.g., "Visa", "Mastercard")
fundingSource string The funding source: Unknown, Credit, Debit, Prepaid, or Charge
bin string The Bank Identification Number (first 6-8 digits of the card)
issuerInformation object Information about the card issuing bank (name, country, phone number)
surcharge string Whether surcharges are allowed: Unknown, Allowed, or NotAllowed

Example Response

Credit Card Example

{
  "responseStatus": "Accepted",
  "responseMessage": "Saved payment method retrieved successfully",
  "responseCode": "200",
  "responseReason": null,
  "responseResult": "success",
  "legacyResponseCode": "A",
  "correlationId": "abc123-def456-ghi789",
  "customAttributes": null,
  "payorId": "5513027774438108364",
  "savedPaymentMethodId": "5513027774438108365",
  "savedPaymentMethodIdLimitedBitFlag": true,
  "createdDate": "2024-01-15T10:30:00Z",
  "accountType": "VISA",
  "customerAccountId": "CUST-12345",
  "customerAccountType": "Primary",
  "binId": "dGVzdC1iaW4taWQ",
  "maskedAccountNumber": "************1234",
  "lastFour": "1234",
  "cardExpiry": "1225",
  "abaRoutingNumber": null,
  "accountHolderFirstName": "John",
  "accountHolderLastName": "Doe",
  "accountHolderStreetLine1": "123 Main Street",
  "accountHolderStreetLine2": "Apt 4B",
  "accountHolderCity": "Springfield",
  "accountHolderRegion": "IL",
  "accountHolderPostalCode": "62701",
  "accountHolderPhoneNumber": "555-123-4567",
  "accountHolderEmail": "john.doe@example.com",
  "binInformation": {
    "binId": "dGVzdC1iaW4taWQ",
    "cardType": "Credit",
    "brandName": "Visa",
    "fundingSource": "Credit",
    "bin": "45678901",
    "issuerInformation": {
      "name": "Example Bank",
      "country": "US",
      "phoneNumber": "1-800-555-0100"
    },
    "surcharge": "Allowed"
  },
  "isDeleted": false,
  "deletedDate": null,
  "customerData": {
    "preferredPayment": "true",
    "notes": "Primary card for monthly billing"
  },
  "isDefaultAccount": true,
  "sponsorKey": "SPONSOR1",
  "allowTransactionalEmails": true
}

ACH Checking Account Example

{
  "responseStatus": "Accepted",
  "responseMessage": "Saved payment method retrieved successfully",
  "responseCode": "200",
  "responseReason": null,
  "responseResult": "success",
  "legacyResponseCode": "A",
  "correlationId": "xyz789-abc123-def456",
  "customAttributes": null,
  "payorId": "5513027774438108364",
  "savedPaymentMethodId": "5513027774438108366",
  "savedPaymentMethodIdLimitedBitFlag": true,
  "createdDate": "2024-02-01T14:20:00Z",
  "accountType": "ECHK",
  "customerAccountId": "CUST-12345",
  "customerAccountType": "Backup",
  "binId": null,
  "maskedAccountNumber": "******7890",
  "lastFour": "7890",
  "cardExpiry": null,
  "abaRoutingNumber": "123456789",
  "accountHolderFirstName": "John",
  "accountHolderLastName": "Doe",
  "accountHolderStreetLine1": "123 Main Street",
  "accountHolderStreetLine2": "Apt 4B",
  "accountHolderCity": "Springfield",
  "accountHolderRegion": "IL",
  "accountHolderPostalCode": "62701",
  "accountHolderPhoneNumber": "555-123-4567",
  "accountHolderEmail": "john.doe@example.com",
  "binInformation": null,
  "isDeleted": false,
  "deletedDate": null,
  "customerData": {
    "preferredPayment": "false",
    "notes": "Backup payment method"
  },
  "isDefaultAccount": false,
  "sponsorKey": null,
  "allowTransactionalEmails": true
}

HTTP Status Codes

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

Understanding Account Types

The accountType field indicates the payment method type:

  • Credit Cards: VISA, MC (Mastercard), DISC (Discover), AMEX (American Express), JCB
  • ACH Accounts:
    • ECHK - Electronic checking account
    • SAV - Savings account

Security and Privacy Notes

Important Security Information:
  • Full account numbers (PAN - Primary Account Number) are never returned by this endpoint
  • Only masked account numbers are provided, showing the last 4 digits
  • For credit cards, CVV/CVV2 data is never stored or returned
  • The binId allows you to look up card issuer information without exposing sensitive account data
  • All sensitive data in transit should use HTTPS encryption

Additional Notes

  • The merchantId must be exactly 11 digits. Requests with invalid formats will return a 400 Bad Request error.
  • The isDefaultAccount flag indicates which payment method is used by default for transactions when no specific payment method is specified.
  • The isDeleted flag indicates soft-deleted records. Deleted payment methods may still be retrievable but cannot be used for new transactions.
  • For credit card accounts, the binInformation object provides valuable details about the card issuer, card type (credit/debit), and surcharge eligibility.
  • For ACH accounts, the abaRoutingNumber identifies the financial institution, while credit card accounts will have this field as null.
  • The correlationId is useful for troubleshooting and should be provided when contacting support.
  • Custom attributes allow you to store additional metadata specific to your integration needs.
  • The sponsorKey is an optional identifier (maximum 8 characters) that can be used to associate the payment method with a sponsor or program.
  • If allowTransactionalEmails is true and an email address is present, the payor may receive transactional notifications related to payments.

Use Cases

  • Display Payment Methods: Show customers their saved payment methods with masked account numbers in your application UI
  • Verify Payment Method Details: Confirm account holder information before processing a transaction
  • Payment Method Selection: Allow customers to choose between multiple saved payment methods
  • Compliance Verification: Check card type and issuer information for surcharge compliance
  • Audit and Logging: Track which payment methods are used for specific transactions