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: 
{
  "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

FieldRequiredDescriptionExamples
AddressLine1OptionalStreet address (first line)"381 Forest Ave", "123 Main Street"
AddressLine2OptionalApartment, suite, unit, etc."Suite 100", "Apt 5B"
CityOptionalCity name"Laguna Beach", "New York"
StateOptionalState or province"CA", "NY", "ON" (for Canada)
PostalCodeOptionalZIP code or postal code"92651", "10001", "K1A 0B1" (Canada)
CountryOptionalCountry 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 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

{
  "BillingAddress": {
    "AddressLine1": "49 Featherstone Street",
    "City": "London",
    "PostalCode": "EC1Y 8SY",
    "Country": "GB"
  }
}

​
Canada

{
  "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

{
  "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: 
{
  "BillingAddress": {
    "AddressId": 7551  // Reference to previously stored address
  }
}
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