Verify Payment Instrument

Overview

Perform a real-time verification of a Payment Instrument, including CVV/AVS checks for payment cards or Push-to-Card eligibility verification. This endpoint helps validate payment methods before processing transactions.

Resource Access

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

Arguments

Parameter	Type	Required	Description
payment_instrument_id	string	Yes	The unique ID of the Payment Instrument to verify
merchant	string	No	The Merchant ID performing the verification
security_code	string	No	CVV/CVC code for verification (Payment Card only)
verify_payment_card	boolean	No	Set to true to perform CVV/AVS verification (Payment Card only)
address	object	No	Address details for AVS verification (Payment Card only)
processor	string	No	Processor to verify Push-to-Card eligibility

Example Request (CVV/AVS Verification)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": "MUmerchantExample123",
    "verify_payment_card": true,
    "security_code": "123",
    "address": {
      "line1": "123 Main Street",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94105",
      "country": "USA"
    }
  }'

Example Response (Successful Verification)

{
  "id": "PIpaymentCardExample123",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-15T11:00: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,
  "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": {},
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIpaymentCardExample123"
    }
  }
}

Example Request (Push-to-Card Verification)

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

Additional Information

• CVV Verification:
  • Validates that the CVV/CVC code matches the card on file with the issuing bank
  • Does not create an authorization or charge
  • Result is reflected in security_code_verification field
• Security Code Verification Results:
  • MATCHED: CVV code matches
  • UNMATCHED: CVV code does not match
  • UNKNOWN: Issuer did not provide verification result
• AVS (Address Verification System):
  • Validates the billing address against the address on file with the card issuer
  • Checks both street address and postal code
  • Result is reflected in address_verification field
• Address Verification Results:
  • MATCHED: Both street address and postal code match
  • POSTAL_CODE_AND_STREET_MATCH: Both components match (verbose result)
  • PARTIAL_MATCH: Either street or postal code matches
  • NO_MATCH: Neither street nor postal code match
  • UNKNOWN: Issuer did not provide verification result
• Push-to-Card Verification:
  • Validates that the card can receive disbursements (payouts)
  • Required before using the card for Push-to-Card transfers
  • Checks card eligibility with the processor and card network
  • Some cards (e.g., prepaid cards, debit cards) may support Push-to-Card while credit cards typically do not
• Zero-Dollar Authorization: CVV/AVS verification typically performs a $0 authorization that is immediately voided
• Merchant ID: A valid Merchant ID is required to perform verification
• Processor Support: Not all processors support all verification types. Check with your processor for specific capabilities
• No Charge: Verification does not result in any charge to the cardholder
• Use Cases:
  • Validate card details before saving for future use
  • Confirm CVV code during checkout
  • Verify billing address accuracy
  • Check Push-to-Card eligibility before initiating payouts