Address Verification
Address verification confirms that the billing address tied to a payment method matches an authoritative source. It's a transaction-time check, not a one-shot onboarding step: Frame runs the verification automatically when a charge is initiated, using a different mechanism per payment method type, and either lets the charge through or blocks it.
The mechanism splits by rail:
- Cards use AVS (the Address Verification System), the standard card-network check.
- Bank accounts compare the billing address against the account holder's KYC-verified residential address.
Both surface through the same address_verification capability on the account, but the prerequisites are different.
When to use it
Request address_verification when:
- Your platform takes card payments and you want AVS-level fraud signal beyond Frame's defaults.
- You're processing ACH and want to confirm the bank-account owner's billing address is consistent with their verified identity.
- A compliance or dispute-management policy requires explicit address-match evidence on file.
If you're only accepting card payments through hosted checkout and don't have a specific AVS requirement, Frame's built-in fraud signals already factor address consistency in — explicit address_verification is for cases where you want to require the match and reject the transaction otherwise.
How it works — card AVS
When a charge runs against a card payment method:
- Frame submits the billing address on the payment method to the card network as part of authorization.
- The card issuer compares it against the address on file for that cardholder.
- The network returns a match result.
If the payment method already has an AVS result from a prior verification, Frame reuses it instead of re-running the check. If no billing address is on the payment method, verification fails immediately — there's nothing to compare.
For payment methods that haven't been verified yet, Frame runs a $1 authorization that's immediately reversed — the cardholder is never billed, but the network returns the AVS signal. This shows up as a transient $1 hold; merchants who care about that signal-to-noise ratio should communicate the pattern to customer support.
AVS outcomes for cards:
| Result | Behavior |
|---|---|
| Pass | Address matched. Charge proceeds. |
| Fail | Address did not match. Charge is blocked. |
How it works — bank account address verification
For ACH (bank account payment methods), there's no equivalent of AVS at the bank network level. Frame instead compares the billing address on the payment method against the KYC-verified residential address on the account holder's profile.
This means:
- KYC must have passed for the account before ACH address verification can run.
- The payment method's billing address must match the account holder's
profile.individual.address.
Outcomes for bank accounts:
| Result | Behavior |
|---|---|
| Pass | Billing address matches the KYC-verified address. Charge proceeds. |
kyc_required | KYC hasn't passed yet. Charge is blocked. |
address_mismatch | Billing address doesn't match KYC. Charge is blocked. |
individual_required | The account doesn't have an individual profile to compare against. Charge is blocked. |
ACH address verification depends on KYC. Request both capabilities together (kyc + address_verification) when you intend to accept bank account payments — KYC is what populates the reference address.
What it doesn't do
Address verification is a match check, not a validity check. Frame is not validating:
- That the address physically exists at the postal level (no USPS standardization).
- That the account holder currently lives there.
- That the address is deliverable.
If you need postal validity or deliverability, that's a separate concern — address verification answers "does the billing address match the source of truth," not "is this a real place mail could go."
Capability requirements
| Use case | Required capabilities |
|---|---|
| Card-only payments with AVS | address_verification |
| Bank account payments with address match | address_verification + kyc |
| Both card and bank account payments | address_verification + kyc (covers both rails) |
Address verification activates automatically once the prerequisite data is on file — a payment method with a billing address for cards, or a completed KYC for ACH. There's no separate hosted UX; like geocompliance, it's a background capability that gates transactions.
Gotchas
Symptom: card charges are failing address_verification even though you're sure the billing address is correct. Why: AVS results vary by issuer — some banks return partial matches (zip only, street only) that Frame's threshold treats as a fail. Fix: check the specific AVS code returned by the network; if it's a partial match, consider whether your platform's risk policy can accept it (Frame support can help configure thresholds).
Symptom: ACH charges fail with kyc_required even though the account has been onboarded. Why: the kyc capability didn't fully activate — it's still pending (waiting on a back-channel check) or disabled. ACH address verification reads the active KYC state. Fix: retrieve the account and confirm kyc is active; if it's pending, listen for the capability.activated webhook before retrying.
Symptom: a customer updates their address with you but charges keep failing address_mismatch. Why: updating the address on your platform doesn't automatically update the KYC-verified address on the Frame account. They're separate records. Fix: update the account's profile.individual.address via the API; if the address is substantially different, Frame may put kyc back into pending for re-verification.
Reference
For payment method creation (where the billing address is attached), see POST/v1/payment_methods.