Billing Address Formatting & Validation

Every virtual card billing address is validated and standardized before it is saved. Fluz uses Smarty to check each address against USPS data (CASS / Delivery Point Validation) and normalize it to USPS standards.

If the address you submit cannot be matched to a real, deliverable US address, the request is rejected with error code VC-0025 and no address is saved. Retrying with the same values will fail again — the address itself has to change.

Validation happens whenever a billing address is submitted, including Add Virtual Card Address, Create Virtual Card, and card issuance for authorized users.

How validation works

When you submit a billing address, Smarty:

1. Matches the address against USPS and proprietary address data.
2. Standardizes it — corrects abbreviations, applies USPS formatting, and fills in the ZIP+4.
3. Confirms deliverability — verifies the address is a real, active USPS delivery point.

Only an address that resolves to a confirmed delivery point is accepted. On success, the saved values are normalized (city, state, and postal code are stored in uppercase, and the country is stored as its full name).

Address fields

These are the fields on billingAddress. See Add Virtual Card Address for the full mutation.

Formatting rules

Follow these rules to pass validation on the first try:

1. Use a real, deliverable address. The building number must actually exist on the named street. A street that exists is not enough — 500 Main St fails if the highest number on Main St is 480.
2. Keep city, state, and ZIP consistent. The ZIP code must be the one USPS assigns to that city and state. A mismatched ZIP is the single most common cause of VC-0025 (see the examples below).
3. Use USPS abbreviations. Standard street suffixes (St, Ave, Blvd, Dr, Ln, Rd, Ct, Pkwy) and directionals (N, S, E, W, NE, NW, SE, SW) match most reliably. Smarty will standardize your input, but clean input improves match rates.
4. Put unit / apartment / suite in streetAddressLine2. Do not append it to line 1 in a way that breaks parsing. If USPS requires a secondary unit for a building and none is provided, the address can fail to validate.
5. US addresses only. Set country to United States. Non-US addresses are rejected.
6. No PO boxes. The card issuer does not accept PO box addresses, even if USPS considers them deliverable.
7. Send a 5-digit ZIP. ZIP+4 is not required on input; Smarty adds it during standardization.

Why an address gets rejected (VC-0025)

An address fails validation when Smarty cannot confirm it as a deliverable US delivery point. The most common reasons:

Worked examples

Example 1 — City / ZIP mismatch

2581 Oakwood Avenue, New York, NY 10605

Rejected (VC-0025). ZIP code 10605 belongs to White Plains, NY (Westchester County), not New York City — so the city and ZIP do not match. On top of that, 2581 Oakwood Avenue is not a confirmed delivery point in that ZIP. Smarty returns no valid match, so the address is not saved.

How to fix: submit the ZIP that USPS assigns to the city (or the city that matches the ZIP), and a building number that actually exists on the street.

Example 2 — Invalid building number

896 S State St, Dover, DE 19904

Rejected (VC-0025). S State St exists in Dover, DE, but 896 is not a confirmed USPS delivery point for that street and ZIP. Because the specific building number cannot be validated, Smarty returns no deliverable match.

How to fix: confirm the exact building number and the ZIP that covers that block of the street.

A valid submission

A clean, deliverable address is accepted and standardized on save:

mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) {
  addVirtualCardAddress(input: $input) {
    userAddressId
    streetAddressLine1
    streetAddressLine2
    country
    city
    state
    postalCode
  }
}

{
  "input": {
    "billingAddress": {
      "streetAddressLine1": "1600 Amphitheatre Pkwy",
      "streetAddressLine2": "",
      "country": "United States",
      "city": "Mountain View",
      "state": "CA",
      "postalCode": "94043"
    }
  }
}

Response (values normalized on save):

{
  "data": {
    "addVirtualCardAddress": {
      "userAddressId": "1f6b2c3d-4e5f-4a67-9a10-2b3c4d5e6f70",
      "streetAddressLine1": "1600 Amphitheatre Pkwy",
      "streetAddressLine2": null,
      "country": "United States",
      "city": "MOUNTAIN VIEW",
      "state": "CA",
      "postalCode": "94043"
    }
  }
}

Handling VC-0025 in your integration

• Collect the address in structured fields (streetAddressLine1, streetAddressLine2, city, state, postalCode) rather than a single free-text field. This makes it easy to prompt for the specific part that needs fixing.
• Do not blind-retry. The same address will keep returning VC-0025. Surface the error to the end user and ask them to correct the address.
• Validate before you submit (optional). If you collect addresses in your own UI, running an address autocomplete or verification step on your side reduces failed round-trips.
• The address is not saved on failure, so there is nothing to clean up before retrying with corrected values.

Error reference

See Virtual Card Error Codes for the full list.

Want to learn more? Contact us at [email protected]. Speak with our experts for more info or to request a demo.