Skip to main content

Update a Payment Instrument

Overview​

Update metadata, billing address (card only), status (enable/disable), Account Updater settings, Network Token settings, or trigger bank account validation. This endpoint allows you to modify Payment Instrument details and settings.

Resource Access​

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

Arguments​

ParameterTypeRequiredDescription
payment_instrument_idstringYesThe unique ID of the Payment Instrument to update
enabledbooleanNoEnable or disable the Payment Instrument
namestringNoUpdate the name on the card or bank account
tagsobjectNoUpdate custom metadata key-value pairs
addressobjectNoUpdate the billing address (Payment Card only)
account_updater_enabledbooleanNoEnable or disable Account Updater (Payment Card only)
network_token_enabledbooleanNoEnable or disable Network Tokens (Payment Card only)
attempt_bank_account_validation_checkbooleanNoTrigger bank account validation (Bank Account only)

Example Request (Disable Payment Instrument)​

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": false
  }'

Example Request (Update Card Address and Enable Features)​

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "address": {
      "line1": "456 Oak Avenue",
      "city": "Los Angeles",
      "region": "CA",
      "postal_code": "90001",
      "country": "USA"
    },
    "account_updater_enabled": true,
    "network_token_enabled": true,
    "tags": {
      "customer_type": "premium",
      "loyalty_tier": "gold"
    }
  }'

Example Response​

{
  "id": "PIpaymentCardExample123",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-09-20T14:45:30Z",
  "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": true,
  "address": {
    "line1": "456 Oak Avenue",
    "city": "Los Angeles",
    "region": "CA",
    "postal_code": "90001",
    "country": "USA"
  },
  "tags": {
    "customer_type": "premium",
    "loyalty_tier": "gold"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123"
    }
  }
}

Example Request (Bank Account Validation)​

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payment_instruments/PIbankAccountExample456' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "attempt_bank_account_validation_check": true
  }'

Additional Information​

  • Disabling Payment Instruments: Setting enabled to false prevents the Payment Instrument from being used in new transactions. Existing authorizations and transfers are not affected
  • Billing Address Updates: Only available for Payment Cards. Updates to the address may affect future AVS (Address Verification System) checks
  • Account Updater:
    • When enabled, automatically updates card details (number, expiration date) when issuers provide updates
    • Reduces declined transactions due to expired or replaced cards
    • Updates are tracked in the instrument_history endpoint
    • Additional fees may apply
  • Network Tokenization:
    • Replaces card details with network-specific tokens for enhanced security
    • Reduces risk of data breaches
    • May improve authorization rates
    • Supported by major card networks (Visa, Mastercard, etc.)
  • Bank Account Validation:
    • Set attempt_bank_account_validation_check to true to trigger validation
    • Validates routing number format and account number format
    • May perform micro-deposit verification (small deposits sent to the account)
    • Result is reflected in the bank_account_validation_check field (VALID, INVALID, NOT_ATTEMPTED)
  • Tags: Custom metadata can be used for organizing and filtering Payment Instruments
  • Immutable Fields: You cannot update the card number, account number, expiration date, or other core identifying fields. Create a new Payment Instrument instead
  • Immediate Effect: Most updates take effect immediately, though Account Updater and Network Token changes may take time to propagate