Skip to main content

​
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:

​
Address Field Details

​
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 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

​
Canada

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

​
Australia

​
Using Stored Addresses (AddressId)

If you’ve previously stored an address in Revolv3, you can reference it by AddressId:
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