--- title: Add the Amazon Pay Button url: amazon-pay-recurring-checkout/add-the-amazon-pay-button.html --- **[Step 2 of 11]** The Amazon Pay checkout experience starts when the buyer clicks on the Amazon Pay button. Add the button wherever the buyer starts checkout, such as on the mini cart, shopping cart page, or checkout page. In this step, you will configure the Amazon Pay Checkout Session object and then render the Amazon Pay button. At the end of this step, you will be able to redirect the buyer to an Amazon Pay hosted page where they can select their preferred shipping address and payment instrument. You must add the domains where the Amazon Pay button will be rendered to Seller Central. See Add domains to Seller Central for more information. * TOC {:toc} {::options toc_levels="3" /} *** ### 1. Add the Amazon Pay script Add the Amazon Pay script to your HTML file. Be sure you select the correct region.
```html ```
```html ```
```html ```
*** ### 2. Generate the Create Checkout Session payload To render the Amazon Pay button, you will need to provide a payload that Amazon Pay will use to create a Checkout Session object. You will use the Checkout Session object to manage the buyer’s active session on your website. The payload has the same structure as the request body for the [Create Checkout Session](../amazon-pay-api-v2/checkout-session.html#create-checkout-session){:target="\_blank"} API. Providing the payload as part of the button removes the need to call this API. In the payload, you must provide all details required for the buyer to complete checkout. **Instructions for generating button payload:** * Set `checkoutReviewReturnUrl` parameter to the URL that the buyer is redirected to after they select their preferred shipping address and payment method. The Checkout Session ID will be appended as a query parameter. * Set `recurringMetadata.frequency` to increase buyer confidence. If you do not provide a value in this step, you are required to set a value before the buyer can complete checkout. Note that Amazon Pay only uses the values provided to calculate the Charge Permission expiration date and in buyer communication. You are still responsible for calling Create Charge to charge the buyer for each billing cycle. * Specify the buyer information you need to complete checkout using the `scopes` parameter. If you do not set this value, all buyer information except billing address will be requested. **Optional integrations steps:** * Use the `deliverySpecifications` parameter to specify shipping restrictions and prevent buyers from selecting unsupported addresses from their Amazon address book. See address restriction samples for samples how to handle common use-cases. * If you registered for Amazon Pay in the EU or UK, you can use the `presentmentCurrency` parameter to charge your buyer using a different supported currency. See multi-currency integration for more info. #### Payload example ``` { "webCheckoutDetails": { "checkoutReviewReturnUrl": "https://a.com/merchant-review-page" }, "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId", "scopes": ["name", "email", "phoneNumber", "billingAddress"], "chargePermissionType": "Recurring", "recurringMetadata": { "frequency": { "unit": "Month", "value": "1" }, "amount": { "amount": "30", "currencyCode": "USD" } }, "deliverySpecifications": { "specialRestrictions": ["RestrictPOBoxes"], "addressRestrictions": { "type": "Allowed", "restrictions": { "US": { "statesOrRegions": ["WA"], "zipCodes": ["95050", "93405"] }, "GB": { "zipCodes": ["72046", "72047"] }, "IN": { "statesOrRegions": ["AP"] }, "JP": {} } } } } ```
Name
Location
Description
webCheckoutDetails
(required)

Type: webCheckoutDetails
Body
URLs associated to the Checkout Session used to complete checkout. The URLs must use HTTPS protocol
storeId
(required)

Type: string
Body
Amazon Pay store ID. Retrieve this value from Amazon Pay Integration Central: US, EU, JP
scopes

Type: list <scope>
Body
The buyer details that you're requesting access to. Specify whether you need shipping address using button productType parameter in Step 4.

Supported values:
  • 'name' - Buyer name
  • 'email' - Buyer email
  • 'phoneNumber' - Buyer phone number. You must also request billingAddress scope or use payAndShip productType to retrieve the billing address or shipping address phone number.
  • 'billingAddress' - Default billing address
Default value: all buyer information except billing address is requested if the scopes parameter is not set
chargePermissionType

Type: string
Body
The type of Charge Permission requested

Supported values:
  • 'OneTime' - The Charge Permission can only be used for a single order
  • 'Recurring' - The Charge Permission can be used for recurring orders
Default value: 'OneTime"
recurringMetadata

Type: recurringMetadata
Body
Metadata about how the recurring Charge Permission will be used. Amazon Pay only uses this information to calculate the Charge Permission expiration date and in buyer communication

Note that it is still your responsibility to call Create Charge to charge the buyer for each billing cycle
deliverySpecifications

