Skip to main content

Fetch a Payment Instrument

Overview​

Retrieve the details of a previously created Payment Instrument. The Payment Instrument resource represents tokenized payment details (credit card or bank account) associated with an Identity.

Resource Access​

  • User Permissions: All users can access this endpoint
  • Endpoint: GET /payment_instruments/\{payment_instrument_id}

Arguments​

ParameterTypeRequiredDescription
payment_instrument_idstringYesThe unique ID of the Payment Instrument to retrieve

Example Request​

curl -X GET \
  'https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response (Payment Card)​

{
  "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,
  "security_code_verification": "MATCHED",
  "address_verification": "POSTAL_CODE_AND_STREET_MATCH",
  "address": {
    "line1": "123 Main Street",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "tags": {
    "customer_type": "premium"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123"
    },
    "identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDentityExample123"
    },
    "authorizations": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123/authorizations"
    },
    "transfers": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123/transfers"
    }
  }
}

Example Response (Bank Account)​

{
  "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"
    },
    "identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDentityExample123"
    },
    "transfers": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIbankAccountExample456/transfers"
    }
  }
}

Additional Information​

  • Payment Card Fields:
    • brand: Card network (VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, JCB, DINERS_CLUB)
    • 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
    • security_code_verification: CVV verification result (MATCHED, UNMATCHED, UNKNOWN)
    • address_verification: AVS verification result (MATCHED, NO_MATCH, PARTIAL_MATCH, etc.)
  • Bank Account Fields:
    • account_type: CHECKING, SAVINGS, BUSINESS_CHECKING, PERSONAL_CHECKING
    • bank_code: Routing/ABA number (USA) or institution details (CAN)
    • masked_account_number: Account number with most digits masked for security
    • bank_account_validation_check: VALID, INVALID, or NOT_ATTEMPTED
  • Fingerprinting: The fingerprint is a unique hash representing the card/account details, useful for detecting duplicate payment methods
  • Enabled Status: If enabled is false, the Payment Instrument cannot be used for new transactions
  • Security: Full card numbers, CVV codes, and unmasked account numbers are never returned in API responses
  • Related Resources: Use the _links object to navigate to related authorizations and transfers
  • Account Updater: When enabled, card details are automatically updated through the card networks, and history is available via the instrument_history endpoint
  • Network Tokens: When enabled, enhances security by replacing card details with network-specific tokens