Amazon Payボタンを追加する

[ステップ2/7] Amazon Payの決済エクスペリエンスは、購入者がAmazon Payボタンをクリックすると開始されます。ミニカート、ショッピングカートページ、決済ページなど、購入者が決済を開始する場所にボタンを追加します。

このステップでは、Amazon Pay CheckoutSessionオブジェクトを設定してから、Amazon Payボタンをレンダリングします。このステップの最後に、購入者をAmazon Payでホストされているページにリダイレクトして、お支払い方法を選択できるようになります。


1. Amazon Payスクリプトを追加します

Amazon PayスクリプトをHTMLファイルに追加します。必ず正しいリージョンを選択してください。

<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. Checkout Sessionペイロードを生成します

Amazon Payボタンをレンダリングするには、 Checkout Sessionオブジェクトを作成するために使用するペイロードを提供する必要があります。 CheckoutSessionオブジェクトを使用して、Webサイトでの購入者のアクティブなセッションを管理します。

ペイロードに購入者が決済を完了させるのに必要な全ての情報を設定します。

ボタンペイロード生成手順:

  • webCheckoutDetails.checkoutModeをProcessOrderに設定します。
  • Amazon Payでホストされているページで決済を完了した後、購入者がリダイレクトされるURLとしてcheckoutResultReturnUrlを設定します。CheckoutSession IDはクエリパラメータとして追加されます。
  • paymentDetailsを指定する必要があります:
    • paymentIntent - 購入者がAmazonの「今すぐ支払う」ボタンをクリックしたときの支払いアクション
    • chargeAmount - 決済金額(recurringMetadataを設定しない場合には必須)
  • PaymentMethodOnFileとしてChargePermissionを利用する為に、chargePermissionTypeに"PaymentMethodOnFile" を設定します。
  • 決済時に合わせてお支払い方法の設定を行うフローとするために、paymentMethodOnFileMetadata項目としてsetupOnly = falseを設定します。
  • 配送先住所が必要な物販でのトランザクションの場合は、productTypeをPayAndShipに設定します。デジタル商材の場合、productTypeをPayOnlyに設定します。
  • productTypeがPayAndShipの場合は、購入者から提供された配送先住所をaddressDetailsに設定する必要があります。アドレスデータを渡す方法の詳細については、アドレスのフォーマットと検証を参照してください。
  • scopesパラメータを使用して、決済を完了するために必要な購入者情報を指定します。この値を設定した場合、請求先住所など追加で取得できます。
  • もし定期商材が含まれている場合は、recurringMetadata.frequencyを設定することで、購入者の信頼性を高めることができます。もしこのステップで値を設定しない場合は、購入者が決済を完了する前までに値を設定する必要があります。Amazon Payは、提供された値を使用して、購入者とのコミュニケーションに用います。定期商材への請求を行うためには、事業者がCreate Chargeを呼び出して、請求サイクルごとに購入者に請求する必要があります。

オプションのインテグレーション手順:

  • merchantMetadataパラメータを使用して、このトランザクションに追加の注文詳細を設定できます。
  • (EU/UKのみ)presentmentCurrencyパラメータを使用して、 他のサポートされている通貨を使用して購入者に請求できます。詳細については、こちらを参照してください。

ペイロードの例(任意のタイミングで請求する商材が存在する場合)

{
    "webCheckoutDetails": {
        "checkoutResultReturnUrl": "https://a.com/merchant-review-page",
        "checkoutMode": "ProcessOrder"
    },
    "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "scopes": ["name", "email", "phoneNumber", "billingAddress"],
    "chargePermissionType": "PaymentMethodOnFile",
    "paymentMethodOnFileMetadata": {
        "setupOnly": false,
    },  
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "chargeAmount": {
            "amount": "10",
            "currencyCode": "USD"
        },
        "presentmentCurrency":"USD"
    },
    "merchantMetadata": {
        "merchantReferenceId":"Merchant-order-123",
        "merchantStoreName":"Merchant Store Name",
        "noteToBuyer":"Thank you for your order"
    },
    "addressDetails": {
        "name": "Paul Smith",
        "addressLine1": "9999 First Avenue",
        "city": "New York",
        "stateOrRegion": "NY",
        "postalCode": "10016",
        "countryCode": "US",
        "phoneNumber": "212555555"
    }
}

ペイロードの例(定期商材が存在する場合)

