OneTimeからRecurringへのアップグレード
OneTimeからRecurringへアップグレードすることが可能です。方法は二つあり、Checkout SessionのchargePermissionTypeを決済フロー中に変更する方法と、決済完了後に購入者をAmazon Payがホストするページに遷移させてアップグレードを確認させた上で、recurring Charge Permissionを作成する方法です。
決済フロー中にアップグレードする
Update Checkout Sessionを使用してOneTimeからRecurringへアップグレードします。chargePermissionTypeにRecurringを設定した上、recurringMetadata.frequencyも指定します。Amazon PayはrecurringMetadata.frequencyをCharge Permissionの期限日と購入者とのコミュニケーションにしか利用しないことに注意してください。支払いサイクルごとの購入者への売上請求のためにはCreate Charge を必要なタイミングで実行する必要があります。
Checkout Sessionがアップグレードして購入者が決済完了できる準備ができたら、決済を確認・完了する を実装してください。
リクエスト
リクエストボディ
{
"chargePermissionType": "Recurring",
"recurringMetadata": {
"frequency": {
"unit": "Month",
"value": "1"
},
"amount": {
"amount": "30",
"currencyCode": "USD"
}
}
}
決済後にアップグレードする
既存のOneTime Charge Permissionのアップグレードを購入者に確認させるには、購入者をAmazonPayがホストするページにリダイレクトする必要があります。Charge Permissionをアップグレードするためには、次のことを行う必要があります。
- Amazon Payスクリプトを追加します
- bindUpgradeActionペイロードを生成します
- ペイロードに署名する
- amazon.Pay.bindUpgradeAction()を使用して、クリックイベントをHTML要素にバインドします
- 決済を確認・完了する を実装します
Step 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>
Step 2. bindUpgradeActionペイロードを生成します
Amazon Payがアップグレード内容を設定するために使用するペイロードを提供します。
bindUpgradeActionペイロードを生成するための手順：
chargePermissionTypeをRecurringに設定します。- Recurring Charge Permissionの生成に使用する
chargePermissionIdを、OneTime Charge PermissionのCharge Permission IDに設定します。 checkoutResultReturnUrlを、購入者がアップグレードを確認した後にリダイレクトされるURLに設定します。Checkout Session IDは、クエリパラメータとして指定されたURLに追加されます。- 配送先住所が必要な物理的なトランザクションの場合は、
productTypeをPayAndShipに設定します。取得される配送先住所は、OneTime Charge Permissionに関連付けられている住所になります。デジタル取引の場合、productTypeをPayOnlyに設定します。 chargeAmountを、アップグレード中にpaymentIntentを使用して処理する必要がある値に設定します。アップグレード中に支払いを要求しない場合は、paymentIntentをConfirmに設定します。recurringMetadata.frequencyを設定して、購入者の信頼を高めます。Amazon Payは、提供された値をCharge Permissionの有効期限の計算と購入者との連絡のためだけに使用することに注意してください。請求サイクルごとの購入者への請求は、Create Chargeを呼び出す必要があります。scopesパラメータを使用して、アップグレードを完了するために必要な購入者情報を指定します。この値を設定しない場合、すべての購入者情報が要求されます。
ペイロードの例
{
"merchantId":"merchant_id",
"storeId":"amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
"ledgerCurrency": "USD",
"chargePermissionType": "Recurring",
"chargePermissionId":"charge_permission_id",
"webCheckoutDetails": {
"checkoutResultReturnUrl":"https://a.com/merchant-result-page"
},
"productType": "PayAndShip",
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"chargeAmount": {
"amount": "10",
"currencyCode": "USD"
},
"presentmentCurrency":"USD"
},
"recurringMetadata": {
"frequency": {
"unit": "Month",
"value": "1"
},
"amount": {
"amount": "30",
"currencyCode": "USD"
}
},
"scopes": ["name", "email", "phoneNumber", "billingAddress"]
}
| パラメータ
|
説明
|
| merchantId (必須) Type: string |
Amazon Pay 事業者アカウント識別子
|
| storeId (必須) Type: string |
Amazon PayのStore IDです。 Amazon Pay インテグレーションセントラルUS, EU, JPからこの値を取得します。
|
| ledgerCurrency (必須) Type: string |
指定された出品者IDの登録時に提供された通貨 サポートされている値:
|
| chargePermissionType (必須) Type: string |
リクエストされたCharge PermissionのType サポートされている値: 'Recurring' - このCharge Permissionは定期的な注文に使用できます |
| chargePermissionId (必須) Type: string |
Recurring Charge Permissionの生成に使用するOneTimeのCharge Permission ID
|
| recurringMetadata (必須) Type: recurringMetadata |
RecurringのCharge Permissionの使用方法に関するメタデータ。 Amazon Payは、この情報を使用して、Charge Permissionの有効期限を計算し、購入者と連絡を取ります。
請求サイクルごとに購入者に請求するためにCreate Chargeを実行することは事業者責任であることに注意してください。 |
| webCheckoutDetails (必須) Type: webCheckoutDetails |
購入者がアップグレードを確認した後にリダイレクトされるURL。 URLはHTTPSプロトコルを使用する必要があります。
|
| productType (必須) Type: string |
アップグレード用に選択されたAmazon Payインテグレーションタイプ。 サポートされている値: 'PayAndShip' - 購入者のお届け先と支払い方法を使用した決済を提供します。購入者のお届け先情報が必要な場合は、このproduct typeを選択してください 'PayOnly' - 購入者の支払い方法のみを使用した決済を提供します。購入者のお届け先情報が必要ない場合は、このproduct typeを選択してください デフォルト値: 'PayAndShip' |
| paymentDetails (必須) Type: paymentDetails |
購入者に請求する金額や方法など、販売者が指定した支払いの詳細
|
| checkoutLanguage Type: string |
Amazon Pay Hosted pageでボタンとテキストをレンダリングするために使用される言語。サポートされている言語は、Amazon Payアカウントの申し込みを行った地域によって異なることに注意してください。 サポートされている値:
|
| scopes Type: list<scope> |
リクエストする購入者の詳細情報。productTypeを使用して、配送先住所が必要かどうかを指定します。 サポートされている値:
scopesパラメータが設定されていない場合、請求先住所以外のすべての購入者情報をリクエストしたことになります
|
Step 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 = '{"merchantId":"merchant_id","storeId":"amzn1.application-oa2-client.xxxxx","ledgerCurrency":"USD","webCheckoutDetails":{"checkoutResultReturnUrl":"https://example.com/result.html"},"chargePermissionType":"Recurring","chargePermissionId":"P01-1111111-1111111","productType":"PayAndShip","paymentDetails":{"paymentIntent":"AuthorizeWithCapture","chargeAmount":{"amount":"10","currencyCode":"USD"},"presentmentCurrency":"USD"},"recurringMetadata":{"frequency":{"unit":"Month","value":"1"},"amount":{"amount":"30","currencyCode":"USD"}},"scopes":["name","email","phoneNumber","billingAddress"]}';
$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 client = new WebStoreClient(payConfiguration);
var payload = "{'merchantId':'merchant_id','storeId':'amzn1.application-oa2-client.xxxxx','ledgerCurrency':'USD','webCheckoutDetails':{'checkoutResultReturnUrl':'https://example.com/review.html'},'chargePermissionType':'Recurring','chargePermissionId':'P01-1111111-1111111','productType':'PayAndShip','paymentDetails':{'paymentIntent':'AuthorizeWithCapture','chargeAmount':{'amount':'10','currencyCode':'USD'},'presentmentCurrency':'USD'},'recurringMetadata':{'frequency':{'unit':'Month','value':'1'},'amount':{'amount':'30','currencyCode':'USD'}},'scopes':['name','email','phoneNumber','billingAddress']}";
// generate the button signature
var signature = client.GenerateButtonSignature(payload);
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 = "{\"merchantId\":\"merchant_id\",\"storeId\":\"amzn1.application-oa2-client.xxxxxx\",\"ledgerCurrency\":\"USD\",\"webCheckoutDetails\":{\"checkoutResultReturnUrl\":\"https://example.com/result.html\"},\"chargePermissionType\":\"Recurring\",\"chargePermissionId\":\"P01-1111111-1111111\",\"productType\":\"PayAndShip\",\"paymentDetails\":{\"paymentIntent\":\"AuthorizeWithCapture\",\"chargeAmount\":{\"amount\":\"10\",\"currencyCode\": \"USD\"},\"presentmentCurrency\":\"USD\"},\"recurringMetadata\":{\"frequency\":{\"unit\":\"Month\",\"value\":\"1\"},\"amount\":{\"amount\":\"30\",\"currencyCode\":\"USD\"}},\"scopes\": [\"name\",\"email\",\"phoneNumber\",\"billingAddress\"]}";
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 = {
"merchantId": "merchant_id",
"webCheckoutDetails": {
"checkoutResultReturnUrl": "https://example.com/result.html"
},
"storeId": "amzn1.application-oa2-client.xxxxx",
"ledgerCurrency":"USD",
"chargePermissionType": "Recurring",
"chargePermissionId": "P01-1111111-1111111",
"productType": "PayAndShip",
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"chargeAmount": {
"amount": "10",
"currencyCode": "USD"
},
"presentmentCurrency":"USD"
},
"recurringMetadata": {
"frequency": {
"unit": "Month",
"value": "1"
},
"amount": {
"amount": "30",
"currencyCode": "USD"
}
},
"scopes": ["name", "email", "phoneNumber", "billingAddress"]
};
const signature = testPayClient.generateButtonSignature(payload);
オプション2: 署名リクエストガイドのステップ2と3に従って、手動で署名を作成します。
Step 4. amazon.Pay.bindUpgradeAction()を使用して、クリックイベントをHTML要素にバインドします
前の2つの手順の値を使用して、クリックイベントをHTML要素にバインドします。購入者がHTML要素をクリックすると、Amazon Payがホストするページにリダイレクトされてアップグレードが確認されます。
<script type="text/javascript" charset="utf-8">
amazon.Pay.bindUpgradeAction('#changeButton1', {
payloadJSON: 'payload', // string generated in step 2
signature: 'xxxx', // signature generated in step 3
publicKeyId: 'xxxxxxxxxx',
upgradeAction: 'recurringUpgrade'
});
</script>
Step 5. 決済を確認・完了する を実装します
購入者は、アップグレードを確認した後、checkoutResultReturnUrlにリダイレクトされます。その際、Recurring(継続支払い)のインテグレーションガイド中の決済を確認・完了するに従い、アップグレードを完了させる必要があります。