Address Verification
Address verification confirms that the billing address provided with a payment method matches the address on record for the account holder. frameOS runs this check automatically when initiating transactions, helping prevent fraud and reducing the risk of payment disputes.
Address verification works differently depending on the payment method type — cards use an AVS check against the card network, while bank accounts are verified by comparing the billing address against the account holder's KYC-verified address.
How it works
Card address verification (AVS)
For card payments, frameOS uses the Address Verification System (AVS) to confirm that the billing address on the payment method matches what the card issuer has on file. This check is performed by running a $1 authorization against the card — the charge is immediately canceled, so the account holder is never billed. The card network returns a result indicating whether the address matched or not.
If the payment method already has an AVS result on record from a previous verification, frameOS uses that result directly without running a new authorization.
A billing address must be present on the payment method before address verification can run. If no billing address is provided, the verification will fail immediately.
Bank account address verification (ACH)
For bank account payments, frameOS verifies the billing address by comparing it against the address collected and verified during KYC. This means KYC must have passed for the account before ACH address verification can run.
The billing address on the payment method must match the individual's KYC-verified address for verification to pass.
ACH address verification requires a completed KYC verification for the account. If KYC has not passed, the address verification will fail with a kyc_required error.
Verification results
Card (AVS)
| Result | Description |
|---|---|
| Pass | Address matched the card issuer's records |
| Fail | Address did not match — transaction will be blocked |
Bank account (ACH)
| Result | Description |
|---|---|
| Pass | Billing address matches the KYC-verified address |
kyc_required | KYC must pass before ACH address verification can run |
address_mismatch | Billing address does not match the KYC-verified address |
individual_required | No individual profile found on the account |
Create an account with address verification
Add address_verification to the capabilities array when creating the account. For ACH address verification, also include kyc — KYC must pass before bank account addresses can be verified.
Parameters
Must be individual. Address verification is only supported for individual accounts.
Include address_verification to enable address verification. Add kyc if you intend to accept bank account payments — KYC is required for ACH address verification.
The account holder's email address.
The account holder's first name.
The account holder's last name.
Object containing number and country_code for the account holder's phone.
curl --request POST \
--url https://api.framepayments.com/v1/accounts \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"type": "individual",
"capabilities": ["address_verification", "kyc"],
"profile": {
"individual": {
"email": "marcia@example.com",
"name": {
"first_name": "Marcia",
"last_name": "Longo"
},
"phone": {
"number": "3107484186",
"country_code": "1"
}
}
}
}'
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"object": "account",
"type": "individual",
"status": "pending",
"external_id": null,
"capabilities": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
"object": "capability",
"name": "address_verification",
"status": "pending",
"disabled_reason": null,
"currently_due": [],
"disabled": null
},
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
"object": "capability",
"name": "kyc",
"status": "pending",
"disabled_reason": null,
"currently_due": [],
"disabled": null
}
],
"profile": {
"individual": {
"email": "marcia@example.com",
"ssn_last_four": null,
"name": {
"first_name": "Marcia",
"middle_name": null,
"last_name": "Longo",
"suffix": null
},
"phone": {
"number": "3107484186",
"country_code": "1"
},
"birthdate": null,
"address": null
}
},
"terms_of_service": null,
"metadata": {},
"livemode": false,
"created": 1721010605
}
Complete onboarding
Once the account is created, create an onboarding session to collect the account holder's address and any other required information. For ACH address verification, the address collected during KYC onboarding will be used as the reference for all future bank account billing address checks.
curl --request POST \
--url https://api.framepayments.com/v1/onboarding_sessions \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"account_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"return_url": "https://example.com/onboarding/complete"
}'
After onboarding, address verification runs automatically when a transaction is initiated. No additional API calls are required — frameOS performs the check in the background before the payment is processed.