{
    "webCheckoutDetails": {
        "checkoutResultReturnUrl": "https://a.com/merchant-review-page",
        "checkoutMode": "ProcessOrder"
    },
    "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "scopes": ["name", "email", "phoneNumber", "billingAddress"],
    "chargePermissionType": "PaymentMethodOnFile",
    "paymentMethodOnFileMetadata": {
        "setupOnly": false,
    },
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    },     
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "presentmentCurrency":"USD"
    },
    "merchantMetadata": {
        "merchantReferenceId":"Merchant-order-123",
        "merchantStoreName":"Merchant Store Name",
        "noteToBuyer":"Thank you for your order"
    },
    "addressDetails": {
        "name": "Paul Smith",
        "addressLine1": "9999 First Avenue",
        "city": "New York",
        "stateOrRegion": "NY",
        "postalCode": "10016",
        "countryCode": "US",
        "phoneNumber": "212555555"
    }
}

ペイロードの例(任意のタイミングで請求する商材と定期商材が存在する場合)

  • 任意のタイミングで請求する商材の金額は、chargeAmount項目に設定してください。
  • 初回の定期商材の請求金額も含めて、chargeAmountに設定した場合は、事業者は初回請求時の為のCreate Chargeをスキップすることができます。
  • 定期商材への請求を行うためには、事業者はCreate Chargeを呼び出して、請求サイクルごとに購入者に請求する必要があります。
{
    "webCheckoutDetails": {
        "checkoutResultReturnUrl": "https://a.com/merchant-review-page",
        "checkoutMode": "ProcessOrder"
    },
    "storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
    "scopes": ["name", "email", "phoneNumber", "billingAddress"],
    "chargePermissionType": "PaymentMethodOnFile",
    "paymentMethodOnFileMetadata": {
        "setupOnly": false,
    },
    "recurringMetadata": {
        "frequency": { 
            "unit": "Month", 
            "value": "1" 
        },
        "amount": { 
            "amount": "30",
            "currencyCode": "USD"
        }
    },     
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "chargeAmount": {
            "amount": "10",
            "currencyCode": "USD"
        },
        "presentmentCurrency":"USD"
    },
    "merchantMetadata": {
        "merchantReferenceId":"Merchant-order-123",
        "merchantStoreName":"Merchant Store Name",
        "noteToBuyer":"Thank you for your order"
    },
    "addressDetails": {
        "name": "Paul Smith",
        "addressLine1": "9999 First Avenue",
        "city": "New York",
        "stateOrRegion": "NY",
        "postalCode": "10016",
        "countryCode": "US",
        "phoneNumber": "212555555"
    }
}
名前
ロケーション
説明
webCheckoutDetails
(必須)

Type: webCheckoutDetails
Body
Checkout Sessionに関連付けられたURLは、決済を完了するために使用されます。 URLはHTTPSプロトコルを使用する必要があります

checkoutModeを使用して、購入者が決済を完了する前に注文を確認するためにWebサイトに戻るかどうかを指定します
storeId
(必須)

Type: string
Body
Amazon Pay StoreID。 Amazon Pay インテグレーションセントラルからこの値を取得します: USEUJP
scopes

Type: list <scope>
Body
必要となる購入者情報詳細を指定します。

サポートされている値:
  • 'name' - 名前
  • 'email' - メールアドレス
  • 'phoneNumber' - 既定の請求先住所の電話番号
  • 'billingAddress' - 既定の請求先住所
デフォルト値: scopesパラメータが設定されていない場合、請求先住所以外のすべての購入者情報をリクエストしたことになります
chargePermissionType

Type: string
Body
要求されたCharge Permissionタイプ

サポートされている値:
  • 'OneTime' - Charge Permissionは1回の注文に使用できます
  • 'Recurring' - Charge Permissionは定期的な注文に使用できます
  • 'PaymentMethodOnFile' - Charge Permissionは、お支払い方法設定での(不定期な課金を伴う)注文に使用できます


デフォルト値: 'OneTime'
paymentDetails

Type: paymentDetails
Body
paymentIntentや購入者への請求金額など、事業者が指定する支払い内容の情報。
merchantMetadata

Type: merchantMetadata
Body
事業者が提供する注文の詳細情報
addressDetails

Type: addressDetail
Body
購入者が入力した配送先住所。このパラメータは、 checkoutModeがProcessOrderで productTypeがPayAndShipの場合にのみ使用してください。
paymentMethodOnFileMetadata

Type: paymentMethodOnFileMetadata
Body
ChargePermissionをPaymentMethodOnFileの中でどのように利用するかを示す詳細情報。Amazon Payは、PaymentMethodOnFileとして処理を行うのに必要な情報を判別する為にこの情報を利用します。
recurringMetadata

Type: recurringMetadata
Body
RecurringのChargePermissionをどのように利用するかを示す詳細情報。Amazon Payは、この情報を購入者とのコミュニケーションにのみ使用します。

3. ペイロードに署名します

