--- title: Steps to integrate with Amazon Pay's hosted update page url: amazon-pay-paymentmethodonfile/steps-to-integrate-with-amazon-pay-hosted-update-page.html --- You can integrate with Amazon Pay’s solution that handles the payment and address update for the buyer. Follow below steps to integrate the solution: * Add the Amazon Pay script * Provide a payload that Amazon Pay will use to create a Checkout Session object that will be used for the update. Amazon Pay will use the Checkout Session object to manage the buyer’s activity during the update. * Sign the payload. * Render a custom button and call Amazon Pay’s init checkout API * Once buyer updates the address/PI and returns to youryou website, use Complete Checkout Session to confirm that the buyer has successfully returned to your site. * Set up IPNs to receive notifications whenever buyers update their payment method or address. * 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 Provide a payload that Amazon Pay will use to create a Checkout Session object that will be used for the update. Amazon Pay will use the Checkout Session object to manage the buyer’s activity during the update. **Instructions for generating button payload for the update flow:** * Set `checkoutResultReturnUrl` parameter to the URL that the buyer is redirected to after they select their preferred payment method. The Checkout Session ID will be appended as a query parameter. * Set `chargePermissionId` to the *Saved Wallet* charge permission id value stored for the buyer. * Set `chargePermissionType` to `PaymentMethodOnFile` * Set `productType` as “PayAndShip” * If buyer intends to update an address * If buyer intends to update payment method for a charge permission id that has an associated address * If you intend to update theSaved Wallet Charge Permission Id from a “PayOnly” product type to a “PayAndShip” productType. * Set `productType` as “PayOnly” if the Saved Wallet Charge Permission Id stored on your systems was of type “PayOnly” and buyer's intention is to update the payment method alone. * Provide details for `paymentMethodOnFileMetadata`: Provide `setupOnly = true` to initiate a update payment method or address flow for a Saved Wallet charge permission id. * Set `paymentIntent = Confirm` since there is no transaction happening in update flow. **Optional integrations steps:** * Use the `deliverySpecifications` parameter to specify shipping restrictions to prevent buyers from selecting unsupported addresses from their Amazon address book. See [address restriction samples](../amazon-pay-checkout/v1-address-restriction-samples.html) for samples how to handle common use-cases. #### Payload example ``` { "webCheckoutDetails": { "checkoutResultReturnUrl": "https://a.com/merchant-result-page" }, "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId", "chargePermissionId": "B01-0000000-0000000", "chargePermissionType": "PaymentMethodOnFile", "paymentMethodOnFileMetadata": { "setupOnly": true }, "paymentDetails": { "paymentIntent": "Confirm", "canHandlePendingAuthorization": false } "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' - Default billing address phone number
  • 'billingAddress' - Default billing address
Default value: all buyer information except billing address is requested if the scopes parameter is not set
chargePermissionId

Type: string
Body
The buyer's Saved Wallet charge permission id with the merchant
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
  • 'PaymentMethodOnFile' - The Charge Permission can be used for Saved Wallet orders
Default value: 'OneTime"
paymentDetails

Type: paymentDetails
Body
Payment details specified by the merchant such as the amount and method for charging the buyer

Modifiable: Multiple times before the buyer is redirected to the amazonPayReturnUrl
merchantMetadata

Type: merchantMetadata
Body
External order details provided by the merchant

Modifiable: Multiple times before the buyer is redirected to the amazonPayReturnUrl
paymentMethodOnFileMetadata

Type: paymentMethodOnFileMetadata
Body
Metadata about how Saved Wallet charge permission will be used.
*** ### 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. **Option 1 (recommended):** Generate a signature using the helper function provided in the Amazon Pay SDKs.
``` 'MY_PUBLIC_KEY_ID', 'private_key' => 'keys/private.pem', 'region' => 'US', 'sandbox' => true ); $client = new Amazon\Pay\API\Client($amazonpay_config); $payload = '{"storeId":"amzn1.application-oa2-client.xxxxx","webCheckoutDetails":{"checkoutResultReturnUrl":"https://example.com/review.html"},"chargePermissionId": "B01-0000000-0000000","chargePermissionType":"PaymentMethodOnFile","paymentMethodOnFileMetadata":{"setupOnly": true}, "paymentDetails": {"paymentIntent": "Confirm", "canHandlePendingAuthorization": false}}'; $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" ); var request = new CreateCheckoutSessionRequest ( checkoutReviewReturnUrl: "https://example.com/review.html", storeId: "amzn1.application-oa2-client.xxxxx", chargePermissionId: "B01-0000000-0000000" ); request.ChargePermissionType = ChargePermissionType.PaymentMethodOnFile; request.PaymentMethodOnFileMetadata.SetupOnly = true; request.PaymentDetails.PaymentIntent = PaymentIntent.Confirm; request.PaymentDetails.CanHandlePendingAuthorization = false; // generate the payload 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); }catch (AmazonPayClientException e) { e.printStackTrace(); } AmazonPayClient client = new AmazonPayClient(payConfiguration); String payload = "{\"storeId\":\"amzn1.application-oa2-client.xxxxxx\",\"webCheckoutDetails\":{\"checkoutResultReturnUrl\":\"https://example.com/review.html\"},\"chargePermissionId\":\"B01-0000000-0000000\",\"chargePermissionType\":\"PaymentMethodOnFile\",\"paymentMethodOnFileMetadata\":{\"setupOnly\": true}, \"paymentDetails\": {\"paymentIntent\": \"Confirm\", \"canHandlePendingAuthorization\": false}}"; 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 }; const testPayClient = new Client.AmazonPayClient(config); const payload = { "webCheckoutDetails": { "checkoutResultReturnUrl": "https://example.com/review.html" }, "storeId": "amzn1.application-oa2-client.xxxxx", "chargePermissionId": "B01-0000000-0000000", "chargePermissionType": "PaymentMethodOnFile", "paymentMethodOnFileMetadata": { "setupOnly": true }, "paymentDetails": { "paymentIntent": "Confirm", "canHandlePendingAuthorization": false } }; 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 an UI element and call Amazon Pay's init checkout API Any UI element can be rendered to trigger the payment method and/or address update. UI element click should be bound to call amazon pay’s init update function as shown in the example below. Once the UI element is clicked buyer will be redirected to Amazon’s page where they can update the payment method or address. After the successful update buyer is redirected back to the `checkoutResultReturnUrl` that was set in the payload. **NOTE:** The amzon.Pay.initUpdate() function is not yet available, to test the update flow, please use amazon.Pay.initCheckout() function instead. #### Code sample
```html ```
```html ```
```html ```
```html ```
*** ### 5. Set up Instant Payment Notifications (IPN) Set up IPNs to receive notifications whenever buyers update their payment method or address.