ログイン

Amazon Pay Hosted Pageでのお届け先/支払い方法変更のインテグレーション手順

現時点では、この機能は日本ではサポートされていません。

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:

1. Add the Amazon Pay script
2. Generate the Create Checkout Session payload
3. Sign the payload
4. Render an UI element and call Amazon Pay's init checkout API
5. Verify & complete checkout
6. Set up Instant Payment Notifications (IPN)

1. Add the Amazon Pay script

Add the Amazon Pay script to your HTML file. Be sure you select the correct region.

<script src="https://static-na.payments-amazon.com/checkout.js"></script>

<script src="https://static-eu.payments-amazon.com/checkout.js"></script>

<script src="https://static-fe.payments-amazon.com/checkout.js"></script>

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 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 to indicate payment method on file charge permission.
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 the Saved Wallet Charge Permission Id from a “PayOnly” product type to a “PayAndShip” productType.
Set productType as “PayOnly” if the Saved Wallet Charge Permission Id was of type “PayOnly” and buyer's intention is to update the payment method alone.
Provide details for paymentMethodOnFileMetadata: Provide setupOnly = fase 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 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 payment method on file 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 payment method on file 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 payment method on file 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.

<?php
    include 'vendor/autoload.php';

    $amazonpay_config = array(
        'public_key_id' => '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": false}, "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 = false;
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\": false}, \"paymentDetails\": {\"paymentIntent\": \"Confirm\", \"canHandlePendingAuthorization\": false}}";
String signature = client.generateButtonSignature(payload);

Source code

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": false
    },
    "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 checkout 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.

Code sample

<body>
    <button onclick="initAmazonPayCheckout()">Update</button>
    <script src="https://static-na.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        function initAmazonPayCheckout() {
            amazon.Pay.initCheckout({
                merchantId: 'merchant_id',
                ledgerCurrency: 'USD',
                sandbox: false,            
                checkoutLanguage: 'en_US',
                productType: 'PayAndShip',
                createCheckoutSessionConfig: {                     
                    payloadJSON: 'payload', 
                    signature: 'xxxx',
                    publicKeyId: 'xxxxxxxxxx'
                }   
            });
        }
    </script>
</body>

<body>
    <button onclick="initAmazonPayCheckout()">Update</button>
    <script src="https://static-eu.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        function initAmazonPayCheckout() {
            amazon.Pay.initCheckout({
                merchantId: 'merchant_id',
                ledgerCurrency: 'EUR',
                sandbox: false,            
                checkoutLanguage: 'en_GB',
                productType: 'PayAndShip',
                createCheckoutSessionConfig: {                     
                    payloadJSON: 'payload', 
                    signature: 'xxxx',
                    publicKeyId: 'xxxxxxxxxx'
                }   
            });
        }
    </script>
</body>

<body>
    <button onclick="initAmazonPayCheckout()">Update</button>
    <script src="https://static-eu.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        function initAmazonPayCheckout() {
            amazon.Pay.initCheckout({
                merchantId: 'merchant_id',
                ledgerCurrency: 'GBP',
                sandbox: false,            
                checkoutLanguage: 'en_GB',
                productType: 'PayAndShip',
                createCheckoutSessionConfig: {                     
                    payloadJSON: 'payload', 
                    signature: 'xxxx',
                    publicKeyId: 'xxxxxxxxxx'
                }   
            });
        }
    </script>
</body>

<body>
    <button onclick="initAmazonPayCheckout()">Update</button>
    <script src="https://static-fe.payments-amazon.com/checkout.js"></script>
    <script type="text/javascript" charset="utf-8">
        function initAmazonPayCheckout() {
            amazon.Pay.initCheckout({
                merchantId: 'merchant_id',
                ledgerCurrency: 'JPY',
                sandbox: false,            
                checkoutLanguage: 'ja_JP',
                productType: 'PayAndShip',
                createCheckoutSessionConfig: {                     
                    payloadJSON: 'payload', 
                    signature: 'xxxx',
                    publicKeyId: 'xxxxxxxxxx'
                }   
            });
        }
    </script>
</body>

5. Verify & complete checkout

The buyer is redirected to checkoutResultReturnUrl after Amazon Pay has successfully updated the Saved Wallet charge permission.

In this step, you will call the Complete Checkout Session API with checkout session ID to confirm that the buyer has successfully returned to your site. At the end of this step, you will be able to present the buyer with the update result.

Successful response:

Complete Checkout Session will return a success response if the update was processed successfully.

Error response:

Complete Checkout Session will return an error response for failed update. The buyer either canceled update or was unable to provide a valid payment instrument. You should:

Redirect the buyer to the start of update flow
Display a message such as: "The update for your address or payment method failed. Please try again.“

Request

curl "https://pay-api.amazon.com/:version/checkoutSessions/:checkoutSessionId/complete" \ -X POST -H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE" -H "x-amz-pay-date:20201012T235046Z" -d @request_body

Request body

{ }

Request parameters

Name	Location	Description
checkoutSessionId (required) Type: string	Path parameter	Checkout Session identifier

Response

Returns HTTP 200 status response code if update was successful

{
    "checkoutSessionId": "bd504926-f659-4ad7-a1a9-9a747aaf5275",
    "webCheckoutDetails": null,
    "chargePermissionType": PaymentMethodOnFile,   
    "recurringMetadata": null,
    "productType": null,
    "paymentDetails": null,
    "merchantMetadata": null,
    "paymentMethodOnFileMetadata": null,    
    "supplementaryData":null, // Amazon Pay system data 
    "buyer": null,
    "billingAddress": null,
    "paymentPreferences": [
        null
    ],
    "statusDetails": {
        "state": "Completed",
        "reasonCode": null,
        "reasonDescription": null,
        "lastUpdatedTimestamp": "20191015T204327Z"
    },
    "shippingAddress": null,
    "platformId":null,
    "chargePermissionId": "S01-5105180-3221187",
    "chargeId": "S01-5105180-3221187-C056351",
    "constraints": [
        null
    ],
    "creationTimestamp": "20191015T204313Z",
    "expirationTimestamp": null,
    "storeId": null,
    "deliverySpecifications": null,
    "providerMetadata": null,
    "releaseEnvironment": null
}

6. Set up Instant Payment Notifications (IPN)

Set up IPNs to receive notifications whenever buyers update their payment method or address.