Type: deliverySpecifications
Body
Specify shipping restrictions to prevent buyers from selecting unsupported addresses from their Amazon address book
*** ### 3. Sign the payload You must secure the payload using a signature. The payload does not include a timestamp so you can re-use the signature as long as the payload does not change. If you need to change the payload and your button signature is dynamic, you should decouple button render from checkout initialization to avoid re-rendering the button. **Option 1 (recommended):** Generate a signature using the helper function provided in the Amazon Pay SDKs. The signature generated by the helper function is only valid for the button and not for API requests.
``` 'MY_PUBLIC_KEY_ID', 'private_key' => 'keys/private.pem', 'region' => 'US', 'sandbox' => true, 'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2' ); $client = new Amazon\Pay\API\Client($amazonpay_config); $payload = '{"storeId":"amzn1.application-oa2-client.xxxxx","webCheckoutDetails":{"checkoutReviewReturnUrl":"https://example.com/review.html"},"chargePermissionType":"Recurring","recurringMetadata":{"frequency":{ unit":"Month","value":"1"},"amount":{"amount":"30","currencyCode":"USD"}}}'; $signature = $client->generateButtonSignature($payload); echo $signature . "\n"; ?> ``` Source code
``` var payConfiguration = new ApiConfiguration ( region: Region.Europe, environment: Environment.Sandbox, publicKeyId: "MY_PUBLIC_KEY_ID", privateKey: "PATH_OR_CONTENT_OF_MY_PRIVATE_KEY", algorithm: AmazonSignatureAlgorithm.V2 ); var request = new CreateCheckoutSessionRequest ( checkoutReviewReturnUrl: "https://example.com/review.html", storeId: "amzn1.application-oa2-client.xxxxx" ); request.ChargePermissionType = ChargePermissionType.Recurring; request.RecurringMetadata.Frequency.Unit = FrequencyUnit.Month; request.RecurringMetadata.Frequency.Value = 1; request.RecurringMetadata.Amount.Unit = 99.99M; request.RecurringMetadata.Amount.CurrencyCode = Currency.EUR; // generate the button signature var signature = client.GenerateButtonSignature(request); // the payload as JSON string that you must assign to the button in the next step var payload = request.ToJson(); ``` Source code
``` PayConfiguration payConfiguration = null; try { payConfiguration = new PayConfiguration() .setPublicKeyId("YOUR_PUBLIC_KEY_ID") .setRegion(Region.YOUR_REGION_CODE) .setPrivateKey("YOUR_PRIVATE_KEY_STRING") .setEnvironment(Environment.SANDBOX) .setAlgorithm("AMZN-PAY-RSASSA-PSS-V2"); }catch (AmazonPayClientException e) { e.printStackTrace(); } AmazonPayClient client = new AmazonPayClient(payConfiguration); String payload = "{\"storeId\":\"amzn1.application-oa2-client.xxxxxx\",\"webCheckoutDetails\":{\"checkoutReviewReturnUrl\":\"https://example.com/review.html\"},\"chargePermissionType\":\"Recurring\",\"recurringMetadata\":{\"frequency\":{\"unit\":\"Month\",\"value\":\"1\"},\"amount\":{\"amount\":\"30\",\"currencyCode\":\"USD\"}}}"; String signature = client.generateButtonSignature(payload); ``` Source code
```html const fs = require('fs'); const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs'); const config = { publicKeyId: 'ABC123DEF456XYZ', privateKey: fs.readFileSync('tst/private.pem'), region: 'us', sandbox: true, algorithm: 'AMZN-PAY-RSASSA-PSS-V2' }; const testPayClient = new Client.AmazonPayClient(config); const payload = { "webCheckoutDetails": { "checkoutReviewReturnUrl": "https://example.com/review.html" }, "storeId": "amzn1.application-oa2-client.xxxxx", "chargePermissionType": "Recurring", "recurringMetadata": { "frequency": { "unit": "Month", "value": "1" }, "amount": { "amount": "30", "currencyCode": "USD" } } }; const signature = testPayClient.generateButtonSignature(payload); ``` Source code
**Option 2:** Build the signature manually by following steps 2 and 3 of the signing requests guide. *** ### 4. Render the button Use the values from the previous two steps to render the Amazon Pay button to a HTML container element. The button will be responsive and it will inherit the size of the container element, see responsive button logic for details. The code below will initiate Amazon Pay checkout immediately on button click. If you need control of the click event, you can decouple button render and checkout initiation. See Amazon Pay script for more info. #### Code sample #### Function parameters
Parameter
Description
merchantId
(required)

Type: string
Amazon Pay merchant account identifier
createCheckoutSessionConfig
(required)

Type: buttonConfig
Create Checkout Session configuration. This is a required field if you use PayAndShip or PayOnly productType
placement
(required)

Type: string
Placement of the Amazon Pay button on your website

Supported values:
  • 'Home' - Initial or main page
  • 'Product' - Product details page
  • 'Cart' - Cart review page before buyer starts checkout
  • 'Checkout' - Any page after buyer starts checkout
  • 'Other' - Any page that doesn't fit the previous descriptions
ledgerCurrency
(required)

Type: string
Ledger currency provided during registration for the given merchant identifier

Supported values:
  • US merchants - 'USD'
  • EU merchants - 'EUR'
  • UK merchants - 'GBP'
  • JP merchants - 'JPY'
productType

Type: string
Product type selected for checkout

Supported values:
  • 'PayAndShip' - Offer checkout using buyer's Amazon wallet and address book. Select this product type if you need the buyer's shipping details
  • 'PayOnly' - Offer checkout using only the buyer's Amazon wallet. Select this product type if you do not need the buyer's shipping details
  • 'SignIn' - Offer Amazon Sign-in. Select this product type if you need buyer details before the buyer starts Amazon Pay checkout. See Amazon Sign-in for more information.
Default value: 'PayAndShip'
buttonColor

Type: string
Color of the Amazon Pay button

Supported values: 'Gold', 'LightGray', 'DarkGray'
Default value: 'Gold'
checkoutLanguage

Type: string
Language used to render the button and text on Amazon Pay hosted pages. Please note that supported language(s) is dependent on the region that your Amazon Pay account was registered for

Supported values: 
  • US merchants - 'en_US'
  • EU/UK merchants - 'en_GB', 'de_DE', 'fr_FR', 'it_IT', 'es_ES'
  • JP merchants - 'ja_JP'
sandbox

Type: boolean
Sets button to Sandbox environment

You do not have to set this parameter if your publicKeyId has an environment prefix (for example: SANDBOX-AFVX7ULWSGBZ5535PCUQOY7B)

Default value: false