署名を使用してペイロードを保護する必要があります。ペイロードにはタイムスタンプが含まれていないため、ペイロードが変更されない限り、署名を再利用できます。ペイロードを変更する必要があり、ボタンの署名が動的である場合は、ボタンの再レンダリングを回避するために、決済の初期化からボタンのレンダリングを切り離す必要があります。

オプション1(推奨): Amazon Pay SDKで提供されるヘルパー関数を使用して署名を生成します。ヘルパー関数によって生成された署名は、ボタンに対してのみ有効であり、APIリクエストは有効ではありません。

<?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"},"chargePermissionType":"PaymentMethodOnFile","paymentMethodOnFileMetadata":{"setupOnly": false}, "paymentDetails": {"paymentIntent": "AuthorizeWithCapture", "canHandlePendingAuthorization": false}}';
    $signature = $client->generateButtonSignature($payload);
    echo $signature . "\n";
?>

ソースコード

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
(
    checkoutResultReturnUrl: "https://example.com/review.html",
    storeId: "amzn1.application-oa2-client.xxxxx"
);

rvequest.ChargePermissionType = ChargePermissionType.PaymentMethodOnFile;
request.PaymentMethodOnFileMetadata.SetupOnly = false;
request.PaymentDetails.PaymentIntent = PaymentIntent.AuthorizeWithCapture;
request.PaymentDetails.CanHandlePendingAuthorization = false;

// 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(); 

ソースコード

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\"},\"chargePermissionType\":\"PaymentMethodOnFile\",\"paymentMethodOnFileMetadata\":{\"setupOnly\": false}, \"paymentDetails\": {\"paymentIntent\": \"AuthorizeWithCapture\", \"canHandlePendingAuthorization\": false}}";
String signature = client.generateButtonSignature(payload);

ソースコード

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",
    "chargePermissionType": "PaymentMethodOnFile",   
    "paymentMethodOnFileMetadata": {
        "setupOnly": false
    },
    "paymentDetails": {
        "paymentIntent": "AuthorizeWithCapture",
        "canHandlePendingAuthorization": false
    }
};
const signature = testPayClient.generateButtonSignature(payload);

ソースコード

オプション2: 署名リクエストガイドの手順2と3に従って、手動で署名を作成します。


4. ボタンをレンダーします

前の2つの手順の値を使用して、Amazon PayボタンをHTMLコンテナ要素にレンダリングします。ボタンはレスポンシブになり、コンテナ要素のサイズを継承します。詳細については、 レスポンシブボタンのロジックを参照してください。

以下のコードは、ボタンをクリックするとすぐにAmazon Payの決済を開始します。クリックイベントの制御が必要な場合は、ボタンのレンダリングと決済の開始を切り離すことができます。詳細については、 Amazon Payスクリプトを参照してください。

コードサンプル

関数パラメータ

パラメータ
説明
merchantId
必須

Type: string
Amazon Pay 事業者アカウント識別子
createCheckoutSessionConfig
必須

Type: buttonConfig
Checkout Sessionを構成します。 PayAndShipまたはPayOnlyproductType を使用する場合、これは必須フィールドです。
placement
必須

Type: string
ウェブサイトへのAmazon Payボタンの配置

サポートされている値:
  • 'Home' -初期ページまたはメインページ
  • 'Product' -製品詳細ページ
  • 'Cart' -購入者が決済を開始する前のカートレビューページ
  • 'Checkout' -購入者が決済を開始した後の任意のページ
  • 'Other' -前の説明に当てはまらないページ
ledgerCurrency
必須

Type: string
指定された出品者IDの登録時に提供された通貨

サポートされている値:
  • US 事業者-'USD '
  • EU 事業者-'EUR '
  • UK 事業者-'GBP '
  • JP 事業者- 'JPY'
productType

Type: string
決済用に選択されたproductType

サポートされている値:
  • 'PayAndShip' - 物販の場合は、'PayAndShip'を選択します。ボタンのペイロードで購入者の配送先住所を渡す必要があります
  • 'PayOnly' - デジタル商品を販売している場合は'PayOnly'を選択します
デフォルト値: 'PayAndShip'
buttonColor

Type: string
Amazon Payボタンの色

サポートされている値: 'Gold'、 'LightGray'、 'DarkGray'
デフォルト値: 'Gold'
checkoutLanguage

Type: string
Amazon Payがホストするページでボタンとテキストをレンダリングするために使用される言語。サポートされている言語は、Amazon Payアカウントが登録されているリージョンによって異なることに注意してください。

サポートされている値:
  • US 事業者 - 'en_US '
  • EU/UK 事業者 - 'en_GB'、'de_DE'、 'fr_FR'、 'it_IT'、 'es_ES'
  • JP 事業者 - 'ja_JP '
sandbox

Type: boolean
ボタンをSANDBOXに設定します

デフォルト値:false