Initiating Merchant Registration for Unhosted Service Providers

Note: We recommend that you initiate the unhosted registration workflow in a popup or new window.

The registration URL where you will send merchants to initiate registration with Amazon Pay is:

Payment Region URL
European payment region https://payments-eu.amazon.com/register
North American payment region https://payments.amazon.com/register

The registration flow must be initiated via an HTTPS POST request to supply the registration experience with some pre-filled information that you send through the POST fields, as shown in the following table:

Parameter Description and examples
spId
(required)
Your ID, which is provided to you by your account representative (AR). The spId is used to identify the Ecommerce provider that the merchant’s account will be associated with.

Please work with your AR to obtain the spId for each of the regions in which you integrate Amazon Pay.

Example: AXXXXXXXXX
onboardingVersion
(required for key exchange)
The onboarding flow's version to use. For checkout Version 1, omit this parameter entirely, or set its value to 1.
For Checkout Version 2, this parameter is required, and its value should be set to 2
publicKey
(required for key exchange)
The public key generated by the Ecommerce provider or plugin, which is used to encrypt the contents of the key exchange package when supported by the registration workflow. This is an ephemeral 2048 bit RSA public key.

Please see the keyShareURL functionality section for additional information on using this parameter.
keyShareURL
(optional)
The HTTPS endpoint where the encrypted key package will be posted when the registration workflow supports it.

Example: https://www.mystore.com/return

Note: Currently, automated key sharing is applicable only in the North American payment region. Unhosted Ecommerce providers in the European payment region currently do not need to send keyShareURL and publicKey. Please see the keyShareURL functionality section for additional information on using this parameter.
locale
(optional)
The value of locale is used to determine the language that Amazon Pay registration pages should be displayed in.

Allowed values (for European payment region): en_GB, de_DE, fr_FR, it_IT, es_ES

Allowed values (for UK payment region): en_GB

Allowed values (for North American payment region): en_US

Note: Invalid or unsupported values will be ignored.
merchantCountry
(optional, not yet processed)
The country of establishment (COE). The COE is the country where a merchant has established their business legally, and is associated with the merchant legal entity.
merchantLoginDomains[ ]
(optional)
The value of merchantLoginDomains is used to populate the secure checkout URLs (or the URL of pages on which a button appears) for the Login with Amazon application.

Multiple valid domains can be passed. (Please see the example in the code sample that follows).

