Skip to main content

List Instrument History Entries

Overview​

Retrieve a list of history entries for a Payment Instrument, detailing updates like those from Account Updater. This endpoint tracks changes to payment card details over time, such as updated card numbers or expiration dates.

Resource Access​

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

Arguments​

ParameterTypeRequiredDescription
payment_instrument_idstringYesThe unique ID of the Payment Instrument
limitintegerNoThe maximum number of results to return (default: 10)
after_cursorstringNoReturn every resource created after the cursor value for pagination

Example Request​

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

Example Response​

{
  "_embedded": {
    "instrument_history_entries": [
      {
        "id": "IHhistoryEntry789",
        "created_at": "2023-09-15T08:30:00Z",
        "type": "NUMBER_AND_EXPIRATION_UPDATED",
        "old_instrument_details": {
          "last_four": "1111",
          "expiration_month": 12,
          "expiration_year": 2023,
          "brand": "VISA"
        },
        "new_instrument_details": {
          "last_four": "2222",
          "expiration_month": 12,
          "expiration_year": 2026,
          "brand": "VISA"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/instrument_history_entries/IHhistoryEntry789"
          },
          "payment_instrument": {
            "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123"
          }
        }
      },
      {
        "id": "IHhistoryEntry456",
        "created_at": "2023-03-20T14:15:00Z",
        "type": "NUMBER_AND_EXPIRATION_UPDATED",
        "old_instrument_details": {
          "last_four": "9999",
          "expiration_month": 6,
          "expiration_year": 2022,
          "brand": "VISA"
        },
        "new_instrument_details": {
          "last_four": "1111",
          "expiration_month": 12,
          "expiration_year": 2023,
          "brand": "VISA"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/instrument_history_entries/IHhistoryEntry456"
          },
          "payment_instrument": {
            "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 2
  }
}

Additional Information​

  • Account Updater Service: Instrument history entries are primarily created by the Account Updater service, which automatically updates card details when:
    • Cards are replaced due to loss, theft, or fraud
    • Cards are reissued with new expiration dates
    • Card numbers change during bank mergers or rebranding
  • Update Types:
    • NUMBER_AND_EXPIRATION_UPDATED: Both card number and expiration date changed
    • Additional update types may be available depending on the card network
  • History Tracking: Each entry records:
    • old_instrument_details: Card details before the update (last 4 digits, expiration, brand)
    • new_instrument_details: Card details after the update
    • created_at: When the update was applied
  • Automatic Updates: When Account Updater is enabled on a Payment Instrument:
    • The system periodically checks with card networks for updated card information
    • Updates are applied automatically without requiring action from you or the cardholder
    • History entries are created to track each change
  • Continuity: The Payment Instrument ID remains the same after updates, ensuring:
    • Recurring billing continues without interruption
    • Saved cards work seamlessly after replacement
    • No need to re-collect card information from customers
  • Notification: You can configure webhooks to receive notifications when instrument updates occur
  • Best Practices:
    • Review history regularly to understand card update patterns
    • Monitor for unusual update frequency (may indicate fraud)
    • Use history data for customer support inquiries
    • Track update success rates to measure Account Updater effectiveness
  • Pagination: Use the after_cursor parameter to paginate through large history sets
  • Payment Cards Only: Instrument history is only available for Payment Cards, not bank accounts