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
binIdallows you to look up card issuer information without exposing sensitive account data - All sensitive data in transit should use HTTPS encryption
Additional Notes
- The
merchantIdmust be exactly 11 digits. Requests with invalid formats will return a 400 Bad Request error. - The
isDefaultAccountflag indicates which payment method is used by default for transactions when no specific payment method is specified. - The
isDeletedflag indicates soft-deleted records. Deleted payment methods may still be retrievable but cannot be used for new transactions. - For credit card accounts, the
binInformationobject provides valuable details about the card issuer, card type (credit/debit), and surcharge eligibility. - For ACH accounts, the
abaRoutingNumberidentifies the financial institution, while credit card accounts will have this field as null. - The
correlationIdis useful for troubleshooting and should be provided when contacting support. - Custom attributes allow you to store additional metadata specific to your integration needs.
- The
sponsorKeyis an optional identifier (maximum 8 characters) that can be used to associate the payment method with a sponsor or program. - If
allowTransactionalEmailsis 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