Additional payment button - address formatting and validation

You must populate addressDetails with the shipping address provided by the buyer if you set checkoutMode to ProcessOrder with productType PayAndShip. Below are details on how Amazon Pay validates the address provided, standardizes input, and handles Latin letters and special or multi-byte characters.


Address validation

Required addressDetails parameters is dependent on region.

 
Parameter Comments
name
Required parameter
addressLine1
Required parameter
addressLine2
Optional parameter
addressLine3
Optional parameter
city
Required parameter
districtOrCounty
Optional parameter
stateOrRegion
Required parameter
postalCode
Required parameter
countryCode
Required parameter
phoneNumber
Required parameter
 
EU address validations apply if countryCode is one of the following values: 'UK' ,'GB' ,'DE' ,'FR' ,'IT' ,'ES' ,'AT' ,'BE' ,'BG' ,'HR' ,'CY' ,'CZ' ,'DK' ,'EE' ,'FI' ,'GR' ,'HU' ,'IE' ,'LV' ,'LT' ,'LU' ,'MT' ,'NL' ,'PL' ,'PT' ,'RO' ,'SK' ,'SI' ,'SE'
 
Parameter Comments
name
Required parameter
addressLine1
Required parameter
addressLine2
Optional parameter
addressLine3
Optional parameter
city
Required parameter
districtOrCounty
Optional parameter
stateOrRegion
Not supported if countryCode is: 'UK', 'GB', 'SG', 'AE', 'MX'
postalCode
Required parameter
countryCode
Required parameter
phoneNumber
Required parameter
 
Parameter Comments
name
Required parameter
addressLine1
Required parameter
addressLine2
Optional parameter
addressLine3
Optional parameter
city
Optional parameter
districtOrCounty
Optional parameter
stateOrRegion
Required parameter
postalCode
Required parameter
countryCode
Required parameter
phoneNumber
Required parameter

Input standardization

Amazon Pay standardizes addressDetails using the following transformations:

  • Leading and trailing whitespace are trimmed from all inputs
  • postalCode and countryCode are uppercased
  • name and addressLine1 are truncated if they exceed max length (50 and 60 characters respectively)

Additionally, the following transformations are applied at the region level:

  • US
    • A dash is inserted into 9-digit US postalCode (for example, 98104 - 3442)
  • JP
    • postalCode is converted to single-byte format if multi-byte input exceeds 6 characters
    • addressLine1, addressLine2, addressLine3 are converted to single-byte format if multi-byte input exceeds 20 characters
    • name is converted to single-byte format if multi-byte input exceeds 16 characters
    • phoneNumber is always converted to single-byte format for multi-byte input

Latin letters and special or multi-byte characters

Latin letters and special characters:

Latin and special characters must be URL encoded (UTF-8) for all addressDetails fields except for countryCode.

For example, to set City as "東京" (Tokyo) you should use "%E6%9D%B1%E4%BA%AC".

Multi-byte characters:

Multi-byte characters must be URL encoded (UTF-8) for all addressDetails fields.

For example, to set Name as "012345678" you should use "%EF%BC%90%EF%BC%91%EF%BC%92%EF%BC%93%EF%BC%94%EF%BC%95%EF%BC%96%EF%BC%97%EF%BC%98".

Note: In JP, postalCode will be automatically converted to single byte format if the value provided exceeds 6 characters.