Pay
Verification
Card AVS (Address Verification)

Card AVS (Address Verification)

Address Verification Service (AVS) compares the billing address provided with a card against the address on file with the cardholder's issuing bank. AVS runs in two situations:

  • When a card payment method is added directly via the /payment_methods endpoint
  • When a card is used to create a transaction via the /transactions endpoint (whether the card is provided inline or already saved as a payment method)

In both cases the result is returned as an avs attribute on the response, regardless of whether the request is approved or declined. A successful match helps confirm the cardholder's identity and reduce fraud risk, while a partial or failed match can indicate a miskeyed address or potentially suspicious activity.

See the table below for a list of all possible avs values:

AVS CodeResultDescription
street_and_zipMatchBoth the billing zip code and street address matched
streetPartialOnly the billing street address matched
zipPartialOnly the billing zip code matched
no_matchNo matchNone of the billing address fields provided were valid
unknownNo resultNo address verification performed

A response of street_and_zip or zip indicates a positive verification — the address information provided matches what the issuing bank has on file, and the request proceeds normally. By default, an avs response value of unknown, no_match, or street will fail:

  • On a transaction, the request returns the transaction with a status_code of invalid_address indicating an invalid_address decline.
  • On a new payment method, the request returns a 400 error with the message Billing address details invalid.

The threshold for what avs values are considered a failure can be adjusted — contact our support team for more information.

Testing AVS responses

To test the various possible avs responses in a sandbox environment, any street address with a street number of 999 will be recognized as an invalid street and any postal code with a value of 99999 will be recognized as an invalid zip. See the billing address combinations below. Each example shows the request body for both creating a card payment method directly and sending the card inline on a transaction.

No verification (unknown)

// Provide card details without billing information
// This will generally result in a decline
{
  "type": "card",
  "card": {
    "card_number": "4111 1111 1111 1111",
    "expiry": "12/25",
    "card_code": "123"
  },
  "account_id": "acct_customer123"
}
// Provide card details without billing information
// This will generally result in a decline
{
  "type": "payment",
  "amount": 1,
  "sender": {
    "method": {
      "type": "card",
      "card": {
        "card_number": "4111 1111 1111 1111",
        "expiry": "12/25",
        "card_code": "123"
      }
    }
  },
  "receiver": {
    "account_id": "acct_receiver123"
  }
}

No match (no_match)

{
  "type": "card",
  "card": {
    "card_number": "4111 1111 1111 1111",
    "expiry": "12/25",
    "card_code": "123"
  },
  "billing_address": {
    // 999 as the street number
    "street_address": "999 Example St",
    // 99999 as the postal code
    "postal_code": "99999"
  },
  "account_id": "acct_customer123"
}
{
  "type": "payment",
  "amount": 1,
  "sender": {
    "method": {
      "type": "card",
      "card": {
        "card_number": "4111 1111 1111 1111",
        "expiry": "12/25",
        "card_code": "123"
      },
      "billing_address": {
        // 999 as the street number
        "street_address": "999 Example St",
        // 99999 as the postal code
        "postal_code": "99999"
      }
    }
  },
  "receiver": {
    "account_id": "acct_receiver123"
  }
}

Partial zip match (zip)

{
  "type": "card",
  "card": {
    "card_number": "4111 1111 1111 1111",
    "expiry": "12/25",
    "card_code": "123"
  },
  "billing_address": {
    // 999 as the street number
    "street_address": "999 Example St",
    // Any value other than 99999 as the postal code
    "postal_code": "11111"
  },
  "account_id": "acct_customer123"
}
{
  "type": "payment",
  "amount": 1,
  "sender": {
    "method": {
      "type": "card",
      "card": {
        "card_number": "4111 1111 1111 1111",
        "expiry": "12/25",
        "card_code": "123"
      },
      "billing_address": {
        // 999 as the street number
        "street_address": "999 Example St",
        // Any value other than 99999 as the postal code
        "postal_code": "11111"
      }
    }
  },
  "receiver": {
    "account_id": "acct_receiver123"
  }
}

Partial street match (street)

{
  "type": "card",
  "card": {
    "card_number": "4111 1111 1111 1111",
    "expiry": "12/25",
    "card_code": "123"
  },
  "billing_address": {
    // Any value other than 999 as the street number
    "street_address": "123 Example St",
    // 99999 as the postal code
    "postal_code": "99999"
  },
  "account_id": "acct_customer123"
}
{
  "type": "payment",
  "amount": 1,
  "sender": {
    "method": {
      "type": "card",
      "card": {
        "card_number": "4111 1111 1111 1111",
        "expiry": "12/25",
        "card_code": "123"
      },
      "billing_address": {
        // Any value other than 999 as the street number
        "street_address": "123 Example St",
        // 99999 as the postal code
        "postal_code": "99999"
      }
    }
  },
  "receiver": {
    "account_id": "acct_receiver123"
  }
}

Full match (street_and_zip)

{
  "type": "card",
  "card": {
    "card_number": "4111 1111 1111 1111",
    "expiry": "12/25",
    "card_code": "123"
  },
  "billing_address": {
    // Any value other than 999 as the street number
    "street_address": "123 Example St",
    // Any value other than 99999 as the postal code
    "postal_code": "11111"
  },
  "account_id": "acct_customer123"
}
{
  "type": "payment",
  "amount": 1,
  "sender": {
    "method": {
      "type": "card",
      "card": {
        "card_number": "4111 1111 1111 1111",
        "expiry": "12/25",
        "card_code": "123"
      },
      "billing_address": {
        // Any value other than 999 as the street number
        "street_address": "123 Example St",
        // Any value other than 99999 as the postal code
        "postal_code": "11111"
      }
    }
  },
  "receiver": {
    "account_id": "acct_receiver123"
  }
}
Bank Account VerificationTest Cards