> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revolv3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Billing Addresses

> Learn how to format and validate billing addresses for payment processing. Understand address requirements, validation rules, and international address formats.

## Why Billing Addresses Matter

A **billing address** is the address associated with the customer's payment method (credit card or bank account). It's used for:

* **Fraud prevention**: Banks verify that the address matches what they have on file
* **Address Verification System (AVS)**: Card networks check if the address matches
* **Compliance**: Required for many payment types
* **Customer identification**: Helps verify the customer is authorized to use the payment method

**Why it's important**: Providing the correct billing address can improve payment success rates and reduce fraud. Incorrect addresses may cause payments to be declined.

## Sample Billing Address

Here's a complete example of a valid billing address:

```json theme={null}
{
  "PaymentMethod": {
    "BillingAddress": {
      "AddressLine1": "381 Forest Ave",
      "AddressLine2": null,
      "City": "Laguna Beach",
      "State": "CA",
      "PostalCode": "92651",
      "Country": "USA"
    },
    "BillingFirstName": "John",
    "BillingLastName": "Doe",
    "CreditCard": {
      "PaymentAccountNumber": "4111111111111111",
      "ExpirationDate": "0330",
      "SecurityCode": "737"
    }
  }
}
```

## Address Field Details

| Field          | Required | Description                  | Examples                                   |
| -------------- | -------- | ---------------------------- | ------------------------------------------ |
| `AddressLine1` | Optional | Street address (first line)  | `"381 Forest Ave"`, `"123 Main Street"`    |
| `AddressLine2` | Optional | Apartment, suite, unit, etc. | `"Suite 100"`, `"Apt 5B"`                  |
| `City`         | Optional | City name                    | `"Laguna Beach"`, `"New York"`             |
| `State`        | Optional | State or province            | `"CA"`, `"NY"`, `"ON"` (for Canada)        |
| `PostalCode`   | Optional | ZIP code or postal code      | `"92651"`, `"10001"`, `"K1A 0B1"` (Canada) |
| `Country`      | Optional | Country code (ISO format)    | `"USA"`, `"CA"`, `"GB"`                    |

## Address Formatting Rules

### Country Codes

Use **ISO Alpha-2 or Alpha-3** country code abbreviations:

* `"USA"` or `"US"` for United States
* `"CA"` or `"CAN"` for Canada
* `"GB"` or `"GBR"` for United Kingdom
* See [Country Codes Reference](https://www.iban.com/country-codes) for complete list

### United States Postal Codes

* **Format**: Exactly 5 digits
* **Examples**: `"92651"`, `"10001"`, `"90210"`
* **Not valid**: `"92651-1234"` (extended ZIP), `"9265"` (too short)

### International Postal Codes

* **Format**: Up to 10 characters
* **Examples**:
  * Canada: `"K1A 0B1"` (with space) or `"K1A0B1"` (without)
  * UK: `"EC1Y 8SY"` or `"SW1A 1AA"`
  * Australia: `"2000"` or `"2000-3000"`

### State/Province Requirements

* **United States**: State is typically required (2-letter code like `"CA"`, `"NY"`)
* **Canada**: Province is typically required (2-letter code like `"ON"`, `"BC"`)
* **Many other countries**: State/province is **not required** (e.g., UK, Australia, most of Europe)

## International Address Examples

### United Kingdom

```json theme={null}
{
  "BillingAddress": {
    "AddressLine1": "49 Featherstone Street",
    "City": "London",
    "PostalCode": "EC1Y 8SY",
    "Country": "GB"
  }
}
```

### Canada

```json theme={null}
{
  "BillingAddress": {
    "AddressLine1": "100 Main Street",
    "City": "Toronto",
    "State": "ON",
    "PostalCode": "M5H 2N2",
    "Country": "CA"
  }
}
```

**Note**: Canadian addresses use province codes (ON, BC, QC, etc.) and postal codes can include spaces.

### Australia

```json theme={null}
{
  "BillingAddress": {
    "AddressLine1": "100 George Street",
    "City": "Sydney",
    "State": "NSW",
    "PostalCode": "2000",
    "Country": "AU"
  }
}
```

## Using Stored Addresses (AddressId)

If you've previously stored an address in Revolv3, you can reference it by `AddressId`:

```json theme={null}
{
  "BillingAddress": {
    "AddressId": 7551  // Reference to previously stored address
  }
}
```

In this example, `AddressId` refers to an address that was previously stored in Revolv3 and can be reused without resending the full address fields.

This is useful when:

* The customer has used this address before
* You want to avoid sending address data repeatedly
* You're reusing addresses for multiple transactions

## Best Practices

1. **Collect complete addresses**: Get all fields when possible for better fraud prevention
2. **Validate before sending**: Check address format in your application before API calls
3. **Handle international addresses**: Be aware that different countries have different requirements
4. **Store addresses**: If customers use the same address multiple times, store it and reuse
5. **Match card address**: The billing address should match the address on file with the bank

## Common Questions

**Q: Do I need all address fields?** A: No, but providing more fields improves fraud prevention.

**Q: What if the customer doesn't have a state/province?** A: For countries where state isn't required (like UK), you can omit it. For US/Canada, it's typically required.

**Q: Can I use extended ZIP codes (ZIP+4)?** A: For US addresses, use only the 5-digit ZIP code. Extended ZIPs (like "92651-1234") are not supported.

**Q: What format should postal codes be in?** A: Use the format common in that country. Canadian postal codes can include spaces; US ZIPs should be 5 digits only.

**Q: Do I need to include AddressLine2?** A: No, it's optional. Only include it if the customer has an apartment, suite, or unit number.

## Next Steps

* [**Make a Payment**](/docs/getting-started/make-a-payment) — See how billing addresses are used in payment requests
* [**Payment Methods Guide**](/docs/core-concepts/paymentmethod/paymentmethod-guide) — Learn about storing payment methods with addresses
* [**Create a Subscription**](/docs/core-concepts/subscription/create-subscription) — See how addresses work with subscriptions

***