List Payment Instruments

Overview

Retrieve a list of Payment Instruments with optional filtering by type and card details. Payment Instruments represent tokenized payment details (credit cards or bank accounts) associated with Identities.

Resource Access

• User Permissions: All users can access this endpoint
• Endpoint: GET /payment_instruments

Arguments

Parameter	Type	Required	Description
limit	integer	No	The maximum number of results to return (default: 30)
type	string	No	Filter by Payment Instrument type (PAYMENT_CARD, BANK_ACCOUNT)
last4	string	No	Filter by the last 4 digits (Payment Card only)
after_cursor	string	No	Return every resource created after the cursor value for pagination

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/payment_instruments?limit=20&type=PAYMENT_CARD' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "_embedded": {
    "payment_instruments": [
      {
        "id": "PIpaymentCardExample123",
        "created_at": "2023-06-15T10:30:00Z",
        "updated_at": "2023-06-15T10:30:00Z",
        "type": "PAYMENT_CARD",
        "identity": "IDentityExample123",
        "enabled": true,
        "fingerprint": "FPR-123456789",
        "currency": "USD",
        "name": "John Doe",
        "brand": "VISA",
        "last_four": "1111",
        "expiration_month": 12,
        "expiration_year": 2025,
        "account_updater_enabled": true,
        "network_token_enabled": false,
        "address": {
          "line1": "123 Main Street",
          "city": "San Francisco",
          "region": "CA",
          "postal_code": "94105",
          "country": "USA"
        },
        "tags": {},
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123"
          }
        }
      },
      {
        "id": "PIbankAccountExample456",
        "created_at": "2023-06-14T09:15:00Z",
        "updated_at": "2023-06-14T09:15:00Z",
        "type": "BANK_ACCOUNT",
        "identity": "IDentityExample123",
        "enabled": true,
        "fingerprint": "FPR-987654321",
        "currency": "USD",
        "name": "Jane Smith",
        "account_type": "CHECKING",
        "bank_code": "021000021",
        "masked_account_number": "XXXXX6789",
        "bank_account_validation_check": "VALID",
        "tags": {},
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIbankAccountExample456"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 2
  }
}

Additional Information

• Filtering by Type: Use the type parameter to retrieve only cards or only bank accounts:
  • type=PAYMENT_CARD: Returns only payment cards
  • type=BANK_ACCOUNT: Returns only bank accounts
• Card Search: Use the last4 parameter to find cards by their last 4 digits (e.g., last4=1111)
• Pagination: Use the after_cursor parameter to paginate through large result sets
• Payment Card Fields:
  • brand: Card network (VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER)
  • last_four: Last 4 digits of the card number
  • expiration_month / expiration_year: Card expiration date
  • account_updater_enabled: Whether automatic card updates are enabled
  • network_token_enabled: Whether network tokenization is enabled
• Bank Account Fields:
  • account_type: CHECKING, SAVINGS, BUSINESS_CHECKING, PERSONAL_CHECKING
  • bank_code: Routing/ABA number
  • masked_account_number: Account number with most digits masked
  • bank_account_validation_check: VALID, INVALID, or NOT_ATTEMPTED
• Enabled Status: The enabled field indicates whether the Payment Instrument can be used for transactions
• Fingerprinting: Each unique card/bank account has a unique fingerprint for duplicate detection
• Security: Sensitive data (full card numbers, CVV, account numbers) is never returned in API responses