A valid login domain is a combination of protocol, domain name, and port, it must use the HTTPS protocol, and it cannot be longer than 512 characters. If you are using a standard port (port 443) you only need to include the protocol and domain name (for example: https://www.example.com).

The values of this parameter are used to populate Allowed Javascript Origins on the Login with Amazon application.

Notes:
  • During buyer checkout, client validation will fail if merchantLoginDomains references a page outside of the root domain and port number.
  • Do not include any text beyond the domain in the URL. For example, do not specify a URL similar to https://www.example.com/cart. Instead, specify a URL similar to https://www.example.com.
spSoftwareVersion
(Optional)
The version of the Ecommerce platform software.
spAmazonPluginVersion
(Optional)
The version of the Amazon Pay plugin or extension.
ld
(Optional)
If Amazon Pay shares a Lead Code ( ld ), it must be sent via this parameter. For example, if one is appended as a redirect URL query parameter you must use that value. The ld code is generated dynamically based on the source of registration and passed on to solution providers. If no ld code is provided, you can disregard this requirement.
merchantLoginRedirectURLs[ ]
(optional)
The value of merchantLoginRedirectURLs includes the protocol, domain, path, and query string. The protocol used in the URL must be HTTPS. Multiple redirect URLs can be passed. (Please see the FAQ section for more information).

The values of this parameter are used to populate Allowed Return URLs on the Login with Amazon application.

Note: Client validation will fail if the HTTPS protocol is not used, or if the URL is longer than 512 characters.
merchantPrivacyNoticeURL
(optional)
merchantPrivacyNoticeURL is the URL address of the merchant’s privacy policy. A link to the merchant’s privacy policy is displayed on the consent screen the first time that a customer signs in to the merchant’s website. The URL can use either the HTTP or HTTPS protocol.

Note: Client validation will fail if the URL is longer than 512 characters.
merchantStoreDescription
(optional)
The value of merchantStoreDescription is used to fill the Application/Business Description on the Login with Amazon application.

Example: Bob’s Online Store

Note: Client validation will fail if this parameter is longer than 2048 characters.
merchantSandboxIPNURL
(optional, not yet processed)
The value of merchantSandboxIPNURL will be used to set the Merchant URL IPN for Sandbox on the account.

This Sandbox URL can use either the HTTP or HTTPS protocol, but can be no longer than 150 characters.

Example: https://www.example.com/merchantSandboxIPN
spSandboxIPNURL
(optional, not yet processed)
The value of spSandboxIPNURL will be used to set the Ecommerce Provider URL IPN for Sandbox on the account.

This Sandbox URL can use either the HTTP or HTTPS protocol, but can be no longer than 150 characters.

Example: https://www.ecommerceprovider.com/spSandboxIPN
merchantProductionIPNURL
(optional, not yet processed)
The value of merchantProductionIPNURL will be used to set the Merchant URL IPN for Production on the account.

This Production URL must use the HTTPS protocol, and cannot be longer than 150 characters.

Example: https://www.example.com/merchantProductionIPN
spProductionIPNURL
(optional, not yet processed)
The value of spProductionIPNURL will be used to set the Ecommerce Provider URL IPN for Production on the account.

This Production URL must use the HTTPS protocol, and cannot be longer than 150 characters.

Example: https://www.ecommerceprovider.com/spProductionIPN
source
(optional)
The value of source is used to identify the origin of the registration request.

The values supported are:
  • SPPL – used when coming from the configuration section of the platform admin panel
  • SPPW – used when coming from a non-Amazon website
  • SPPD – used when coming from platform documentation
  • SPEM – used when coming from platform-sent emails
  • SPYT – used when coming from YouTube
  • SPOT – any other source

The following sample shows the call, which will initiate the redirect to the registration flow.


<form method="POST" action="https://payments.amazon.com/register">
	<input type="hidden" value="en_US" name="locale">
	<input type="hidden" value="AXXXXXXXYZ" name="spId">
	<input type="hidden" value="https://www.url1.com"
	name="merchantLoginDomains[]">
	<input type="hidden" value="https://www.url2.com"
	name="merchantLoginDomains[]">
	<input type="hidden" value="https://www.url3.com"
	name="merchantLoginDomains[]">
	<input type="hidden" value=" https://checkout.example.com/1/callbackname"
	name="merchantLoginRedirectURLs[]">
	<input type="hidden" value=" https://www.example.com/login.php?parameter=1"
	name="merchantLoginRedirectURLs[]"/>
	<input type="hidden" value="https://www.url3.com/privacy"
	name="merchantPrivacyNoticeURL">
	<input type="hidden" value="Store Description"
	name="merchantStoreDescription">
	<input type="hidden" value="SPPL" name="source">
	<input type="hidden"
	value="https://ecommerceprovider.com/services/amazon/getKeys"
	name="keyShareURL">
	<input type="hidden" value="XXXXXXXXXXX" name="publicKey">
	<input type="hidden" value="ecommerceProvider1.1" name="spSoftwareVersion">
	<input type="hidden" value="version1.4" name="spAmazonPluginVersion">
	<input type="hidden" value="APUS_ECOMMERCEPROVIDER_XXXXX" name="ld">
	<input type="hidden" value="https://www.example.com/merchantSandboxIPN"
	name="merchantSandboxIPNURL">
	<input type="hidden" value="https://www.ecommerceprovider.com/spSandboxIPN"
	name="spSandboxIPNURL">
	<input type="hidden" value="https://www.example.com/merchantProductionIPN"
	name="merchantProductionIPNURL">
	<input type="hidden"
	value="https://www.ecommerceprovider.com/spProductionIPN"
	name="spProductionIPNURL">
	<input type="submit" value="Submit">
</form>