Login and Pay with Amazon Integration Guide

Transcription

Amazon ログイン & ペイメント
インテグレーションガイド
Amazon ログイン & ペイメントインテグレーションガイド
2
目次
概要 ....................................................................................... 4
重要な前提条件 ........................................................................... 4
Amazon ログイン & ペイメントの仕組み ..................................................... 4
重要な概念 ............................................................................... 5
購入者エクスペリエンスの概要 ............................................................... 9
インテグレーションの概要 .................................................................. 19
作業の開始 ................................................................................ 23
Eメールに表示されるデータの処理 ........................................................... 45
オーソリの同期モードと非同期モード ........................................................ 53
AddressBookウィジェットなしのインテグレーション ........................................... 55
スマートフォン用の折りたたみ可能ウィジェットの使用 ........................................ 56
複雑な支払いシナリオへの対応 .............................................................. 58
購入後に注文が変更された場合の支払いへの対応 .............................................. 60
支払い拒否への対応 ........................................................................ 63
システムとAmazon Paymentsの同期 ........................................................... 66
テスト環境とのインテグレーションのテスト .................................................. 73
エラーの処理 .............................................................................. 78
ボタンギャラリー .......................................................................... 82
スタイルのガイドライン .................................................................... 84
2
3
Amazon ログイン & ペイメント
インテグレーションガイド
Copyright© 2013-2015 Amazon.com, Inc. or its affiliates.
AMAZON、AMAZON PAYMENTS、およびAMAZON.COMは、Amazon.com, Inc.またはその関連会社の商標です。
その他のすべての商標は、各所有者の財産です。
最終更新日：2015年5月14日
3
4
概要
Amazon ログイン & ペイメントは、Amazon購入者がセラーのサイトで購入する場合のログインと支払いに利
用できる、安全で信頼性に優れた便利な方法です。購入者は、Amazon ログイン & ペイメントを使用して、
プロファイル情報(名前、Eメールアドレス、および郵便番号)を共有し、Amazonアカウントに保存している配
送先情報と支払い情報にアクセスして購入を完了します。
このガイドでは、Amazon ログイン & ペイメントと呼ばれるAPIベースのインテグレーションの詳細について
説明します。Amazon ログイン & ペイメントにより、セラーの支払い条件に応じた柔軟なカスタマイズが可
能になります。
注：Amazon ログイン & ペイメントサービスは、Webブラウザー内のみでの使用を目的に設計および
開発されています。このサービスは、(iOS、Android、RIM、Windowsのオペレーティングシステムを
含むがこれに限定されない)ネイティブアプリケーションでは使用できません。Amazon ログイン &
ペイメントは、ネイティブアプリケーション内でこのサービスを実装しているAmazonのサービスのい
かなるユーザーの支払いアカウントを一時的に停止する権利を留保します。
重要な前提条件
Amazon ログイン & ペイメントサービスの前提条件は次のとおりです。
• アプリケーション開発用のHTML、JavaScript、XMLの使用経験。
• WebサービスAPIの使用経験。
• セラーセントラルポータルに精通していること。
• セラーIDは(別名マーチャントID)はAmazon ログイン & ペイメントのセラーアカウントで
す。 Amazon ログイン & ペイメントセラーアカウントは、Amazon ログイン & ペイメントサービス
を設定しておく必要があります。Amazon ログイン & ペイメントのセラーアカウントを作成または既
存のセラーアカウントをAmazon ログイン & ペイメント用に設定するには、Amazon ログイン & ペイ
メント Webサイト(https://payments.amazon.co.jp/contactsales)からAmazon ログイン & ペイメ
ントの導入に関するお問い合わせから登録します。
• AmazonマーケットプレイスWebサービス(Amazon MWS)のアクセスキーと秘密キーでアクセスします。こ
れらのキーを取得するには、Amazon MWSに登録するか、開発者のキーを使用してセラーの代わりに開
発者が呼び出しできるように認証します。詳しくは、Amazon MWS開発者ガイドの「Amazon MWS利用へ
の登録」を参照してください。
•
WebサイトをAmazonログインアプリケーションコンソールのアプリケーションとして登録します。詳し
くは、「 Amazonログインスタートガイド（英語資料：Login with Amazon Getting Started Guide fo
r Websitesを参照）」を参照してください。クライアント識別子(クライアントID)は、Webサイトを登
録すると設定されます。この識別子はインテグレーションに必要になります。
• 購入者のブラウザーでJavaScriptを有効にする必要があります。
• 購入者のブラウザーでCookieを有効にする必要があります。
Amazon ログイン & ペイメントの仕組み
Amazon ログイン & ペイメントは、既存のWebサイトに直接埋め込まれ、購入者とAmazon ログイン & ペイメ
ントとのすべてのやり取りは埋め込みウィジェットで行われるため、購入者はセラーのサイトから移動する
必要がありません。購入者は、Amazonログイン認証を使用して、配送先住所と支払方法を選択してから注文
を確定できます。
Amazon ログイン & ペイメントと購入者のすべてのやり取りは、埋め込みウィジェットで行われるため、購
入者はセラーのサイトから移動する必要がありません。選択したインテグレーションボタンのオプションに
応じて、購入者はセラーのサイトでチェックアウトプロセスを開始する前、開始中、または開始した後に認
証できます。購入者は、Amazonログインを使用してセラーのサイトにサインインするか、ゲスト用のチェッ
クアウトプロセスを使用できます。どちらの場合も、購入者はAmazonアカウントの配送先情報と支払い情報
を使用して、チェックアウトプロセスを完了できます。
4
5
重要な概念
Amazon ログイン & ペイメントのエンドツーエンドのエクスペリエンスは、購入者のチェックアウトとセラ
ーへの支払い処理を簡単で安全にすることを目的としています。インテグレーションを開始する前に、この
サービスに関するいくつかの重要な概念を理解しておいてください。
ボタンウィジェット
Amazon ログイン & ペイメントとのインテグレーションを開始するには、購入者のログインとチェックアウ
ト用のボタンウィジェットをセラーのサイトに埋め込みます。選択したボタンウィジェットに応じて、購入
者がセラーのサイトでチェックアウトプロセスを開始する前、開始中、または開始した後に、名前、Eメー
ルアドレス、郵便番号などの購入者情報を取得できます。次の表では、ボタンウィジェットのオプションに
ついて詳しく説明します。
ボタン
ユースケース
Amazonログイン
このボタンを使うことで購入者はサイトにログインでき、Amazonアカウントを利用し
て支払えます。購入者は注文処理を開始する前、開始中、または、開始した後にログ
インすることができます。購入者はAmazonアカウントに登録されているプロファイル
情報(名前、Eメールアドレス、郵便番号)、配送先住所、支払情報をサイトでの購入を
完了するために共有できます。
Login with Amazon
購入者がAmazonアカウント認証でログインした後:
•
購入者の名前、Eメールアドレスを含むAmazonプロファイルの情報を受信しま
す。購入者の購入エクスペリエンスのカスタマイズや参照履歴の追跡を行うた
めに、この情報を利用することができます。
•
購入者はログインしてから55分間は、Amazonアカウントに登録されている配送
と支払情報をアクセスしたサイト上にあるペイメントウィジェットで使用する
ことができます。55分経てば認証されたトークンの有効期限が切れます、購入
者にもう一度ログイン要求する必要があります。
•
購入者が配送先住所を選択したとき、クリックしてすぐに完全な配送先住所に
アクセスできます。
このボタンを以下の例のように利用されるべきです:
•
購入者は購入履歴の確認やサイト上の特別なお得な情報が必要な場合です。購
入者がログインしてから1時間内で、Amazonに登録されている配送先と支払情報
を使ってたくさんの商品をたったの2クリックで購入することができます。
•
購入者がチェックアウト（注文する）ボタンをクリックし、注文処理中にAmazo
nログインを使って認証し、それからAmazonアカウントに登録されている配送先
と支払情報にアクセスして2クリックで注文処理を完了します。
•
購入者が注文履歴にアクセスや商品の追跡ができるように、注文処理の最後に
サイトへ登録するオプションを与えたい場合です。
購入者はサイトにAmazonアカウントで初回ログインした場合は同意画面が表示されま
す。同意画面は次の購入者情報をセラーのサイトで共有する権限を要求します。:
•
購入者の名前、Eメールアドレス、郵便番号
•
購入者の注文前に選択された配送先住所
購入者が情報を共有しないと決めた場合は、認証トークンはaccess_deniedのレスポン
スメッセージを投げ、購入者はAmazonアカウントからの支払と配送先の情報を登録する
ことができません。
5
Amazonペイメント(ゲスト注文)
Pay with Amazon (guest checkout)
6
このボタンを利用することで、処理を完了する前に個人情報を共有せずに購入者がAmaz
onアカウントに登録されている配送先と支払情報を使いゲストのように処理を完了でき
ます。
購入者がAmazonアカウントから配送先住所にアクセスするためにサインインし、消費
税と配送料を計算する目的のために市区町村、国、郵便番号を受け取れます。
Amazonアカウントを使用してチェックアウト処理を完了させた後に、購入者の名前、E
メールアドレス、配送先住所を受け取れます。購入者がチェックアウト処理を完了しな
かった場合は、顧客情報を受け取れません。
Amazonを使用してサインインするときは、購入者に同意画面が表示されません。
Amazonペイメント（完全な配送先住
所にアクセス）
Pay with Amazon (access to full sh
ipping address)
このボタンを利用することで、処理が完了する前でプロファイル情報と完全な配送先情
報を共有している間は、購入者がAmazonアカウントでセラーのサイトにログインと支払
ができます。
購入者がAmazonでログインした後:
•
購入者のAmazonプロファイルから名前とEメールアドレスを含む情報を受け取れ
ます。購入者の購入体験や閲覧履歴の追跡をカスタマイズするためにこの情報
を利用できます。
•
購入者はログインしてから55分間は、Amazonアカウントに登録されている配送
と支払情報をアクセスしたサイト上にあるペイメントウィジェットで使用する
ことができます。55分経てば認証されたトークンの有効期限が切れ、購入者に
もう一度ログイン要求する必要があります。
•
購入者が配送先住所を選択したとき、クリックしてすぐに完全な配送先住所に
アクセスできます。
このボタンを以下の例のように利用されるべきです:
•
購入者がカートページから支払処理を開始、Amazonアカウントに登録されてい
る配送先と支払情報にアクセスしたい場合
•
フルフィルメントのための完全な配送先住所や処理の完了前に消費税計算する
必要がある場合
購入者はサイトにAmazonログインで初回サインインした場合は同意画面が表示されま
す。同意画面は次の購入者情報を共有する権限を要求します。:
•
購入者の名前、Eメールアドレス、郵便番号
•
購入者の注文前に選択された配送先住所
アクセストークン
ユーザーがサイトにログインすると、オーソリサーバーによってアクセストークンが付与されます。アクセ
ストークンは、クライアント、ユーザー、およびアクセススコープに固有です。クライアントは、アクセス
トークンを使用して、購入者のプロファイルデータを取得し、配送先情報と支払い情報にアクセスできるよ
うにする必要があります。
支払いオブジェクト
支払いオブジェクトは、Amazon ログイン & ペイメントの支払いプロセスをサポートする請求ブロックで
す。このガイドでは、次のオブジェクトについて説明します。
• Order Referenceオブジェクト – このオブジェクトは、購入者の支払い処理に必要な重要な属性の記録
です。配送先住所や支払い方法など、これらの属性の一部はチェックアウトプロセス中に購入者が指定
し、合計金額や注文IDなど、注文に関する情報はセラーが設定します。
•
Authorizationオブジェクト – このオブジェクトは、選択した支払い方法で決済が可能かどうかを表
し、キャプチャーリクエストを使用して、今後の回収のために資金を取り置きます。
• Captureオブジェクト – このオブジェクトは、購入者の支払い方法からセラーのAmazon ペイメントセラー
アカウントへの資金の動きを表します。
• Refundオブジェクト – このオブジェクトは、返金が発生した場合に、以前Caputureされた資金を購入
者のアカウントに戻す動きを表します。
6
7
これらの各オブジェクトは、一意の識別子によって識別され、それぞれステータスが割り当てられます。
これらのオブジェクトの使用については、このガイドの次の章で詳しく説明します。
ウィジェット
ウィジェットとは、セラーのサイトに埋め込み可能なAmazonホストコントロールです。ウィジェットによ
り、購入者はセラーのサイトへのログイン、Amazonクレデンシャルを使用した認証、Amazonアカウントに
保存している住所と支払い方法の表示、購入で使用する住所と支払い方法の選択が可能になります。選択
した住所と支払い方法の情報は、Order Referenceオブジェクトに保存されます。
Amazon ログイン & ペイメントとのインテグレーションでは、次の4つのウィジェットを使用できます。
• 「Amazonアカウントでログイン」ボタンウィジェット：このウィジェットでは、チェックアウトプロ
セスの開始前、開始中、または開始後に、購入者がAmazonアカウントを使用して、セラーのサイトにログ
インできます。このウィジェットは、セラーのサイトのホームページなどの目立つ場所に配置することを
お勧めします。次のイメージは、「Amazonアカウントでログイン」ボタンウィジェットを示しています。
• 「Amazonアカウントでお支払い」ボタンウィジェット：このウィジェットでは、購入者が支払いにA
mazon ペイメントを選択し、Amazonで認証できます。このウィジェットは、ショッピングカートや製品
の詳細ページなど、通常は購入者がチェックアウトプロセスを開始するページに配置します。次のイメ
ージは、「Amazonアカウントでお支払い」ボタンウィジェットを示しています。
• AddressBookウィジェット：AddressBookウィジェットには、購入者のAmazonアカウントに保存している
住所が表示されます。このウィジェットにより、購入者から住所を収集するのに使用する手入力のフォ
ームが不要になります。次のイメージは、AddressBookウィジェットを示しています。
7
8
• Walletウィジェット：Walletウィジェットには、購入者のAmazonアカウントに保存している支払い方法
が表示されます。このウィジェットにより、購入者から支払い方法の情報を収集するのに使用する手入
力のフォームが不要になります。次のイメージは、Walletウィジェットを示しています。
アプリケーションプログラミングインタフェース(API)
Amazon ペイメントとセラーの内部システム間で情報と命令を交換するには、Off-Amazon Payments API
セクションのオペレーションを呼び出します。たとえば、購入者プロファイル情報の取得、Amazonへの
購入者請求のリクエスト、返金、購入者の配送先情報の取得、注文内容のキャンセルには、これらのオ
ペレーションを呼び出します。詳しくは、Off-Amazon Payments APIセクションリファレンスを参照して
ください。
インスタントペイメント通知(IPN)
Amazonでは、支払いリクエスト(Authorize、Capture、およびRefundリクエスト)を非同期で処理します。
Amazonがリクエストを処理すると、インスタントペイメント通知(IPN)と呼ばれる通知がセラーに送信さ
れ、リクエストの最終ステータスが通知されます。
また、支払いオブジェクトのステータスは、セラーによって送信されたリクエストまたは内部のAmazonビジ
ネスルールにより変更される場合があります。支払いオブジェクトのステータスが変更されると、Amazonか
らセラーにIPNが送信され、セラーは自社システムとAmazon ペイメントとの同期を保つことができます。詳
しくは、「システムとAmazon ペイメントの同期」を参照してください。
8
9
購入者エクスペリエンスの概要
Amazon ログイン & ペイメントでは、数回クリックするだけで、購入者がセラーのサイトで購入を完了
できます。以下は、Amazon ログイン & ペイメントでの購入者エクスペリエンスの例です。
• Amazon ログインでの購入者エクスペリエンス
• Amazon ペイメントでの購入者エクスペリエンス
Amazon ログインでの購入者エクスペリエンス
1. 購入者は「チェックアウト」をクリックし、チェックアウトプロセスを開始します。
9
10
2. 購入者は「Amazonアカウントでログイン(下図：Login with Amazon)」ボタンをクリックし、ログイン
して支払います。
Login and Pay with Amazonインテグレーションガイド
10
11
3. 購入者はAmazonのユーザー名とパスワードを使用してサインインします。
11
12
4. 購入者は購入者情報をセラーと共有することに同意します(セラーのサイトの初回ログイン時にのみ必
要)。
12
13
5. 購入者はAddressBookウィジェットから配送先住所、Walletウィジェットから支払い方法を選択し、注
文します。
13
14
Amazon ペイメントでの購入者エクスペリエンス
1. 購入者は「Amazonアカウントでお支払い(下図：Pay with Amazon)」ボタンをクリックし、チェッ
クアウトプロセスを開始します。
14
15
2. 購入者はAmazonのユーザー名とパスワードを使用してサインインします。
15
16
3. 購入者が購入者情報をセラーと共有することに同意すると(セラーのサイトの初回ログイン時にの
み必要)、セラーは購入者の完全な配送先住所を取得します。Amazonアカウントでお支払いボタン
のゲスト用チェックアウトを使用している場合、購入者にはこの画面は表示されません。
16
17
4. 購入者がAddressBookウィジェットから配送先住所、Walletウィジェットから支払い方法を選択
し、注文します。
17
18
5. セラーから購入者に注文確認が送信されます。
上記のシナリオでは、購入者はチェックアウトプロセスを開始し、「Amazonアカウントでログイン」ボタ
ンまたは「Amazonアカウントでお支払い」ボタンをクリックします。次に、購入者はAmazonアカウントに
サインインして、プロファイル情報(名前とEメールアドレス)を共有し、支払い情報と配送先情報にアクセ
スして処理を完了します。これらのシナリオでは、購入者はプロファイル情報を共有しており、セラーは
セラーのWebサイトにアカウントを作成できます。Amazon ログイン & ペイメントとのインテグレーション
では、「Amazonアカウントでお支払い」ボタンをゲスト用のチェックアウトとして使用し、購入者がログ
インすることなく、セラーのサイトで支払いすることもできます。このボタンは、チェックアウトプロセ
スの開始前、開始中、または開始後に購入者がアクセスするセラーのWebサイトの任意のページに追加でき
ます。購入者がAmazon ログインですでにログインしている場合は、「Amazonアカウントでお支払い」ボ
タンをチェックアウトボタンとして使用できます。購入者は再度サインインする必要はありません。
セラーのサイトで「Amazonアカウントでログイン」ボタンを使用するメリットについて詳しくは、「ボタ
ンウィジェット」を参照してください。
「Amazonアカウントでログイン」ボタンの配置のサンプルイメージと使用については、「スタイルのガイ
ドライン」を参照してください。
18
19
インテグレーションの概要
以下は、セラーのWebサイトにAmazon ペイメントを設定し、簡単なシナリオの支払いを回収するにあたって
の一般的なプロセスの概要です。各ステップは、購入の有効化と支払い処理の2つの部分に分けられます。こ
れらのステップについて詳しくは、このガイドで後述します。
Amazon ログイン & ペイメントでの購入の有効化
1. 購入者がチェックアウトフローを開始するページ(アカウントの作成ページ、ショッピングカート、製品
の詳細ページなど)に「Amazonアカウントでログイン」ボタンまたは「Amazonアカウントでお支払い」ボ
タンを追加します。このボタンを使って、購入者はAmazonで認証できます。
2. 購入者が認証に成功したら、配送先住所を収集するページにAmazon AddressBookウィジェット、支払い
情報を収集するページにWalletウィジェットを表示します。
3. GetOrderReferenceDetailsオペレーションを呼び出して配送先住所を取得し、税金と配送費を計算しま
す。配送費と税金の金額を購入者に表示します。
4. オプションで、読み取り専用バージョンのAddressBookウィジェットとWalletウィジェットをセラーの
注文内容確認ページに表示します。
5. SetOrderReferenceDetailsオペレーションを呼び出し、注文合計とその他のオプションの情報をAmazon
に通知します。
6. 購入者が注文したら、ConfirmOrderReferenceオペレーションを呼び出し、注文を確定してAmazonに通
知します。
7. 「Amazonアカウントでお支払い」ボタンをゲスト用のチェックアウトオプションとして使用している場
合は、GetOrderReferenceDetailsオペレーションを呼び出し、Amazonから完全な配送先住所を取得しま
す。
8. 注文のお礼を記載した注文確認のメールを購入者に送信します。「支払いがオーソリ処理された」こと
を伝えるEメールもAmazonから購入者に送信されます。
注：「支払いがオーソリ処理された」ことを伝えるEメールは、セラーが注文内容を確定してA
mazonに通知すると、購入者に送信されます。このEメールで、Amazon ペイメントを使用して
購入の支払いがオーソリ処理されたことを購入者に通知します。このEメールは、注文時点ま
たは注文後にセラーが送信するAuthorizeリクエストとは関係ありません。
19
20
次のイメージは、Amazon ログインとAmazon ペイメントを使用して購入を有効化する方法を示しています。
20
21
次のイメージは、Amazon ペイメントを使用して購入を有効化する方法を示しています。
支払いの処理
1. Authorizeオペレーションを呼び出し、購入者の支払いをオーソリ処理するようにAmazonにリクエス
トします。
2. オーソリインスタントペイメント通知(IPN)でオーソリリクエストの処理ステータスを確認します。
21
22
注：Amazonでは、Authorizeオペレーションに同期モードと非同期モードの両方を用意しています。
同期モードでは、OpenまたはDeclinedの即時処理ステータスがセラーに通知されます。非同期モ
ードでは、オーソリオブジェクトで最初にPendingステータスが通知されます。非同期モード処
理が完了すると、インスタントペイメント通知(IPN)でAmazonからセラーに最終的な処理ステー
タスが通知されます。
3.
4.
5.
6.
7.
非同期モードを使用している場合は、Amazonから最終的な処理ステータスが通知されるまで、セ
ラーのサイトで購入者が注文確認を長時間待たされることがないようにしてください。注文を確
定してAmazonに通知したら、ただちに注文確認ページを購入者に表示するようにしてください
(上記のステップ6)。
注文を出荷し、Captureオペレーションを呼び出して支払いをキャプチャーします。
キャプチャーIPNでキャプチャーリクエストの処理ステータスを確認します。キャプチャーが正常に処理さ
れると、Amazonから購入者に「請求通知」のEメールが送信されます。
必要な注文金額を回収したら、CloseOrderReferenceオペレーションを呼び出し、Order Referenceオブジ
ェクトをClosedとマークします。Amazonでは、この情報を使用して、この注文の支払いが完了した旨を購
入者に通知します。
返金が必要な場合は、Refundオペレーションを呼び出すことで返金できます。
返金IPNで返金リクエストの処理ステータスを確認します。返金が正常に処理されると、Amazonから購入者
に「返金通知」のEメールが送信されます。
次のイメージは、支払いの処理方法を示しています。
22
23
作業の開始
作業の開始手順
注：このガイドで説明する手順とサンプルコードを利用すれば、Amazon ログイン & ペイメントウ
ィジェットをセラーのWebサイトに埋め込み、Amazon ログイン & ペイメントテストモードでAPI呼
び出しの実行を準備できます。このテスト環境では、エンドツーエンドのインテグレーションをす
ぐに開始できます。本番環境への切り替えの準備ができるまで、Amazon ログイン & ペイメント購
入者向けの要素を公開する必要はありません。Amazon ログイン & ペイメントテストモードについ
て詳しくは、「テスト環境とのインテグレーションのテスト」を参照してください。テスト環境か
ら本番環境に切り替えるには、次のように変更します。
パラメーター
テスト環境の値
本稼働環境の値
Amazon MWS
endpoint
https://mws.amazonservices.jp/OffAmazonPaym
https://mws.amazonservices.jp/OffAmazonP
ents_Sandbox/2013-01-01/
ayments/2013-01-01/
Widgets.js
https://origin-na.ssl-images-amazon.com/imag
https://static-fe.payments-amazon.com/OffAm
URL
es/G/09/EP/offAmazonPayments/sandbox/prod/lp
azonPayments/jp/lpa/js/Widgets.js
a/js/Widgets.js
Profile API
https://api-sandbox.amazon.co.jp/
https://api.amazon.co.jp/
sns.amazonaws.com
sns.amazonaws.com
endpoint
certCN
セラーのWebサイトでAmazon ログイン & ペイメントを構成する
Amazon ログイン & ペイメントとの連携により、購入者体験が向上します。Login with Amazonでは、使用
するボタンオプション(Amazon ログインまたはAmazon ペイメント)に関係なく、いくつかの基本構成を実
行する必要があります。Amazon ログイン構成の設定には、「Amazon ログイン & ペイメント」セラーセン
トラルページからアクセスします。
アプリケーションコンソールで、「新規アプリケーションの登録」ボタンをクリックします。
アプリケーションの登録フォームが表示されます。
アプリケーション詳細ページで、セラーのWebサイトに関する基本的な詳細を追加します。
これらの詳細は、セラーのWebサイトとモバイルアプリ(利用可能な場合)に使用されます。
a. 表示用名前ユーザーがセラーのWebサイトと情報を共有することに同意した場合、同意画面
に表示される名前です。この名前は、Android、iOS、Webサイトのバージョンのアプリケーション
に適用されます。
b. 説明
Amazonログインユーザー用のセラーのWebサイトの説明です。
c. 個人情報保護方針のURL プライバシーURLは、セラーの会社のプライバシーポリシーの場所です。
同意画面にも表示されます。このリンクは、セラーのアプリケーションの初回のログイン時にユーザ
ーに表示されます(例：http:// www.example.com/privacy.html)。
d. ロゴイメージファイルこのロゴは、Amazon上でのセラーのビジネスまたはWebサイトを表します。ロゴ
は、150x150ピクセルのイメージで表示されます。異なるサイズのファイルをアップロードした場合は、この
サイズに合わせてサイズが変更されます。終了したら、「保存」をクリックして変更内容を保存します。
セラーのアプリケーションにWebサイトを追加する
1. アプリケーション画面で「ウェブサイト設定」をクリックします。クライアントIDとクライアントシ
ークレットの値が自動的に割り当てられます。クライアントIDでは、セラーのWebサイトを識別し、ク
ライアントシークレットは、セラーのWebサイトが本物であることを確認するために使用されます。パ
23
24
スワードなどのクライアントシークレットは機密情報として扱います。クライアントシークレットを
表示するには、「Secretを表示する」をクリックします。
2. 許可済みJavaScriptオリジンまたは許可済み戻りURLをアプリケーションに追加し、「編集する」をク
リックします。
注：WebサイトでAmazon ログインを使用するには、許可済みJavaScriptオリジン(購入者のポッ
プアップログイン操作)、または許可済み戻りURL(購入者のリダイレクトログイン画面操作)のい
ずれかを指定する必要があります。Amazon ペイメントを使用している場合は、いずれかのオプ
ションを指定する必要があります。
a. オリジンとは、プロトコル、ドメイン名、およびポートを組み合わせたものです(例：https://w
ww.example.com:8443)。許可済みオリジンでは、HTTPSプロトコルを使用する必要があります。
標準ポート(ポート443)を使用している場合は、ドメイン名のみを含める必要があります(例：ht
tps://www.example.com)。
ここにセラーのドメインを追加すると、ログインプロセス中にJavaScript用SDKがセラーのWebサイト
と直接通信できます。Webブラウザーは、スクリプトで明確に許可していないかぎり、通常はスクリプ
ト間のクロスオリジン通信をブロックします。
複数のオリジンを追加するには、「さらに追加する」をクリックします。
b. セラーのWebサイトがLogin with AmazonオーソリサービスにHTTPS呼び出しを実行しており、
応答にredirect_uriを指定している場合は、これらのリダイレクトURIを許可済み戻りURLに
追加します。戻りURLには、プロトコル、ドメイン、パス、クエリー文字列が含まれます
（例：https://www.example.com/login.php）
複数の戻りURIを追加するには、「さらに追加する」をクリックします。
3.「保存する」をクリックし、Amazon ログインの構成を終了します。
24
25
Amazon ログイン & ペイメントウィジェットを使用するための準備
埋め込みウィジェットをセラーのサイトに適切に表示するには、ハンドラーをonAmazonLoginReadyコ
ールバックに指定し、Amazon ログイン & ペイメント JavaScriptファイルの参照(Widgets.js)をWeb
ページのソースコードに追加する必要があります。この操作は、Amazon ログイン & ペイメントウィ
ジェットを表示するページから実行する必要があります。
onAmazonLoginReadyコールバックを定義し、Amazon ログイン & ペイメント JavaScriptファイルの参照を
追加するには、次のサンプルコードに示すように、コードを数行追加します。Amazon ペイメントではベス
トプラクティスとして、ボタン、アドレス、およびWalletの各ウィジェットが表示されるセラーのWebペー
ジのheadセクションに、このコードを配置することを推奨しています。またローカルコピーし、Amazon提供
のJavaScriptの内容を変更すると、ウィジェットの表示や機能のエラーなど予期せぬ結果が発生する場合が
あるため、このような操作は行わないようにしてください。
<head>
<script type='text/javascript'>
window.onAmazonLoginReady = function() {
amazon.Login.setClientId('YOUR_CLIENT_ID_HERE');
};
</script>
<script type='text/javascript'
src='https://static-na.payments-amazon.com/OffAmazonPayments/us/js/Widgets.js'>
</script>
</head>
Amazon ログイン & ペイメント JavaScriptファイルの参照をソースコードに追加すると、Amazon ロ
グイン & ペイメントウィジェットの埋め込みを開始できます。
ベストプラクティス
実行する前にデータをエンコード
データのセキュリティはAmazon ペイメントの一番の関心事です、HTML、JavaScriptのように任意の形
式で出力する前に、私たちから受け取る多くのデータをエンコードすることを提案します。また、URL
出力エンコーディングの中で悪意のあるスクリプトや他から挿入された実行可能なスクリプトを実行
できないように保証します。
WSAPI、Open Web Application Security Project (OWASP) APIは、無償でオープンソースのWebアプリ
ケーションセキュリティコントロールライブラリを提供しています。それらは、リスクが低いアプリ
ケーションをより簡単に作れます。この標準的なライブラリを出力エンコードに利用ください。
次の例はいくつかの最も一般的なタイプのデータエンコード方法を表しています:
•
HTML:
String safe = ESAPI.encoder().encodeForHTML( request.getParameter( "input" ) );
•
幅、名前、値のようなHTML属性の値:
String safe = ESAPI.encoder().encodeForHTMLAttribute( request.getParameter( "input" ) );
•
URLパラメーターの値:
String safe = ESAPI.encoder().encodeForURL( request.getParameter( "input" ) );
•
JavaScriptデータの値
String safe = ESAPI.encoder().encodeForJavaScript( request.getParameter( "input" ) );
非同期JavaScript
Amazon ペイメントはJavaScriptをWebページに速やかに提供するために非同期ローディングを限定的に
サポートします。非同期ローディングを使う選択した場合は、Amazon ペイメントのサポートしている
唯一の方法はスクリプトタグ内の非同期属性です。
Amazon ペイメントボタンを非同期でロードするには:
25
1.
2.
3.
4.
26
window.onAmazonPaymentsReady関数を定義
この関数の中にOffAmazonPaymentsに関連する多くのJavaScriptを移動
この定義を以下のWidgets.jsスクリプトタグに追加
Widgets.jsスクリプトタグに非同期属性を追加
タイミングの問題を防ぐために、上記の方法でスクリプトタグを配置する必要があります。
例:
<script>
window.onAmazonPaymentsReady = function(){
OffAmazonPayments.Button('LoginWithAmazon', '<Your-Seller-ID>', {
...
};
</script>
<script async type='text/javascript'
src='https://static-na.payments-amazon.com/OffAmazonPayments/us/sandbox/js/Widgets.js'>
</script>
注：テスト環境での例です。本稼働環境のURLに応じてコードを変更してください。
詳しい非同期属性のスクリプトタグの情報は、Mozilla Developer Network script tag Summaryを参照
してください。(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
ステップ1 - 購入者の認証用ボタンウィジェットの追加
最初に埋め込む必要がある購入者向けのウィジェットは、Amazon ログイン & ペイメントボタンウィジェ
ットです。このウィジェットには、注文の支払いにAmazonアカウントを使用できることを購入者に通知す
るボタンが表示されます。
必要なJavaScriptコードをセラーのWebサイトのheadセクションに追加している場合(「作業の開始」セクシ
ョンを参照)、次のコードを追加することで、選択したボタンを埋め込むことができます。
• Amazon ログイン & ペイメントボタン：
<div id="AmazonPayButton"/>
<script type="text/javascript">
var authRequest;
OffAmazonPayments.Button("AmazonPayButton", "YOUR_SELLER_ID_HERE", {
type: "ENTER_TYPE_PARAMETER",
color: "ENTER_COLOR_PARAMETER",
size: "ENTER_SIZE_PARAMETER",
authorization: function() {
loginOptions =
{scope: "ENTER_SCOPES", popup: ENTER_POPUP_PARAMETER};
authRequest = amazon.Login.authorize (loginOptions,
"YOUR_REDIRECT_URL_HERE");
},
onError: function(error) {
// your error handling code
}
});
</script>
上記のサンプルコードは、セラーのWebページ内でボタンの表示に使用する部分を定義します。このコー
ドは、ボタンを表示したい場所に配置するようにしてください。登録時に通知されたセラーIDで「YOUR_S
ELLER_ID_HERE」のテキストを更新します。セラーIDがわからない場合は、セラーセントラルにログイン
26
27
し、「設定」タブの「インテグレーション設定」セクションにアクセスして、セラーIDを表示します。ま
た、ENTER_TYPE_PARAMETERを更新し、選択したボタンイメージを表示します。
ボタンのcolorとsizeのパラメーターを任意で指定することもできます。次の表は、サポートされて
いるプロパティーと、プロパティーが指定されていない場合デフォルト設定の一覧です。
パラメーター
type
LwA – Amazonアカウントでログインボタンを指定
typeを指定していなかった場合のデフォルトボタン
color
•
•
•
Gold
DarkGray
LightGray
デフォルト: Gold
size
•
•
•
•
small (156px x 32px)
medium (195px x 46px)
large (312px x 64px)
x-large (390px x 92px)
デフォルト: medium
パラメーター
type
PwA – Amazonアカウントでお支払いボタンを指定
color
•
•
•
Gold
DarkGray
LightGray
デフォルト: Gold
size
•
•
•
•
small (148px x 30px)
medium (200px x 45px)
large (296px x 60px)
x-large (400px x 90px)
デフォルト: medium
ENTER_SCOPES、ENTER_POPUP_PARAMETER、およびYOUR_REDIRECT_URL_HEREのテキストも更新してください。
ENTER_SCOPESパラメーターの値では、セラーがアクセスできる購入者の情報を指定します。購入者が情報の
共有を許可できるように、scopeパラメーターの値に基づいて、適切な同意画面が購入者に表示されま
す。
ENTER_POPUP_PARAMETERでは、購入者に認証用のポップアップウィンドウを表示するかどうか、または購入者
をAmazonの認証ページにリダイレクトするかどうかを指定します。安全でないページやスマートフォン用
に最適化された操作用にボタンウィジェットをホストしている場合は、リダイレクトの使用をお勧めしま
す。
YOUR_REDIRECT_URLは、ボタンを押して認証が成功した後に、購入者がリダイレクトされるページを指すパラ
メーターです。たとえば、認証の成功後に、セラーのチェックアウトパイプラインの次のページに購入者
をリダイレクトし、配送先住所または支払い方法の詳細を収集することができます。
scopeパラメーターとpopupパラメーターに指定できる値のリストについては、次の表を参照してください。
27
パラメーター名
28
値
• profile postal_code payments:widget payments:shipping_address
scope
アクセスしたい購入者プロファイル情報を指定（例：名前、Eメ
ールアドレス、郵便番号）し、すぐ後にサインインしてAmazonAd
dressBookウィジェットで選択した完全な配送先住所の値
•
paymenta:widget payments:shipping_address
購入者プロファイル情報にアクセスしたくない場合に指定する。しかしなが
ら、AmazonAddressBookウィジェットで選択した完全な配送先住所にアクセ
スしたい場合の値
•
paymenta:widget
サインインしてすぐに購入者プロファイル情報にアクセスしたくない場合に
指定する。Amazonから購入が承認された後に完全な配送先住所が参照でき
る。このscopeでは購入者に同意画面を表示しない。
payments:shipping_address は、購入者の杯先住所へのアクセスを
提供する。完全な配送先住所を検索するために、getorderReference
Details APIの呼び出しが必要です。詳しい情報はOff-Amazon Payme
nts APIセクションリファンレンスを参照ください。
popup
•
true
– ポップアップダイアログにAmazon認証画面を提供しま
す。デスクトップ用ボタンウィジェットはセキュアページ上で
提供されることを推奨されています。この追加の要求は有効な
SSL認証されたHTTPSページにボタンを属することを認識してく
ださい。
•
false
- 購入者の同じブラウザのウィンドウの中でAmazonページ
がリダイレクトします。モバイルデバイス、また、非セキュア
ページ上でボタンウィジェットをレンダリングする場合に推奨
されます。リダイレクトURLはHTTPSプロトコルを使い、有効な
SSL認証も持つ必要があることを認識してください。
デフォルト: popup: true
前述の例のコードを追加して、ボタンをクリックすると、Amazon ペイメントの認証ウィンドウが開き、
購入者はAmazonアカウントのEメールアドレスとパスワードを入力するように求められます。popupパラメ
ーターをfalseに設定している場合(popup: false)に、ボタンをクリックすると、購入者は、同じブラウザ
ーウィンドウ内でAmazon認証ページにリダイレクトされます。
Amazonでは、onErrorハンドラーをコードに実装することも推奨しています。前述の例では、onErrorコードは
任意ですが、インテグレーションの問題が発生した場合に、トラブルシューティングの手間を大幅に軽減で
きます。詳しくは、「テスト環境とのインテグレーションのテスト」を参照してください。
ボタンを埋め込み、popupパラメーターをtrue (popup:true)に設定してJavaScriptコードを追加すると、ポ
ップアップウィンドウが表示され、購入者はセラーのWebサイトを離れることなく認証できます。
28
29
上記のスクリーンショットからもわかるように、セラーの会社のロゴを認証ウィンドウに追加することも
できます。この操作は、セラーセントラルの「設定」タブの「インテグレーション設定」ページから実行
できます。
ユーザーがログインしたら、「ログアウト」オプション(ハイパーリングの場合が多い)をセラーのWeb
サイトに追加してください。ログアウトオプションでは、キャッシュされたトークンを削除し、ユーザ
ープロファイル情報(名前など)をセラーのWebサイトから削除します。ログアウトすると、セラーのWeb
サイトにログインボタンを再度表示できます。
JavaScript用のLogin with Amazon SDKを使用している場合は、amazon.Login.logoutメソッドを呼び出し、
キャッシュされたトークンを削除できます。例：
document.getElementById('Logout').onclick = function() {
amazon.Login.logout();
};
</script>
これ以降のamazon.Login.authorizeの呼び出しでは、ログイン画面がデフォルトで表示されます。
ステップ2 - プロファイル情報の取得(任意)
最終的に、ボタンウィジェットによって返されるアクセストークンを使用して、Amazonからユーザーのプ
ロファイル情報を取得できます。ユーザーがサイトにログインすると、オーソリサーバーによってアクセ
ストークンが付与されます。アクセストークンは、クライアント、ユーザー、およびアクセススコープに
固有です。クライアントは、アクセストークンを使用して購入者のプロファイルデータを取得する必要が
あります。サーバー側のアプリケーションでは、/handle_login.phpへのリクエストを処理し、アクセストー
クンとプロファイルREST APIを使用して、プロファイル情報を取得します。
29
30
例
PHPの例
$c = curl_init('https://api.amazon.co.jp/auth/o2/tokeninfo?access_token='
. urlencode($_REQUEST['access_token']));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
$r = curl_exec($c);
curl_close($c);
$d = json_decode($r);
if ($d->aud != 'YOUR-CLIENT-ID') {
// the access token does not belong to us
header('HTTP/1.1 404 Not Found');
echo 'Page not found';
exit;
}
// exchange the access token for user profile
$c = curl_init('https://api.amazon.jp/user/profile');
curl_setopt($c, CURLOPT_HTTPHEADER, array('Authorization: bearer '
. $_REQUEST['access_token']));
curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
$r = curl_exec($c);
curl_close($c);
$d = json_decode($r);
echo sprintf('%s %s %s', $d->name, $d->email, $d->user_id);
Javaの例
このサンプルコードを使用するには、JacksonとHttpComponentsのライブラリをダウンロードする必要があり
ます。
import com.fasterxml.jackson.core.type.TypeReference; import co
m.fasterxml.jackson.databind.ObjectMapper; import org.apache.htt
p.client.fluent.Content;
import org.apache.http.client.fluent.Request;
import java.net.URLEncoder;
import java.util.Map;
...
// verify that the access token belongs to us
Content c = Request.Get(
"https://api.amazon.jp/auth/o2/tokeninfo?access_token=" +
URLEncoder.encode(access_token, "UTF-8"))
.execute()
.returnContent();
Map<String,String> m = new ObjectMapper().readValue(
c.toString(), new TypeReference<Map<String,String>>(){});
if (!"YOUR-CLIENT-ID".equals(m.get("aud"))) {
// the access token does not belong to us
throw new RuntimeException("Invalid token");
}
// exchange the access token for user profile
c = Request.Get("https://api.amazon.jp/user/profile")
.addHeader("Authorization", "bearer " + access_token)
.execute()
.returnContent();
m = new ObjectMapper().readValue(
c.toString(), new TypeReference<Map<String,String>>(){});
System.out.println(
String.format("%s %s %s", m.get("name"),
m.get("email"), m.get("user_id")));
詳しくは、The Login with Amazon
Developer’s Guide for Websitesを参照してください。
30
31
ステップ3 - AddressBookウィジェットとWalletウィジェットの追加
購入者の認証が成功すると、選択した場所にAmazon ログイン & ペイメントのAddressBookウィジェッ
トとWalletウィジェットを表示できます。AddressBookウィジェットとWalletウィジェットには、購入
者がAmazonアカウントに保存している配送先住所と支払い方法がそれぞれ表示されます。
AddressBookウィジェットをセラーのWebサイトに埋め込むには、次のサンプルコードをWebページに追加しま
す。

<style type="text/css">
#addressBookWidgetDiv{width: 400px; height: 228px;}
</style>
<div id="addressBookWidgetDiv">
</div>
<script>
new OffAmazonPayments.Widgets.AddressBook({
sellerId: 'YOUR_SELLER_ID_HERE',
onOrderReferenceCreate: function(orderReference) {
orderReference.getAmazonOrderReferenceId();
},
onAddressSelect: function(orderReference) {
// Replace the following code with the action that you want to perform
// after the address is selected.
// The amazonOrderReferenceId can be used to retrieve
// the address details by calling the GetOrderReferenceDetails
// operation. If rendering the AddressBook and Wallet widgets on the
// same page, you should wait for this event before you render the
// Wallet widget for the first time.
// The Wallet widget will re-render itself on all subsequent
// onAddressSelect events, without any action from you. It is not
// recommended that you explicitly refresh it.
},
design: {
designMode: ‘responsive’
},
}
}).bind("addressBookWidgetDiv");
</script>
WalletウィジェットをセラーのWebサイトに埋め込むには、次のサンプルコードをWebページに追加します。
<!—- please put the style below inside your CSS file -->
#walletWidgetDiv{width: 400px; height: 228px;}
</style>
31
32
<div id="walletWidgetDiv">
</div>
<script>
new OffAmazonPayments.Widgets.Wallet({
design: {
size : {width:'400px', height:'260px'}
},
onPaymentSelect: function(orderReference) {
// Replace this code with the action that you want to perform
// after the payment method is selected.
},
}
}).bind("walletWidgetDiv");
</script>
許可されたパラメーターの範囲内である限りCSS内でウィジェットの高さと幅を制御することができます。他
のCSSとして許可された最小値から最大値の範囲であれば、パーセント、REM、EMのような単位でも利用するこ
とができます。
レスポンシブサイトを使っている場合は次のステップを確認:
1. それぞれのスマートフォンに最適化されたページのheadセクションにメタタグを追加します。このメタタ
グはユーザーが手動でズームを必要とせずにスマートフォン上で読み取り可能な大きさでウィジェットを
表示します:
<meta name="viewport" content="width-device-width, initial-scale=1.0, maximum-scale=1.0"/>
2. 以下の例ではモバイルファーストデザインをCSSで構築するためのメディアクエリーを使うことできます:
/* Please include the min-width, max-width, min-height and max-height */
/* if you plan to use a relative CSS unit measurement to make sure the
/* widget renders in the optimal size allowed. */
*/
#addressBookWidgetDiv {min-width: 300px; max-width: 600px; min-height:
228px; max-height: 400px;}
#walletWidgetDiv {min-width: 300px; max-width:600px; min-height: 228px;
max-height: 400px;}
/* Smartphone and small window */
#addressBookWidgetDiv {width: 100%; height: 228px;}
#walletWidgetDiv {width: 100%; height: 228px;}
/* Desktop and tablet */
@media only screen and (min-width: 768px) {
#addressBookWidgetDiv {width: 400px; height: 228px;}
#walletWidgetDiv {width: 400px; height: 228px;}
32
33
}
Amazon ログイン & ペイメントのAddressBookウィジェットとWalletウィジェットを作成する場合は、width
パラメーターとheightパラメーターを指定する必要があります。指定しないと、ウィジェットは表示されませ
ん。1列のウィジェットと2列のウィジェットで推奨される有効なwidthパラメーターとheightパラメーターを
次の表に示します。
2カラムウィジェット
1カラムウィジェット
パラメーター
推奨の大きさ
有効な大きさ
推奨の大きさ
有効な大きさ
width
400px
400px - 600px
260px
200px - 399px
height
260px
228px - 400px
390px
228px - 400px
購入者の認証が成功すると、次のスクリーンショットのように、指定した場所にAddressBookウィジェッ
トが表示されます。
上記のスクリーンショットでは、AddressBookウィジェットとWalletウィジェットがセラーのWebサイトに直接
表示されています。
購入者が住所と支払い方法をそれぞれのウィジェットから選択したことを確認するまで、チェックアウト
ワークフローを無効にすることをお勧めします。購入者が選択した住所と支払い方法は、それぞれonAddress
Selectコールバック関数とonPaymentSelectコールバック関数を使用して、Amazonからセラーに通知されます。
これらの通知に基づいて、セラーはチェックアウトフローの次のステップを有効にできます。たとえば、
注文内容確認ページが続く場合は、セラーのWebページで続行ボタンを有効にできます。
33
34
注：Address Bookウィジェットがページに表示されると、Amazon ログイン & ペイメントによっ
てDraft状態のOrder Referenceオブジェクトが作成されます(Order Referenceオブジェクトについて詳
しくは、ステップ5を参照)。ステップ5を完了していない場合は、DraftのOrder Referenceオブジェ
クトがキャンセルされます。購入者がセラーのサイトでボタンをクリックしてから3時間以内に、
購入の詳細を設定し、購入を確定してください。
注：購入者は注文内容を確定する前に、住所と支払い方法の両方を選択しなくてはなりません。購
入者が住所と支払い方法を最初に選択した後で、住所を変更する場合、支払い方法も再選択する必
要があります。つまり、住所を選択するごとに(onAddressSelect通知)、onPaymentSelect通知を確認す
る必要があります。AddressBookウィジェットから住所情報を収集する必要がない場合は、「Addre
ssBookウィジェットなしのインテグレーション」を参照してください。
Amazonからの配送先住所の取得
多くの場合、購入者の配送先住所を取得して、送料と税金を計算する必要があります。onAddressSelect通知
の受信後に、セラーはGetOrderReferenceDetailsオペレーションを呼び出すことで、配送と税金に関する複数
のビジネスルールに対応できます。サポートされていない住所を購入者がウィジェットから選択した場合
は、ただちに購入者にフィードバックすることもできます。この場合、別の配送先住所をウィジェットから
選択する必要がある旨のメッセージを購入者に表示してください。
完全な配送先住所を取得するには、AmazonアカウントでログインボタンまたはAmazonアカウントでお支払
いボタン(完全な配送先住所にアクセス)のJavaScriptを使用します(「ステップ1 - 購入者の認証用ボタ
ンウィジェットの追加」を参照)。Amazonアカウントでお支払いボタン(ゲスト用チェックアウト)を使用
している場合は、配送先住所の一部(都道府県、市区町村、郵便番号、国)がセラーに送信されます。
購入者が選択した住所を取得するには、onAddressSelect通知後にGetOrderReferenceDetailsオペレーションを呼
び出します。
注：セラーのAPI呼び出しは、正常に動作するようにすべて署名する必要があります。APIリクエスト
を署名するには、Amazon MWSキーが必要です。このキーを取得するには、セラーセントラルにログイ
ンし、「インテグレーション」タブの「MWS Access Key」セクションを表示します。このAmazon MWS
キーは、Off-Amazon Payments APIセクションのオペレーションのMWSAccessKeyIdリクエストパラメ
ーターに設定する必要があります。署名済みAPI呼び出しのサービスの構成方法について詳しくは、A
mazon MWS開発者ガイドを参照してください。
次の例は、GetOrderReferenceDetailsオペレーションの呼び出し方法を示しています。
https://mws.amazonservices.jp/OffAmazonPayments_Sandbox/2013-01-01
?AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE
&Action=GetOrderReferenceDetails
&AddressConsentToken=IQEBLzAtAhUAjagYW4Jrgw84pCaaIDjrKoEhZXsEXAMPLE
&AmazonOrderReferenceId=S23-1234567-1234567
&SellerId=YOUR_SELLER_ID_HERE
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2012-10-03T19%3A01%3A11Z
&Version=2013-01-01
&Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE
注：注文内容にscope payment:shipping_addressを使い、注文確認する前に完全な配送先住
所を得たい場合は、以下のパラメーターをリクエストに挿入する必要があります。
&AddressConsentToken=YOUR_ACCESS_TOKEN
リクエストパラメーターと応答要素を含む、GetOrderReferenceDetailsオペレーションについて詳し
は、Off-Amazon Payments APIセクションリファレンスの「GetOrderReferenceDetails」を参照して
ください。
ステップ4 – リダイレクト認証エクスペリエンスの使用(任意)
購入者が「Amazon ログイン & ペイメント」ボタンを押した後に、認証用のポップアップウィンドウを
購入者に表示したくないシナリオもあります。購入者を同じウィンドウ内のAmazon認証ページにリダイ
レクトしたい場合(ほとんどはモバイルWebアプリケーションを使用)、または「Amazonアカウントでログ
イン」ボタンをhttpページに配置したい場合は、Java Scriptを使用してリダイレクト認証を開始する必
34
35
要があります。
「作業の開始」セクションで説明したステップに加えて、ここでは、リダイレクト認証を有効にするため
に、セラーがサイトに実装する必要がある追加の変更について説明します。
AddressウィジェットとWalletウィジェットを表示するページで、Java Scriptコードを<header>セクシ
ョンに追加し、ウィジェットで使用するAccess_Tokenを取得してください。
注：この例はテスト環境を使用しています。本稼働環境で使用する場合は適切に変更してくださ
い。
例
<script type='text/javascript'>
function getURLParameter(name, source) {
return decodeURIComponent((new RegExp('[?|&|#]' + name + '=' +
'([^&;]+?)(&|#|;|$)').exec(source)||[,""])[1].replace(/\+/g,'%20'))||null; }
var accessToken = getURLParameter("access_token", location.hash);
if (typeof accessToken === 'string' && accessToken.match(/^Atza/)) {
document.cookie = "amazon_Login_accessToken=" + accessToken + ";secure";}
window.onAmazonLoginReady = function() {
amazon.Login.setClientId('YOUR_CLIENT_ID');
amazon.Login.setUseCookie(true); };
</script>
<script src='https://origin-na.ssl-images-amazon.com/images/G/09/EP/OffAmazonPayments/us/sandbox
/prod/lpa/js/Widgets.js'
</script>
ユーザーがログインしたら、「ログアウト」オプション(ハイパーリンクの場合が多い)をセラーのWeb
サイトに追加してください。ログアウトオプションでは、キャッシュされたトークンを削除し、ユーザ
ープロファイル情報(名前など)をセラーのWebサイトから削除します。ログアウトすると、セラーのWeb
サイトに「ログイン」ボタンを再度表示できます。
JavaScript用のLogin with Amazon SDKを使用している場合は、amazon.Login.logoutメソッドを呼び出し、キ
ャッシュされたトークンを削除できます。リダイレクト認証を使用している場合は、Addressウィジェット
とWalletウィジェットで使用されているCookieも削除してください。例：
document.getElementById('Logout').onclick = function() {
amazon.Login.logout();
document.cookie = "amazon_Login_accessToken=; expires=Thu, 01 Jan 1970 00:00:00 GMT";
window.location = 'REDIRECT_URL';
};
</script>
これ以降のamazon.Login.authorizeの呼び出しでは、ログイン画面がデフォルトで表示されます。
ステップ5 - 選択した配送先住所と支払い方法の表示(任意)
購入者が配送先住所と支払い方法の両方をAmazon ペイメントウィジェットから選択した後のオプショ
ンのステップは、読み取り専用バージョンのAddressBookウィジェットとWalletウィジェットを表示
し、購入者が購入を確定する前に、選択内容を最後に確認できるようにすることです。注文内容確認ペ
ージを設定し、読み取り専用ウィジェットを表示する場合は、確認ページを表示する前に、購入者が住
所と支払い方法を選択したことを確認することをお勧めします。この操作を実行するには、GetOrderRef
erenceDetailsオペレーションを呼び出し、応答に制約要素が含まれているかどうかを確認します。この
各制約には、適切な是正措置に必要な情報が表示されます。たとえば、ShippingAddressNotSet制約ま
たはPaymentPlanNotSet制約を受信した場合は、配送先住所または支払い方法を選択する必要がある旨
を購入者に通知してください。また、購入者を適切な選択ページに自動的にリダイレクトできるよう
に、セラーのサイトをインテグレーションすることもできます。購入者が配送先住所または支払い方法
を選択していない場合は、読み取り専用ウィジェットでも購入者による選択が必要である旨を通知しま
す。注文内容で制約が返されない場合は、ConfirmOrderReference呼び出しが成功しています。制約につい
て詳しくは、Off-Amazon Payments APIセクションリファレンスの「GetOrderReferenceDetails」と
35
36
「注文内容の制約」を参照してください。購入者が注文を確定したら、注文を出荷し、支払いを回収で
きます。
Amazon ログイン & ペイメントの読み取り専用AddressBookウィジェットとWalletウィジェットを作成
する場合は、widthパラメーターとheightパラメーターを指定する必要があります。指定しないと、ウ
ィジェットは表示されません。推奨される有効なwidthパラメーターとheightパラメーターを次の表に
示します。
パラメーター
推奨の大きさ
有効な大きさ
Width
400px
290px – 600px
Height
185px
185px
読み取り専用バージョンのウィジェットを表示する場合は、セラーのサイトにウィジェットを最初に表示し
たコードと同じコードを使用できますが、この場合は、パラメーターdisplayMode:"Read"をコード内に追加し
ます。編集可能なAddressBookウィジェットまたはWalletウィジェットと同じページに読み取り専用ウィジェ
ットを表示する必要がある場合は、onAddressSelect通知またはonPaymentSelect通知を受け取り、その時点で読
み取り専用ウィジェットを再表示します。そうしないと、読み取り専用ウィジェットに正しい情報が表示さ
れません。以下は、パラメーターを追加したコードの例です。

#readOnlyAddressBookWidgetDiv {width: 400px; height: 185px;}
#readOnlyWalletWidgetDiv {width: 400px; height: 185px;}
</style>
<div id="readOnlyAddressBookWidgetDiv">
</div>
<div id="readOnlyWalletWidgetDiv">
</div>
<script>
new OffAmazonPayments.Widgets.AddressBook({
amazonOrderReferenceId: amazonOrderReferenceId,
// amazonOrderReferenceId obtained from Address widget
displayMode: "Read",
design: {
designMode: 'responsive'
},
}
}).bind("readOnlyAddressBookWidgetDiv");
</script>
<script>
new OffAmazonPayments.Widgets.Wallet({
amazonOrderReferenceId: amazonOrderReferenceId,
// amazonOrderReferenceId obtained from Address widget
displayMode: "Read",
design: {
},
36
37
}
}).bind("readOnlyWalletWidgetDiv");
</script>
パラメーターを追加すると、次のスクリーンショットのように、読み取り専用バージョンのウィジ
ェットがWebサイトに表示されます。
ステップ6 - 購入の詳細の設定と購入の確定
Order Referenceオブジェクト
ステップ1に示すように、購入者がAmazonで認証すると、Order Referenceオブジェクトと呼ばれるシステ
ムオブジェクトがAmazon ログイン & ペイメントでただちに作成されます。このオブジェクトには、Amaz
on ログイン & ペイメントを使用した購入者の支払いに関連するすべての属性が保存されます。
Amazon ログイン & ペイメントチェックアウトプロセスのこの時点で、Order Referenceオブジェクトに購入
者の配送先住所と支払い方法の選択内容が入力されます。次に、追加の属性をOrder Referenceオブジェクト
に設定する必要があります。これにより、Amazon ログイン & ペイメントの支払いと、追跡するその他の詳
細を関連付けることができます。購入金額の設定も必要です。トランザクションに指定した注文番号など、
追加の詳細を設定することもできます。
37
38
SetOrderReferenceDetailsオペレーションを呼び出して、これらの属性を設定したら、 ConfirmOrderReference
オペレーションを呼び出し、購入を確定してAmazonに通知する必要があります。購入を確定すると、支払
いがオーソリ処理された旨がAmazonから購入者に通知されます。注文の支払いを処理するには、注文内容
を確定する必要があります。
注文内容の詳細の設定
Order Referenceオブジェクトの詳細を設定するには、SetOrderReferenceDetailsオペレーションを呼び出しま
す。この呼び出し中に、購入の合計金額を指定します。これにより、購入に関する追加の情報をOrder Ref
erenceオブジェクトに含めることができます。この追加情報は、Amazonから購入者への連絡と、セラーに
返される支払い処理情報の両方に使用されます。
次の例は、SetOrderReferenceDetailsオペレーションの呼び出し方法を示しています。
?AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Action=SetOrderReferenceDetails
&OrderReferenceAttributes.OrderTotal.Amount=106
&OrderReferenceAttributes.OrderTotal.CurrencyCode=USD
&OrderReferenceAttributes.SellerNote=Lorem%20ipsum%20dolor
&OrderReferenceAttributes.SellerOrderAttributes.SellerOrderId=5678-23
&OrderReferenceAttributes.SellerOrderAttributes.StoreName=CourtAndCherry.com
&SignatureVersion=2
&Timestamp=2013-11-16T19%3A01%3A11Z
&Version=2013-01-01
&Signature=2RPzkOgQmDybUjk0dA54maCEXAMPLE
Order Referenceの詳細のパラメーターの設定は、「支払いがオーソリ処理された」ことを伝えるEメール
に表示される内容に反映されます。詳しくは、「Eメールに表示されるデータの処理」の「支払いがオー
ソリ処理されたことを伝えるEメール」セクションを参照してください。
リクエストパラメーターと応答要素を含む、SetOrderReferenceDetailsオペレーションについて詳し
は、Off-Amazon Payments APIセクションリファレンスの「SetOrderReferenceDetails」を参照して
ください。
注：Amazon ログイン & ペイメントインテグレーションプロセスのこのステップでは、購入金額
を設定する必要があります。選択した住所に基づいて、購入金額を変更する場合は、onAddressSele
ctイベントごとにGetOrderReferenceDetailsオペレーションを呼び出し、購入金額をリセットしま
す。
購入の詳細の確認
Order Referenceオブジェクトの属性(SetOrderReferenceDetailsオペレーション呼び出しで追加する属性を
含む)を設定したら、Order Referenceオブジェクトを確認する必要があります。このステップにより、
購入者がセラーのサイトで注文したことがAmazonに通知されますが、Order Referenceオブジェクトの
確認は、資金を保証するものでも、資金を保留にするものでもありません。この場合は、支払いのオー
ソリ処理と資金のキャプチャーがまだ残っています。
注：購入者が住所または支払い方法を選択できていない場合、またはセラーが金額を設定していな
い場合は、注文内容を確定することはできません。注文内容を確定できない場合は、注文内容に制
約が発生します。注文内容確認ページを使用している場合は、注文内容確認ページを表示して制約
を確認する前に、GetOrderReferenceDetailsオペレーションを呼び出します。住所または支払い関連の
制約がある場合は、購入者が住所または支払い方法(あるいは両方)を選択するまで、セラーのWebサ
イトの確定ボタンは無効にしてください。制約のある注文内容を確定しようとすると、エラー応答
が表示され、具体的な制約違反が表示されます。制約なしでConfirmOrderReferenceオペレーションが
成功しないかぎり、注文確認ページを購入者に表示しないでください。制約について詳しくは、Off
-Amazon Payments APIセクションリファレンスの「GetOrderReferenceDetails」および「注文確認
38
39
の制約」のセクションを参照してください。
Order Referenceオブジェクトを確認するには、ConfirmOrderReferenceオペレーションを呼び出します。
次の例は、ConfirmOrderReferenceオペレーションの呼び出し方法を示しています。
&Action=ConfirmOrderReference
&SignatureVersion=2
&Timestamp=2013-11-16T19%3A01%3A11Z
&Version=2013-01-01
リクエストパラメーターと応答要素を含む、ConfirmOrderReferenceオペレーションについて詳しくは、Off
-Amazon Payments APIセクションリファレンスの「ConfirmOrderReference」を参照してください。
ConfirmOrderReferenceオペレーションを正常に呼び出すと、Order ReferenceオブジェクトがDraft状態から
Open状態になります。状態遷移について詳しくは、「システムとAmazon Paymentsの同期」を参照してく
ださい。
「Amazonアカウントでお支払い」ボタン(ゲスト用チェックアウト)オプションを使用している場合は、Co
nfirmOrderReferenceオペレーションを呼び出してOrder Referenceオブジェクトを確認するまで、配送先住
所の一部のみが表示されます。この住所の一部を使って、税金と配送費を計算します。注文の処理と顧客
サービスの提供には、購入者に関する詳細と完全な配送先住所が必要であるとAmazonでは認識していま
す。ConfirmOrderRefenceオペレーションを呼び出して、Order Referenceオブジェクトを確認したら、GetOrd
erReferenceDetailsオペレーションを呼び出して、完全な配送先住所を取得し、その住所まで配送できるこ
とを確認してください。
「Amazonアカウントでお支払い」ボタン(ゲスト用チェックアウト)オプションを使用している場合
は、Order Referenceオブジェクトの確認後に、次の顧客情報を利用できます。
購入者詳細
入手される内容
Buyer name
ConfirmOrderReferenceオペレーションを呼び出し成功した後にGetO
rderReferenceDetailsオペレーションを呼び出します。
Buyer e-mail address
Buyer phone number (if available)
Recipient name
Shipping address
部分的な住所情報(市区町村、郵便番号、国コード)は、AddressBook
ウィジェットで住所を選択した後すぐにGetOrderReferenceDetailsオ
ペレーションを呼び出すことで入手することができます。完全な住所
情報(地番を含む情報)は、ConfirmOrderReferenceの呼び出しが成功
した後に、GetOrderReferenceDetailsを呼び出して入手されます。
Recipient phone number (if available)
オーソリ処理と支払い方法のキャプチャーの次のステップが処理されるまでは、時間がかかるため、こ
の時点では、既存の購入者向けの注文確認ビジネスプロセス(確認のEメール、確認のランディングペー
ジなど)へ進むことを強くお勧めします。
Order ReferenceオブジェクトがOpen状態の場合は、購入者の支払いプロセスを開始できます。
39
40
購入者への注文確認のEメール
Order ReferenceオブジェクトがOpen状態になると、Amazonから購入者にただちにEメールが送信され、
購入者がOrder Referenceオブジェクトの合計金額の支払いに同意したことが通知されます。
注：Order Referenceオブジェクトは、本番モードとテストモードの両方で180日間Open状態のままに
なります(ConfirmOrderReferenceオペレーションを正常に呼び出した場合)。180日を超えると、Order R
eferenceオブジェクトはClosed状態になります。オーソリ処理をリクエストできるのは、OrderRefer
enceオブジェクトがOpen状態の間のみです。
購入者に送信されるサンプルのEメールは、「支払いがオーソリ処理された」ことを伝えるEメールで確認で
きます。
注：「支払いがオーソリ処理された」ことを伝えるEメールは、注文内容を確定してAmazonに通知
すると、購入者に送信されます。このEメールで、Amazon Paymentsを使用して購入の支払いがオー
ソリ処理されたことを購入者に通知します。このEメールは、注文時点または注文後にセラーが送
信するAuthorizeリクエストとは関係ありません。
ステップ7 - オーソリのリクエスト
購入を確定し、Open状態のOrder Referenceオブジェクトを正常に作成すると、支払い回収のプロセスを開
始できます。最初にAuthorizeオペレーションを呼び出してAuthorizationオブジェクトを作成し、購入者が
チェックアウトプロセス中に選択した支払い方法でオーソリを取得する必要があります。
Authorizationオブジェクト
Amazon ログイン & ペイメントでは、AuthorizationオブジェクトはOrder Referenceオブジェクトに関連
付けられている支払い方法で決済が可能かどうかを表します。Authorizationオブジェクトは、常に次の4
つの状態のいずれかになります。
•
•
•
•
Pending– Authorizationオブジェクトは同期と非同期の2つのモードで動作します。Pendingステータス
は、非同期モードを選択した場合にのみ適用されます。詳しくは、「オーソリの同期モードと非同期モ
ード」を参照してください。非同期モードでは、オーソリはリアルタイムで処理されません。
オーソリリクエストを初めて送信したときには、Authorizationオブジェクトは常にPendingの状態で
す。セラーには、Authorizeオペレーションからのオペレーションステータスの応答を示す応答がただち
に送信され、このステータスが通知されます。Authorizationオブジェクトは、Amazonによって処理され
るまで、Pending状態のままです。処理時間はさまざまで、数分で終わることもあります。処理が完了す
ると、Amazonから最終的な処理ステータスが通知されます。最終的なオーソリステータスの受信方法に
ついて詳しくは、「ステップ7 - オーソリステータスの取得」を参照してください。
Open – Authorizationオブジェクトは、支払い方法が正常にオーソリ処理されるとすぐにOpen状態にな
ります。このオーソリに対しキャプチャーをリクエストできる期間は、最大30日です。
Declined – Authorizationオブジェクトは、Amazonがオーソリリクエストを却下するとDeclined状態に
なります。詳しくは、「支払い拒否への対応」を参照してください。
Closed – Authorizationオブジェクトは、次のようなさまざまな理由で、Closed状態になる場合がありま
す。
• オブジェクトが本番モードで30日間、テストモードで2日間Open状態だった場合。
• Openのオーソリに対して全額または一部の金額のキャプチャーを完了した場合。
Amazonでは、1つのオーソリに対して1つのキャプチャーしか許可しません。オーソリは、
キャプチャーリクエストが正常に処理されるとただちに終了します。
• オーソリをClosedとマークした場合。
• Order ReferenceオブジェクトをCanceledとマークした場合。
• AmazonがオーソリをClosedした場合。
Authorizationオブジェクトの状態およびこれらの状態間の遷移について詳しくは、「システムとAmazon P
aymentsの同期」を参照してください。
次の例は、Authorizeオペレーションの呼び出し方法を示しています。
40
41
?AWSAccessKeyId=AKIAFBM3LG5JEEXAMPLE
&Action=Authorize
&AuthorizationAmount.Amount=106
&AuthorizationAmount.CurrencyCode=USD
&AuthorizationReferenceId=test_authorize_1
&SellerAuthorizationNote=Lorem%20ipsum%20dolor
&SignatureVersion=2
&Timestamp=2013-11-16T19%3A01%3A11Z
&TransactionTimeout=60
&Version=2013-01-01
&Signature=WlQ708aqyHXMkoUBk69Hjxj8qdh3aDcqpY71hVgEXAMPLE
リクエストパラメーターと応答要素を含む、Authorizeオペレーションについて詳しくは、Off-Amazon Paymen
ts APIセクションリファレンスの「Authorize」を参照してください。
ステップ8 - オーソリステータスの取得
Authorize呼び出しへの応答には、AuthorizationStatus応答要素が含まれます。この要素は、常にPendingに
設定されます(非同期モードのオペレーションを選択した場合)。オーソリリクエストの最終的なステータス
(OpenやDeclinedなど)は、インスタントペイメント通知サービス経由で、後でAmazonからセラーに通知され
ます。インスタントペイメント通知サービスについて詳しくは、「システムとAmazon Paymentsの同期」を参
照してください。
次に、オーソリ処理の応答で返されたAmazonAuthorizationIdを使用して、GetAuthorizationDetailsオペレー
ションを呼び出すことで、Authorizationオブジェクトの詳細のクエリーをオプションで実行できます。正
常なオーソリ処理に対する資金のキャプチャーには、この一意の識別子も必要になります。詳しくは、OffAmazon Payments APIセクションリファレンスの「GetAuthorizationDetails」を参照してください。
注：本番モードでは、Authorizeオペレーションを正常に送信した後に、オーソリ処理に対して資金を
キャプチャーできる期間は30日です。この期間を過ぎると自動的に終了します。テストモードでは、
資金をキャプチャーできるのは2日間のみです。
注：AuthorizeリクエストのTransactionTimeoutパラメーターを使用すると、オーソリの処理までの
最大待機時間を指定できます。この時点で未処理のオーソリ(Pending状態のまま)は、Amazonによっ
て却下されます。却下のメッセージは、TransactionTimedOutの理由コードで、インスタントペイメ
ント通知サービス経由で通知されます。
TransactionTimeoutを0に設定すると、オーソリにOpenまたはDeclinedステータスがオペレーション
から常に返されます。この場合、同期処理できないオーソリは、TransactionTimedOutの理由コード
で却下されます。詳しくは、「オーソリの同期モードと非同期モード」を参照してください。
ステップ9 - キャプチャーのリクエスト
Authorizeオペレーションを正常に呼び出し、AuthorizationオブジェクトがOpen状態の場合は、このオーソ
リに対する資金をキャプチャーできます。
Captureオブジェクト
Amazon ログイン & ペイメントでは、Captureオブジェクトは、購入者のアカウントからセラーのアカウ
ントへの資金の移動を表します。すべてのCaptureオブジェクトは、作成済みでまだ有効なAuthorizatio
nオブジェクトに関連付けられます。Captureオブジェクトは、常に次の4つの状態のいずれかになりま
す。
41
42
• Pending – Captureオブジェクトは、Amazonによって処理されるまで、Pending状態のままです。
オーソリが正常に処理されてから7日以内にキャプチャーリクエストを送信すると、Amazonによって
ただちに処理されます。Captureオペレーションへの最初の応答は、CompletedまたはDeclined状態を
示します。オーソリが正常に処理されてから8日目以降にキャプチャーをリクエストした場合、すぐ
には処理されません。オペレーションへの最初の応答でPending状態が返されると、Amazonによって
リクエストが処理されるまで、この状態のままです。キャプチャーの処理時間はさまざまで、1時間
以上になることもあります。処理が完了すると、Amazonから処理ステータスが通知されます。最終
的なキャプチャーステータスの受信方法について詳しくは、「ステップ9 - キャプチャーステータ
スの取得」を参照してください。
• Declined – Captureオブジェクトは、Amazonがキャプチャーリクエストを却下すると、Declined
状態になります。詳しくは、「支払い拒否への対応」を参照してください。
• Completed – Captureオブジェクトは、購入者が正常に請求されると、Completed状態になります。
• Closed – Captureオブジェクトは、Amazonが購入者のアカウントに問題があると確認した場合、キャプ
チャーの最高額がすでに返金された場合、または、Captureオブジェクトに対してリクエストした部分
的な返金の数が10になった場合に、Closed状態になります。返金可能な額は、キャプチャーされた金額
の15%または8,400円のどちらか少ないほうを上限とします。Closed状態になると、キャプチャーに対し
て返金は許可されません。
Captureオブジェクトの状態およびこれらの状態間の遷移について詳しくは、「システムとAmazon Payment
sの同期」を参照してください。
Authorizationオブジェクトで取り置かれた資金を回収するには、オーソリが正常に処理されてから30日以内
(本番モード)または2日以内(テストモード)に、Captureオペレーションを呼び出す必要があります。Declined
の可能性を低くするために、オーソリ処理から7日以内に資金をキャプチャーすることを強くお勧めします。
次の例は、Captureオペレーションの呼び出し方法を示しています。
&Action=Capture
&AmazonAuthorizationId=S23-1234567-1234567-0000001
&CaptureAmount.Amount=106
&CaptureAmount.CurrencyCode=USD
&CaptureReferenceId=test_capture_1
&SellerCaptureNote=Lorem%20ipsum%20dolor
&SignatureVersion=2
&Timestamp=2013-11-19T19%3A01%3A11Z
&Version=2013-01-01
Captureオペレーションのパラメーターの設定は、請求通知のEメールに表示される内容に反映されます。
「Eメールに表示されるデータの処理」の「請求通知のEメール」セクションを参照してください。
リクエストパラメーターと応答要素を含む、Captureオペレーションについて詳しくは、Off-Amazon Payments
APIセクションリファレンスの「キャプチャー」を参照してください。
42
43
ステップ10 - キャプチャーステータスの取得
オーソリが正常に処理されてから7日以内にキャプチャーリクエストを送信すると、Amazonによってただ
ちに処理されます。キャプチャーリクエストへの最初の応答は、CompletedまたはDeclined状態を示し
ます。オーソリが正常に処理されてから8日目以降にキャプチャーをリクエストした場合、すぐには処理
されません。キャプチャーリクエストへの最初の応答でPending状態が返されると、Amazonによってリク
エストが処理されるまで、この状態が続きます。処理時間はさまざまで、1時間以上かかることもありま
す。
処理が完了すると、インスタントペイメント通知サービスでAmazonからセラーに最終的な処理状態が通知
されます。Amazonがセラーのキャプチャーリクエストを完了できない場合は、Declinedメッセージが表示
されます。却下について詳しくは「支払い拒否への対応」を参照してください。インスタントペイメント
通知サービスについて詳しくは、「システムとAmazon Paymentsの同期」を参照してください。
次に、キャプチャー応答で返されたAmazonCaptureIdを使用して、GetCaptureDetailsオペレーションを呼び
出すことで、Captureオブジェクトの詳細のクエリーをオプションで実行できます。完了したキャプチャ
ーに対する資金の返金には、この一意の識別子も必要になります。詳しくは、Off-Amazon Payments API
セクションリファレンスの「GetCaptureDetails」を参照してください。
購入者へのキャプチャー正常処理のEメール
キャプチャーが正常処理されるたびに、キャプチャーの詳細を記載した確認のEメールがAmazonから購入
者に送信されます。購入者へのサンプルのEメールを表示するには、「請求通知のEメール」を参照して
ください。
ステップ11 - 注文内容の終了
必要な購入金額を請求し、それ以上のオーソリ処理をリクエストしない場合は、CloseOrderReference
オペレーションを呼び出して、Order ReferenceオブジェクトをClosedとマークしてください。
Order ReferenceオブジェクトをClosedとマークする場合は、次の点に注意してください。
• Openなオーソリに対してキャプチャーを実行できますが、Order Referenceオブジェクトに新しいオーソ
リを作成することはできません。
• Order Referenceオブジェクトに対して返金を実行することができます。
詳しくは、Off-Amazon Payments APIセクションリファレンスの「CloseOrderReference」を参照してくださ
い。
ステップ12 - 返金のリクエスト
Refundオペレーションを呼び出して、正常に終了したCaptureオペレーションに対する一部または全額返金を
発行できます。キャプチャープロセスにより生成されるAmazonCaptureIdは、Refundオペレーションの呼び
出しに含める必要があります。
Refundオブジェクト
Amazon ログイン & ペイメントでは、Refundオブジェクトは、購入者のアカウントからセラーのアカウン
トへのキャプチャー済みの資金の移動を表します。Refundオブジェクトは、常に次の4つの状態のいずれ
かになります。
•
Pending – 返金はリアルタイムで処理されません。返金リクエストを初めて送信したときには、Re
fundオブジェクトは常にPending状態です。セラーには、Refundオペレーションへの最初の応答が送
信され、このステータスが通知されます。Refundオブジェクトは、Amazonによって処理されるま
で、Pending状態のままです。処理時間はさまざまで、数時間で終わることもあります。処理が完
了すると、Amazonから処理ステータスが通知されます。最終的な返金テータスの受信方法について
詳しくは、「ステップ12 - 返金ステータスの取得」を参照してください。
43
•
•
44
Declined – Refundオブジェクトは、リクエストがAmazonによってDeclinedされると、Declined状
態になります。詳しくは、「支払い拒否への対応」を参照してください。
Completed – Refundオブジェクトは、返金が正常に処理されると、Completed状態になります。
次の例は、Refundオペレーションの呼び出し方法を示しています。
&Action=Refund
&AmazonCaptureId=S23-1234567-1234567-0000002
&RefundAmount.Amount=83.50
&RefundAmount.CurrencyCode=USD
&RefundReferenceId=test_refund_1
&SellerRefundNote=Lorem%20Ipsum%20dolor
&SignatureVersion=2
&Timestamp=2013-11-27T19%3A01%3A11Z
&Version=2013-01-01
Refundオペレーションのパラメーターの設定は、返金通知のEメールに表示される詳細情報に反映されま
す。「Eメールに表示されるデータの処理」の「返金通知のEメール」セクションを参照してください。
リクエストパラメーターと応答要素を含む、Refundオペレーションについて詳しくは、Off-Amazon Payments
APIセクションリファレンスの「返金」を参照してください。
ステップ13 - 返金ステータスの取得
Refundオペレーションへの応答には、RefundStatusと呼ばれる応答要素が含まれます。この要素は、常に
Pendingに設定されます。返金リクエストの最終的なステータス(CompletedやDeclinedなど)は、インス
タントペイメント通知サービス経由で、後でAmazonからセラーに通知されます。インスタントペイメン
ト通知サービスについて詳しくは、「システムとAmazon Paymentsの同期」を参照してください。
次に、返金応答で返されたAmazonRefundIdを使用して、GetRefundDetailsオペレーションを呼び出すこと
で、Refundオブジェクトの詳細のクエリーをオプションで実行できます。詳しくは、Off-Amazon Payment
s APIセクションリファレンスの「GetRefundDetails」を参照してください。
購入者への返金のEメール
返金が正常に完了するたびに、返金の詳細を記載した確認のEメールがAmazonから購入者に送信され
ます。返金通知のサンプルのEメールを表示するには、「返金通知のEメール」を参照してください。
44
45
Eメールに表示されるデータの処理
各オペレーションを呼び出す際のパラメーターの設定は、購入者に送信するEメールに表示する詳細情報
に反映されます。
1. 「支払いがオーソリ処理された」ことを伝えるEメールには、SetOrderReferenceDetailsのフィール
ドが表示されます。
2. 返金または請求通知のEメールには、RefundオペレーションとCaptureオペレーションによってそれ
ぞれ入力されたフィールドと、Order ReferenceオペレーションとSetOrderReferenceDetailsオペレ
ーションからのパラメーターが表示されます。
3. 支払い情報の更新のEメールには、返金および請求通知と同様のパラメーターが表示されます。
下記の例は、購入者へのEメールと入力されたパラメーターを示しています。
「支払いがオーソリ処理された」ことを伝えるEメール
購入者がAmazonで認証すると、Order Referenceオブジェクトと呼ばれるシステムオブジェクトがAmazo
n ログイン & ペイメントでただちに作成されます。Order Referenceオブジェクトが作成されたら、Se
tOrderReferenceDetailsオペレーションを呼び出し、追加の属性をOrder Referenceオブジェクトに設
定します。
購入者に送信される「支払いがオーソリ処理された」ことを伝えるEメールの一部を次に示します。
番号付きのフィールドと、そのフィールドの入力に使用するOrder Referenceオブジェクトの対応するパ
ラメーターに注意してください。
45
1
46
セラー情報：フィールドには、店舗名が入力されます。
&OrderReferenceAttributes.SellerOrderAttributes.StoreName
この属性が設定されていない場合は、登録時に指定した店舗名がデフォルトで設定されます。
例：
2
注文合計(Order Total)：次の2つのパラメーターで設定されます。
&OrderReferenceAttributes.OrderTotal.Amount
&OrderReferenceAttributes.OrderTotal.CurrencyCode
例：
3
注文番号(Seller Order ID)：
&OrderReferenceAttributes.SellerOrderAttributes.SellerOrderId
例：
4
セラーからの注意：ここには「Lorem Ipsum dolor」と表示されていますが、セラーからのメッセージは、「あなたの注文は
青色の靴です」のようになります。パラメーターを次に示します。
&OrderReferenceAttributes.SellerNote
例：
&OrderReferenceAttributes.SellerNote=Your%20order%20for%20Blue%20Shoes
46
47
請求通知のEメール
請求通知のEメールには、返金通知のEメールと同様のパラメーターが表示されます。
1
例：
2
例：
47
3
48
例：
6
セラーからの注意：ここには「Lorem Ipsum dolor」と表示されていますが、セラーからのメッセージは、
「青色の靴の支払いです」のようになります。パラメーターを次に示します。
&SellerCaptureNote
例：
&SellerCaptureNote=Payment%20for%20Blue%20Shoes
7
合計請求金額(Total Amount Charged)：Eメールの書き出しの文と合計請求金額が表示され、次の2つのパラメーター
で設定されます。
&CaptureAmount.Amount
&CaptureAmount.CurrencyCode
例：
&CaptureAmount.Amount=106
&CaptureAmount.CurrencyCode=USD
48
49
返金通知のEメール
返金通知のEメールを次に示します。店舗名と注文番号はOrder Referenceから取得され、一部はRefund
オペレーションの呼び出しから取得されます。
1
例：
3
例：
49
6
50
「青色の靴の返金です」のようになります。パラメーターを次に示します。
&SellerRefundNote
例：
&SellerRefundNote=Refund%20for%20Blue%20Shoes
7
合計返金金額(Total Amount Refunded)：Eメールの書き出しの文と合計返金金額が表示され、次の2つのパラメーター
で設定されます。
&RefundAmount.Amount
&RefundAmount.CurrencyCode
例：
&RefundAmount.Amount=83.50
&RefundAmount.CurrencyCode=USD
50
51
支払い情報更新のEメール
支払い情報更新のEメールには、返金通知のEメールと同様のパラメーターが表示されます。
1
例：
2
例：
51
3
52
例：
4
「青色の靴の支払いです」のようになります。パラメーターを次に示します。
&SellerCaptureNote
例：
&SellerCaptureNote=[R2] For%20your%20order%20of%20Casad%20%272Jours%20Bonheur%27%20Satchel%20in%20Sandstorm
52
53
オーソリの同期モードと非同期モード
Authorizeオペレーションは、次の2つモードのいずれかで動作します。
1. 非同期モード – このモードでは、Authorizeオペレーションは、API応答で常にPendingステータスを返し
ます。最終的な処理ステータス(OpenまたはDeclined)を取得するには、インスタンス通知を確認する必
要があります。
2. 同期モード – このモードでは、Authorizeオペレーションは、API応答でOpenまたはDeclinedステータス
を常に返します。
Authorizeオペレーションについて詳しくは、「ステップ7 - オーソリのリクエスト」または「ステップ8
- オーソリステータスの取得」を参照してください。
オペレーションのモードの選択
Authorize APIのオペレーションのモードの選択は、ビジネスプロセスと技術システムによって異なります。
非同期モード
非同期モードのオペレーションを選択するには、TransactionTimeoutパラメーターを指定しないか、ゼ
ロ以外の値をAuthorize APIのTransactionTimeoutパラメーターに指定します。ゼロ以外の値について詳
しくは、Off-Amazon Payments APIセクションリファレンスの「Authorize」を参照してください。
次のサンプルコードは、Authorize APIの非同期モードを有効にする方法を示しています。
&Action=Authorize
&AuthorizationAmount.Amount=94.50
&SellerAuthorizationNote=Authorization%20for%20Blue%20Shoes
&SignatureVersion=2
&Timestamp=2013-11-16T19%3A01%3A11Z
&Version=2013-01-01
Authorizeオペレーションリクエストに対するAPI応答では、通常は2～3秒以内に最初のPendingステータスが
通知されます。OpenまたはDeclinedの最終的な処理ステータスは、通常は60秒以内にインスタントペイメン
ト通知経由で通知されます。まれなケースですが、Amazonがトランザクションを手動で調査している場合
は、セラーが指定したTransactionTimeout値まで、または24時間(値を指定しない場合)、最終的な処理ステ
ータスが通知されないことがあります。上記のサンプルコードでは、ユーザーが60分のTransactionTimeout
をリクエストしています。
ビジネスプロセスと技術システムに注文またはトランザクションを最大24時間保持できる場合は、非同期
モードを使用することをお勧めします。最終的な処理ステータスはリアルタイムで通知されないため、却
下されないことを想定して、購入者に購入を確認できます。後でオーソリのDeclinedステータスが通知さ
れた場合は、失敗したトランザクションを購入者に通知し、Amazon ペイメントのWebサイトから支払い方
法を更新するように購入者にリクエストして、別の方法で支払いを回収するか、却下の理由コードに基づ
いて注文をキャンセルすることが必要になります。
詳しくは、「支払い拒否への対応」を参照してください。
53
54
このモードを選択すると、トランザクションを調査する時間がセラーからAmazonに提供されるため、通常は
オーソリのDeclined率が低下します。
同期モード
オペレーションの同期モードを選択するには、TransactionTimeoutパラメーターの値を0に指定します。
次のサンプルコードは、Authorize APIの同期モードを有効にする方法を示しています。
&Action=Authorize
&AuthorizationAmount.Amount=94.50
&SellerAuthorizationNote=Authorization%20for%20Blue%20Shoes
&SignatureVersion=2
&Timestamp=2013-11-16T19%3A01%3A11Z
&Version=2013-01-01
同期モードオペレーションでは、Authorizeリクエストに対するAPI応答で、通常は6～8秒以内にOpenまたは
Declinedステータスが通知されます。AmazonでAuthorizationを同期処理できない場合は、TransactionTime
outの理由コードでDeclinedステータスが返されます。
たとえば、デジタルダウンロードを提供する場合や、お急ぎ便の確認を行う場合など、購入者がまだセラ
ーのサイトにいる間に、支払いをオーソリ処理またはキャプチャーしたい場合には、同期モードを使用す
ることをお勧めします。
このモードを選択すると、Pendingの一部のオーソリがDeclinedに変換され、Declined率が高くなる場合があ
ります。これらのオーソリの却下は、理由コードTransactionTimeoutで追跡できます。
オーソリの却下をオフラインプロセスで処理する非同期モードと異なり、同期モードでは、購入者がサイト
にいる間に却下の処理を行うことができます。詳しくは、「支払い拒否への対応」を参照してください。
54
55
AddressBookウィジェットなしのインテグレーション
購入者の住所をAddressBookウィジェットから収集しなくてもよいシナリオもあります。このようなシナリ
オは、チェックアウトプロセスで配送先住所を収集する必要がない場合、または購入者の住所を自社で収
集したい場合に発生する可能性があります。
注：購入者から住所を収集するのにAmazon AddressBookウィジェットを使用しない場合、トランザ
クションはAmazon ペイメント支払い保護ポリシーの対象にはなりません。Amazon ペイメント支払
い保護ポリシーについて詳しくは、Amazon ログイン & ペイメント WebサイトのAmazon ペイメント
利用規約を参照してください。
次の例は、ボタンウィジェットを表示し、AddressBookウィジェットを使用しないシナリオに対応する方
法を示しています。

#walletWidgetDiv {width: 400px; height: 228px;}
</style>
<div id="walletWidgetDiv">
</div>
<script>
new OffAmazonPayments.Widgets.Wallet({ sellerId: 'YOUR_SELLER_ID_HERE',
onOrderReferenceCreate: function(orderReference) {
},
design: {
},
onPaymentSelect: function(orderReference) {
// Replace this code with the action that you want to perform
// after the payment method is selected.
},
}
}).bind("walletWidgetDiv");
</script>
「作業の開始のステップ3 - AddressBookウィジェットとWalletウィジェットの追加」のように、CSS経由で
ウィジェットのサイズを指定します。Walletウィジェットは提示されたスペースに適してリサイズされま
す。ブラウザーのウィンドウサイズに合ったリサイズしたウィジェットが必要な場所にレスポンシブサイト
を構築したい場合は、メディアクエリーを利用できます。
Walletウィジェットをレンダリングしたときは、OrderReferenceオブジェクトを生成しなければなりませ
ん。これを行うには、onOrderReferenceCreateコールバック関数をウィジェットの呼び出しパラメーターの
１つして特定しなければなりません。onOrderReferenceCreate関数はウィジェットがレンダリングしたとき
にコールされたorderReferenceオブジェクトから得られます。orderReferenceオブジェクト上のgetAmazonOr
derReferenceId()関数を呼び出すことでorderReferenceIdを得ることができます。Amazon ログイン & ペイ
メントをインテグレーション中は至る所でamazonOrderReferrenceIdを保持しなければなりません。
55
56
スマートフォン用の折りたたみ可能ウィジェットの使用
すべてのAmazon ログイン & ペイメントウィジェットは、タッチスクリーン用に最適化されており、タ
ブレットやスマートフォンでの使いやすさが向上しています。スマートフォン用に最適化されているWeb
サイトが別にある場合は、折りたたみ可能なウィジェットをWebサイトに使用することをお勧めします。
折りたたみ可能ウィジェットは、1列のユーザーインタフェースに合うように設計されており、スクロー
ル操作を最小限に抑えられるように、展開や折りたたむことができます。折りたたみ可能ウィジェット
は、ウィジェットに割り当てるスペースを最小限に抑え、購入者のデバイスの画面領域を最大限に利用す
る必要があるWebサイトに最適です。標準のウィジェットは、折りたたみ可能ウィジェットと異なり、高
さと幅が固定されており、購入者が展開や折りたたむことができません。標準のウィジェットについて
は、「作業の開始」を参照してください。
折りたたみ可能なAddressBookウィジェットとWalletウィジェットは、スマートフォンの画面の幅に合わせ
てサイズが変更されます。折りたたみ可能ウィジェットの高さは、135ピクセルに固定されます(折りたた
み時)。購入者は、ウィジェットを展開して、事前に選択した配送先住所または支払い方法を変更できま
す。この場合、ウィジェットはデバイスの高さと幅に合わせて展開されます。購入者が選択すると、ウィ
ジェットは自動的に折りたたまれ、購入者はチェックアウトを続行できます。
折りたたみ可能ウィジェットをインテグレーションするには、次の手順に従います。
1. スマートフォン用に最適化された各ページのheadセクションにメタタグを追加します。
これにより、ウィジェットのサイズが変更され、スマートフォンで読みやすくなり、ユーザ
ーがページをズームする必要もなくなります。
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale
=1.0"/>
2. 次の例に示すように、AddressBookウィジェットまたはWalletウィジェットを作成する
コードを変更し、designModeパラメーターをsmartphoneCollapsibleに設定します。
new OffAmazonPayments.Widgets.AddressBook({ sellerId :
'YOUR_SELLER_ID_HERE', onOrderReferenceCreate: function(orderReference) {
},
design : {
designMode: 'smartphoneCollapsible'},
onAddressSelect : function(orderReference) {
},
onError : function(error) {
}
}).bind("addressBookWidgetDiv");
上記の例は、AddressBookウィジェットを変更する方法を示しています。Walletウィジェットや、読み取り
専用のAddressBookウィジェットとWalletウィジェットでも同じように変更する必要があります。折りたた
み可能ウィジェットの幅と高さを指定することはできません。
次の例は、購入者が折りたたみ可能ウィジェットをどのように操作するかを示しています。
•
•
•
図1：折りたたまれているAddressBookウィジェットとWalletウィジェットに示すように、ウィジ
ェットは、最初は折りたたまれています。ウィジェットには、デフォルトの配送先住所と支払い
方法が表示されます。
購入者が配送先住所と支払い方法を変更したい場合は、該当する「変更」ボタンをクリックしま
す。図2：展開されたAddressBookウィジェットに示すように、ウィジェットが展開され、画面全
体に表示されます。
購入者が別の配送先住所または支払い方法を選択するか、「キャンセル」ボタンをクリックす
ると、図1：折りたたまれているAddressBookウィジェットとWalletウィジェットに示すよう
に、ウィジェットは、再び折りたたまれます。
56
図1：折りたたまれている
AddressBookウィジェットとWallet
ウィジェット
57
図2：展開されたAddressBookウィジェット
57
58
複雑な支払いシナリオへの対応
このセクションでは、作業の開始手順で説明した支払いシナリオよりも複雑な支払いシナリオへの対応
方法について説明します。次の支払いシナリオについて説明します。
•
•
•
分割決済
代金後払い
即時請求
分割決済
分割決済シナリオでは、注文に対する合計支払い額を複数回に分けて支払います。たとえば、受注生産
の独自商品を提供する場合に、支払い額の一部を前もって取得し、注文の完了時に残りの支払いをキャ
プチャーしたいとします。
また、購入者の注文を複数回に分けて発送や発送ごとに資金をキャプチャーする場合に、分割決済が便利
になる場合もあります。この支払いモデルは、次の図に示すように、Amazon ログイン & ペイメントでサ
ポートされています。
この例では、Order Referenceオブジェクトが注文時に確認され、7日以内に最初の配送が行われます。
最初のキャプチャーは、初回の発送時にリクエストできます。その後30日が経過した時点で、Authorizeオ
ペレーションを再度呼び出します。最後に、2回目の発送時に、Captureオペレーションをもう一度呼び出
します。
Amazon ログイン & ペイメントでは、Order Referenceオブジェクトに対して最大10のAuthorizeリク
エストを送信し、これらの支払いイベントをセラーの内部ビジネスプロセスにマッピングできるよう
にすることで、このような分割決済のシナリオに対応します。キャプチャーなしのDeclinedまたはCl
osedのオーソリは、この上限にはカウントされません。
代金後払い
代金後払いのシナリオでは、購入者がオンラインで注文しても、特定のマイルストーンに到達するまでは、
支払いはキャプチャーされません。たとえば、購入者が商品を事前注文できるようにした場合や、商品が取
り寄せ注文の場合は、商品が発送されるまで支払いを回収しないビジネスポリシーを設定できます。
取り寄せ注文品が発送された時点で支払いを回収するようにセラーの会社のポリシーで設定している場合
は、商品の在庫確認後、商品の発送時にCaptureオペレーションを呼び出すまでは、Authorize呼び出しを実行
しません。代金後払いのシナリオは、次の図のようになります。
58
59
この図は、注文後、Order Referenceオブジェクトが確認されたが、商品の在庫確認後、出荷準
備ができるまで、Authorizeオペレーションが呼び出されていないことを示しています。事前注文の商品
が購入者に出荷されると、Captureオペレーションの呼び出しが実行されます。
Amazon ログイン & ペイメントでは、確認されたOrder Referenceオブジェクトを本番モードとテストモ
ードの両方で180日間Openにすることで、これらのシナリオに対応します。この180日の期間中に、購入者
は注文を行うことができますが、注文の発送と支払いの回収の準備ができるまで、Authorizeオペレーション
の呼び出しを実行する必要はありません。
即時請求
注文後に購入者に即時請求したいケースで、注文内容を確定してAmazonに通知している場合は、Authorizeオ
ペレーションをただちに呼出すことができます。AuthorizationオブジェクトがOpen状態になったら、Captu
reオペレーションを呼び出します。または、Authorizeオペレーションを呼び出し、CaptureNowリクエストパ
ラメーターをtrueに設定することもできます。このアプローチは、注文後すぐに(当日など)商品を出荷する
場合に便利です。
この支払いシナリオは、次の図のようになります。
この図は、購入者が注文を確定し、Order Referenceが確認されたらすぐに請求が発生することを示し
ています。商品は購入者にただちに発送されます。
注：Amazon ペイメントポリシーでは、注文商品が出荷された時点で購入者に請求すると定めてい
ます。注文の出荷前に資金を回収しないでください。
59
60
購入後に注文が変更された場合の支払いへの対応
Amazon ログイン & ペイメントでは、購入者がチェックアウトプロセスに正常に移行した後でも、
購入の詳細を変更できます。この変更シナリオは、Amazon ログイン & ペイメントでサポートされてお
り、サポート内容は次のとおりです。
•
•
•
•
元の注文金額よりも多額を請求
配送先住所を変更
注文をキャンセルまたは終了
注文の一部を出荷
元の注文金額よりも多額を請求
購入者がセラーのWebサイトで行った注文に対して、購入者への合計請求額の調整や増額が必要になるシ
ナリオもあります。たとえば、購入者がカスタマーサービスセンターに電話し、配送オプションのアップ
グレードを依頼するような場合です。
元の注文金額よりも多くの金額を請求する必要がある場合、Amazon ログイン & ペイメントでは、Open
のOrder Referenceオブジェクトで最初に指定した金額の15%または8,400円 (どちらか少ないほう)を上
限として請求するオーソリを取得できます。
サンプルのシナリオ – 支払いの増額
この支払い増額のシナリオを説明するために、購入者がチェックアウトプロセスをすべて終えて、20,
000円の注文(商品の金額に税金と配送費を加えた金額)を確定するとします。注文の発送前に、購入者
はセラーのカスタマーサービスセンターに電話し、高額の配送オプションへのアップグレードを依頼
したので、合計金額は23,000円になりました。
このシナリオでは、セラーは23,000円のAuthorizeオペレーションを呼び出すか、元の金額の20,000円がすで
にオーソリ処理されている場合は、3,000円のAuthorizeオペレーションを呼び出します。増額分の3,000円
は、元のOrder Referenceオブジェクトの金額の15%に相当するため、23,000円の金額は許可されます。
注：チャージバックとAmazonマーケットプレイス保証が発生する可能性を減らすために、元の注文
金額よりも多い金額を請求する前に購入者からのオーソリを確保することをお勧めします。また、
更新した注文情報のEメールを購入者に送信し、このEメールを記録しておくようにしてください。
配送先住所を変更
購入者がセラーに対して、Amazon ペイメントAddressBookウィジェットで指定している住所とは異なる配
送先住所を注文に使用するようにリクエストしている場合は、Amazonに通知する必要はありません。セラ
ーは、変更に関する情報をAmazonに渡さずに、自身の注文出荷プロセスで住所を変更できます。
注：AddressBookウィジェット経由で、Amazonで指定されていない配送先住所を使用する場合、Ama
zon ペイメント保護ポリシーの対象にはなりません。配送先住所の変更による保証内容への影響に
ついて詳しくは、支払い保護ポリシーを参照してください。
注文をキャンセルまたは終了
注文のキャンセルが必要な場合、または注文の出荷を完了している場合は、Order Referenceオブジェクトを
キャンセルまたは終了し、自社の経理など注文ステータスを追跡する内部処理に対応できるようにしてくだ
さい。
60
61
Amazon ログイン & ペイメントでは、CancelOrderReferenceまたはCloseOrderReferenceオペレーションのいずれか
を使用して、Order Referenceオブジェクトのステータスを変更できます。
次のリストは、CloseOrderReferenceオペレーションとCancelOrderReferenceオペレーションの呼び出しの違いを示
しています。
•
CloseOrderReference - OpenまたはSuspended状態のOrder ReferenceオブジェクトをClosedとマークす
るには、このオペレーションを呼び出します。この操作は、注文の全額を請求し、それ以上のオー
ソリをリクエストしない場合に実行します。注文の一部しか出荷できない場合でも、該当の金額の
請求後に、Order ReferenceオブジェクトをClosedとマークしてください。Amazonでは、この情報を
使用して、注文の支払いがCompletedしたことを購入者に通知します。Order Referenceオブジェク
トは、CloseOrderReferenceオペレーションを呼び出すことで終了されます。
Openなオーソリに対してキャプチャーを実行できますが、Order Referenceオブジェクトに
新しいオーソリを作成することはできません。
o Order Referenceオブジェクトに対して返金を実行することができます。
CancelOrderReference - Draft、Open、またはSuspended状態のOrder ReferenceオブジェクトをC
anceledとマークするには、このオペレーションを呼び出します。ただし、Pending、Complete
d、またはClosedキャプチャーがないことが条件です。この操作は、注文をすべてキャンセル
し、その金額を請求しない場合に実行します。Amazonでは、この情報を使用して、この注文の
支払いがキャンセルされたことを購入者に通知します。Order Referenceオブジェクトは、Canc
elOrderReferenceオペレーションを呼び出すことでキャンセルされます。
o
•
o
o
新しいオーソリをOrder Referenceオブジェクトに作成することはできません。Openまたは
Pending状態の既存のオーソリはClosedされます。
注：Order Referenceオブジェクトをキャンセルできるのは、Completed、クローズ、または
Pendingのキャプチャーがない場合のみです。
CloseOrderReferenceオペレーション
CloseOrderReferenceオペレーションは、購入者の注文の出荷完了後に該当の金額を請求し、Order Refere
nceオブジェクトをClosedとマークして、内部の注文ステータスとOrder Referenceオブジェクトを同期
する場合に便利です。
次の例は、CloseOrderReferenceオペレーションの呼び出し方法を示しています。
&Action=CloseOrderReference
&SignatureVersion=2
&Timestamp=2013-12-19T19%3A01%3A11Z
&Version=2013-01-01
リクエストパラメーターと応答要素を含む、CloseOrderReferenceオペレーションについて詳しくは、Off
-Amazon Payments APIセクションリファレンスの「CloseOrderReference」を参照してください。
この応答に加えて、セラーにはインスタントペイメント通知サービスからの通知が送信されます。インス
タントペイメント通知サービスについて詳しくは、「システムとAmazon Paymentsの同期」を参照してく
ださい。
CancelOrderReferenceオペレーション
CancelOrderReferenceオペレーションは、キャンセルが必要な注文があり、Order Referenceオブジェクト
に対して支払いアクションを実行しない場合に便利です。
61
62
次の例は、CancelOrderReferenceオペレーションの呼び出し方法を示しています。
&Action=CancelOrderReference
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&SignatureVersion=2
&Timestamp=2013-12-19T19%3A01%3A11Z
&Version=2013-01-01
リクエストパラメーターと応答要素を含む、CancelOrderReferenceオペレーションについて詳しくは、
Off-Amazon Payments APIセクションリファレンスの「CancelOrderReference」を参照してください。
この応答に加えて、セラーにはインスタントペイメント通知サービスからの通知が送信されます。セラー
には、Order Referenceオブジェクトに対するOpenなオーソリの通知も送信されます。インスタン
トペイメント通知サービスについて詳しくは、「システムとAmazon ペイメントの同期」を参照してくださ
い。
注文の一部を出荷
注文の一部のみを出荷する場合は、該当の金額の請求後に、CloseOrderReferenceオペレーションを呼び出す
ことで、Order ReferenceをClosedとマークできます。また、CloseAuthorizationオペレーションを使用し
て、使用する予定のない未処理のオーソリを終了することもできます。注文内容とオーソリをClosedとマ
ークすると、内部の注文状態をAmazonと同期できます。
次の例は、CloseAuthorizationオペレーションの呼び出し方法を示しています。
&Action=CloseAuthorization
&ClosureReason=Closing%20the%20auhorization%20transaction
&SignatureVersion=2
&Timestamp=2013-12-19T19%3A01%3A11Z
&Version=2013-01-01
リクエストパラメーターと応答要素を含む、CloseAuthorizationオペレーションについて詳しくは、
Off-Amazon Payments APIセクションリファレンスの「CloseAuthorization」を参照してください。
注：注文の支払い全体を処理したら、注文内容を常に終了することをお勧めします。終了しない
と、購入者がAmazon Payments Webサイトでトランザクションを確認した場合に、注文内容がOpe
nと表示されます(180日間)。
62
63
支払い拒否への対応
オーソリ、キャプチャー、または返金時に支払いが却下されることがあります。Amazon ログイン & ペイ
メントには、このような却下の状況に対処し、購入者が支払い方法を更新または変更するのに役立つ複数
のビジネスルールがあります。次の状況について説明します。
•
•
•
却下されたオーソリ
却下されたキャプチャー
却下された返金
却下されたオーソリ
Authorizeオペレーションの呼び出しが却下されると、次の4つの理由コードのいずれかが応答に表示
されます。
• 支払方法無効 – 選択した支払い方法に問題があることを示します。この状況では、注文内
容がSuspended状態になり、インスタント通知がセラーに送信されます。次の操作を実行することをお
勧めします。
o
非同期モード
このシナリオは、購入者がすでにWebサイトを離れている場合に対処する必要があります。



o
Eメールまたは電話で購入者に連絡します。
購入者に、Amazon ログイン & ペイメント Webサイトにアクセスし、注文を検索してもら
います。ここから、購入者はWebページの指示に従って、支払い方法を更新することがで
きます。
購入者が支払い方法を更新すると、Order ReferenceオブジェクトがSuspended状態からOpen
状態になります。次に、Amazon Paymentsからセラーにインスタントペイメント通知が送信
され、購入者にも次のようなEメールが送信されます。
同期モード
購入者がセラーのWebサイトでチェックアウトフローをまだ実行している間に、この却下を処理
することをお勧めします。


購入フロー内で、セラーのWebサイトにエラーメッセージを表示し、選択した支払
い方法が却下されたことを購入者に通知します。
Amazon Paymentウィジェットをセラーのページに再表示します。
この操作を実行すると、前に選択した支払い方法がDeclinedとマークされます。購入者が
「拒否理由」リンクをクリックして、支払い方法の情報を更新や代替の支払い方法をウィ
ジェットから選択できることを示すテキストを指定できます。
63




•
•
•
64
このスクリーンショットは、Walletウィジェットの拒否情報を拒否メッセージにして購入
者に表示される例です。
購入者が支払い方法を更新するか、新しい支払い方法を選択すると、onPaymentSelectコール
バックがペイメントウィジェットからトリガーされます。
購入者は、最終選択する前に、ウィジェットで複数の支払い方法をクリックできます。
UXフローに従い、購入者が「注文する」、「更新」、または同様のボタンをクリック
して最終選択したら、ConfirmOrderReference APIを呼び出します。これにより、Order Refer
enceはSuspended状態からOpen状態になります。ステータスの変更を示すインスタントペイ
メント通知がセラーに送信されます。あるいはGetOrderReferenceを呼び出して、更新された
注文ステータスを取得することもできます。
注文がOpen状態の場合は、Authorize APIを使用して、新しいオーソリを試みることができます。
購入者には、「支払い情報更新のEメール」に示すようなEメールが送信されます。
AmazonRejected – Amazonの決定により、Authorizeオペレーション呼び出しが却下されたことを
示します。Authorizeオペレーションのリクエストを再試行できるのは、Order Referenceがまだオープン
状態の場合のみです。
ProcessingFailure - 内部の処理エラーにより、Amazonがトランザクション処理できなかったこ
とを示します。1～2分待ってからリクエストを再試行してください。
TransactionTimedOut
o 非同期モードでは、Authorizeオペレーション呼び出しが、デフォルトのタイムアウト時間
の24時間以内、またはTransactionTimeoutリクエストパラメーターで指定した時間内に処
理されなかったことを示します。
o 同期モードでは、Amazonがリクエストを6～8秒で処理できなかったことを示します。
この理由コードにより、却下数が多くなる場合は、非同期モードでタイムアウト値を調整してみ
るか、同期モードを使用している場合は、非同期モードの使用を検討してください。同期モード
でこのエラーを処理する別の方法は、非同期モードでトランザクションを再試行することです。
却下されたキャプチャー
Captureオペレーション呼び出しが却下されると、次の2つの理由コードのいずれかが応答に表示されます。
•
•
AmazonRejected – Amazonの決定により、Captureオペレーション呼び出しが却下されたことを示しま
す。Amazonがキャプチャーを拒否すると、AuthorizationオブジェクトとOrder Referenceオブジェクト
も終了になる可能性があります。オーソリが終了すると、それ以上のキャプチャーリクエストも却下さ
れます。Order ReferenceがまだOpen状態の場合は、新しいオーソリをリクエストし、オーソリのキャ
プチャーをリクエストします。
ProcessingFailure - 内部の処理エラーにより、Amazonがトランザクション処理できなかったことを示
します。1～2分待ってからリクエストを再試行してください。
Order ReferenceオブジェクトがまだOpenの場合は、新しいAuthorizeオペレーション呼び出しの送信後に、
新しいCaptureオペレーション呼び出しを送信することをお勧めします。
却下された返金
Refundオペレーション呼び出しが却下されると、次の2つの理由コードのいずれかが応答に表示されます。
•
•
AmazonRejected – Amazonの決定により、Refundオペレーション呼び出しが却下されたことを示します。
この場合は、返品と同金額分のポイントを発行するなど、別の方法で返金を発行するように購入者に対
応してください。
ProcessingFailure - 次のいずれかを示します。
o
o
内部エラーにより、Amazonがトランザクションを処理できなかった。
購入者がすでにAmazonマーケットプレイス保証申請またはチャージバックから返金を受け取って
いる。
64
65
応答でProcessingFailureの理由コードが通知された場合は、セラーセントラルの「パフォーマンス」タ
ブで、その注文のAmazonマーケットプレイス保証申請またはチャージバックステータスを最初に確認し
てください。Amazonマーケットプレイス保証申請またはチャージバックが購入者に発行されていない場
合、およびCaptureオブジェクトがまだCompleted状態の場合は、1～2分後にリクエストを再試行してく
ださい。再試行が成功しない場合は、購入者に連絡し、別の方法で返金を発行します。
65
66
システムとAmazon Paymentsの同期
支払いオブジェクトの状態遷移
Amazon ログイン & ペイメントオブジェクト(Order Referenceオブジェクト、Authorizationオブジェク
ト、Captureオブジェクト、およびRefundオブジェクト)は、支払いプロセスの一部としてさまざまな状
態に遷移します。これらの状態遷移は、システムまたは内部のAmazonビジネスルールで実行される特定
のオペレーションによって発生します。たとえば、非同期モードでリクエストされるAuthorizationオブ
ジェクトは、処理中は最初にPending状態に移行します。処理が完了すると、Open状態になります。この
状態は、資金の回収の準備ができたことを示します。Authorizationオブジェクトがキャプチャーされる
と、Closed状態になります。この状態は、そのオーソリに対してキャプチャーできる資金がないことを
示します。または、30日以内にオーソリをキャプチャーしない場合は、Closedとマークされます。イン
テグレーションエラーを防ぐには、システムとAmazonの支払いオブジェクトの現在の状態を同期するよ
うにしてください。
支払いオブジェクトの状態遷移について詳しくは、Off-Amazon Payments APIセクションリファレンスを
参照してください。
支払いオペレーションの非同期モード
非同期モードでは、AuthorizeリクエストとRefundリクエストはリアルタイムで処理されません。これらの呼
び出しの最初の応答では、常にPendingの状態が返されます。キャプチャーがオーソリから7日以内にリク
エストされると、キャプチャーはリアルタイムで処理されます。この期間中に、キャプチャーリクエスト
の最初の応答で、CompletedまたはDeclinedの状態が返されます。オーソリから8日目以降にキャプチャー
がリクエストされると、CaptureオペレーションでPending状態が返されます。これらのオブジェクトは、Am
azonがリクエストを処理するまでPending状態のままです。
次の表は、Authorize、Capture、およびRefund のAPI呼び出しに対する最初の応答を示しています。
APIコール
APIコールからの最初のレスポンス
Authorize
非同期モード: O p e n か D e c l i n e d のどちらか
同期モード: 常に P e n d i n g
Capture
CompletedかPendingかDeclinedのどれか
Refund
常にPending
処理が完了すると、Amazonから非同期のインスタントペイメント通知が送信され、処理結果が通知されま
す。これにより、後述のOff-Amazon Payments APIセクションのオペレーションを使用して、これらの支
払いオブジェクトのステータスと詳細に対してクエリーを実行できます。
支払いオブジェクトの状態遷移の監視
インスタントペイメント通知(IPN)を使用すると、支払いオブジェクトの状態遷移を監視できます。
IPNは、支払いオブジェクトの状態の変更を自動的に通知します。インスタントペイメント通知(IP
N)を受信すると、GetOrderReferenceDetails、GetAuthorizationDetails、GetCaptureDetails、またはGetRefu
ndDetailsの各オペレーションを使用してサービスをポーリングし、支払いオブジェクトの詳細を確
認できます。
インスタント通知の例
Amazonは、支払いオブジェクトのいずれかの状態、またはOrder Referenceオブジェクトの状態が変化し
たときに、セラーに通知します。このような通知が届いても、セラー側では特に何もする必要はありませ
んが、注文管理に使用している内部追跡システムやフルフィルメントシステムの更新に使用できます。
66
67
セラーセントラルの通知エンドポイントは、「設定」タブの「インテグレーション設定」ページで設定でき
ます。
たとえば、AuthorizationオブジェクトがPending状態からOpen状態に遷移したことを伝える通知をAmazon
から受け取ることがあります。この遷移は、Authorizeオペレーション呼び出しが成功し、その支払いが正常
にオーソリされたことを確認できたため、注文出荷を処理できることを示します。
通知の受領後ただちに「200 OK」の応答をAmazonに送信するように、エンドポイントを構成してくださ
い。この応答を送信しない場合、またはSNSメッセージの送信時にサーバーが停止している場合は、Ama
zon SNSが1時間おきに再試行を実行します(14日間)。
インスタント通知のフォーマットについて詳しくは、Amazon SNS Getting Started Guideの「HTTP/HTT
PS Notification JSON Format」を参照してください。このガイドは、Amazon AWSドキュメントポータ
ルから入手できます。
インスタント通知で返されるNotificationDataメンバーの内容は、XSD (https://amazonpayments.s3.amaz
onaws.com/documents/payments_ipn.xsd)で公開されています。
Amazonから送信されるすべてのインスタント通知は署名されます。署名の確認方法について詳しくは、Ama
zon SNS Getting Started Guideの「Verifying the Signatures of Amazon SNS Messages」を参照してく
ださい。このガイドは、Amazon AWSドキュメントポータルから入手できます。
以下は、Amazonから送信される通知のリストです。
•
•
•
•
OrderReferenceNotification
AuthorizationNotification
CaptureNotification
RefundNotification
次の例は、OrderReferenceNotificationを示しています。
POST / HTTP/1.1
x-amz-sns-message-type: Notification
x-amz-sns-message-id: 432f33bf-9f84-5004-815f-7a6cfEXAMPLE
x-amz-sns-topic-arn: arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic
x-amz-sns-subscription-arn:
arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic: EXAMPLE
Content-Length: 961
Content-Type: text/plain; charset=UTF-8
Host: ec2-EXAMPLE.compute-1.amazonaws.com
Connection: Keep-Alive
User-Agent: Amazon Simple Notification Service Agent
{
"Type" : "Notification",
"MessageId" : "cf5543af-dd65-5f74-8ccf-0a410EXAMPLE",
"TopicArn" : "arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic",
"Message" :
"{\"NotificationReferenceId\":\"32d195c3-a829-4222-b1e2-14ab2EXAMPLE\",
\"NotificationType\":\"OrderReferenceNotification\",
\"SellerId\":\"YOUR_SELLER_ID_HERE\",
\"ReleaseEnvironment\":\"Sandbox\",
\"Version\":\"2013-01-01\",
\"NotificationData\":
\"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>
<OrderReferenceNotification
xmlns=\\\"https://mws.amazonservices.jp/
ipn/OffAmazonPayments/2013-01-01\\\">\\n
<OrderReference>\\n
<AmazonOrderReferenceId>
S23-1234567-1234567
<\\/AmazonOrderReferenceId>\\n
<OrderTotal>\\n
<Amount>106.00<\\/Amount>\\n
<CurrencyCode>USD<\\/CurrencyCode>\\n
<\\/OrderTotal>\\n
67
68
<OrderReferenceStatus>\\n
<State>CLOSED<\\/State>\\n
<ReasonCode>SellerClosed<\\/ReasonCode>\\n
<LastUpdateTimestamp>
2013-04-01T10:49:59.532Z
<\\/LastUpdateTimestamp>\\n
<\\/OrderReferenceStatus>\\n
<CreationTimestamp>2013-03-30T09:58:51.234Z<\\/CreationTimestamp>\\n
<ExpirationTimestamp>
2013-04-06T09:58:51.234Z
<\\/ExpirationTimestamp>\\n
<\\/OrderReference>\\n
<\\/OrderReferenceNotification>\",
\"Timestamp\":\"2013-04-22T06:00:14Z\"}",
"Timestamp" : "2013-04-22T06:00:15.108Z",
"SignatureVersion" : "1",
"Signature" : "deako5R0...CVmPQOI=",
"SigningCertURL" : "https://sns.EXAMPLE.amazonaws.com/
SimpleNotificationService-f3ecfb7224c7233fe7bb5f59fEXAMPLE.pem",
"UnsubscribeURL" : "https://sns.EXAMPLE.amazonaws.com/
?Action=Unsubscribe
&SubscriptionArn=arn:aws:sns:EXAMPLE:59860EXAMPLE:TestTopic:GUID"
}
次の例は、AuthorizationNotificationを示しています。
POST / HTTP/1.1
x-amz-sns-message-id: 6f7e123e-49c9-5c9d-a389-5bed0EXAMPLE
Content-Length: 961
{
"Message" :
"{\"NotificationReferenceId\":\"32d195c3-a829-4222-b1e2-14ab28909513\",
\"NotificationType\":\"PaymentAuthorize\",
\"Version\":\"2013-01-01\",
<AuthorizationNotification
<AuthorizationDetails>\\n
<AmazonAuthorizationId>
S23-1234567-1234567-0000001
<\\/AmazonAuthorizationId>\\n
<AuthorizationReferenceId>
9bbe88cd5ab4435b85d717fd8EXAMPLE
<\\/AuthorizationReferenceId>\\n
<AuthorizationAmount>\\n
<\\/AuthorizationAmount>\\n
<CapturedAmount>\\n
68
69
<\\/CapturedAmount>\\n
<AuthorizationFee>\\n
<\\/AuthorizationFee>\\n
<IdList/>\\n
<ExpirationTimestamp>
2013-05-22T05:59:38.186Z
<\\/ExpirationTimestamp>\\n
<AuthorizationStatus>\\n
<State>Open<\\/State>\\n
2013-04-22T06:00:11.473Z
<\\/AuthorizationStatus>\\n
<OrderItemCategories/>\\n
<CaptureNow>false<\\/CaptureNow>\\n
<SoftDescriptor/>\\n
<\\/AuthorizationDetails>\\n
<\\/AuthorizationNotification>\",
\"Timestamp\":\"2013-04-22T06:00:14Z\"}",
"Timestamp" : "2013-04-22T06:00:15.108Z",
"Signature" : "W/cfaDzC...5glwqJk=",
?Action=Unsubscribe
}
次の例は、CaptureNotificationを示しています。
POST / HTTP/1.1
x-amz-sns-message-id: 64f5f75c-5799-53e5-b4c3-be8f1EXAMPLE
Content-Length: 961
{
"Message" :
\"NotificationType\":\"PaymentCapture\",
\"Version\":\"2013-01-01\",
<CaptureNotification
<CaptureDetails>\\n
<AmazonCaptureId>S23-1234567-1234567-0000002<\\/AmazonCaptureId>\\n
69
70
<CaptureReferenceId>
6f4d9dea0c234279a65e77994EXAMPLE
<\\/CaptureReferenceId>\\n
<CaptureAmount>\\n
<\\/CaptureAmount>\\n
<RefundedAmount>\\n
<\\/RefundedAmount>\\n
<CaptureFee>\\n
<\\/CaptureFee>\\n
<IdList/>\\n
<CaptureStatus>\\n
<State>Completed<\\/State>\\n
2013-04-22T06:02:25.227Z
<\\/CaptureStatus>\\n
<SoftDescriptor>AMZ*softdescriptor<\\/SoftDescriptor>\\n
<\\/CaptureDetails>\\n
<\\/CaptureNotification>\",
\"Timestamp\":\"2013-04-22T06:00:14Z\"}",
"Timestamp" : "2013-04-22T06:00:15.108Z",
"Signature" : "dUWd9lrs...iNGKnR4=",
?Action=Unsubscribe
}
次の例は、RefundNotificationを示しています。
POST / HTTP/1.1
x-amz-sns-message-id: 5f43584c-1f96-5880-9c98-119f5EXAMPLE
Content-Length: 961
{
"Message" :
\"NotificationType\":\"PaymentRefund\",
\"Version\":\"2013-01-01\",
<RefundNotification
70
71
<RefundDetails>\\n
<AmazonRefundId>S23-1234567-1234567-0000003<\\/AmazonRefundId>\\n
<RefundReferenceId>
07fff0c4e05046958db7e47607e7db17
<\\/RefundReferenceId>\\n
<RefundType>SellerInitiated<\\/RefundType>\\n
<RefundAmount>\\n
<\\/RefundAmount>\\n
<FeeRefunded>\\n
<\\/FeeRefunded>\\n
<RefundStatus>\\n
<State>Completed<\\/State>\\n
2013-04-22T06:09:20.178Z
<\\/RefundStatus>\\n
<SoftDescriptor>AMZ*softDescriptor<\\/SoftDescriptor>\\n
<\\/RefundDetails>\\n
<\\/RefundNotification>\",
\"Timestamp\":\"2013-04-22T06:00:14Z\"}",
"Timestamp" : "2013-04-22T06:00:15.108Z",
"Signature" : "kjac14DH...oQT6FbA=",
?Action=Unsubscribe
}
APIのポーリングの例
次の例は、GetAuthorizationDetailsオペレーションを呼び出してAuthorizationオブジェクトのステータスを取
得する方法を示しています。
&Action=GetAuthorizationDetails
&SignatureVersion=2
&Timestamp=2013-12-19T19%3A01%3A11Z
&Version=2013-01-01
リクエストパラメーターと応答要素を含む、GetAuthorizationDetailsオペレーションについて詳しくは、OffAmazon Payments APIセクションリファレンスの「GetAuthorizationDetails」を参照してください。
IPNの処理のベストプラクティス
Amazonは、支払いオブジェクトのいずれかの状態、またはOrder Referenceオブジェクトの状態が変化し
たときに、セラーに通知します。このような通知が届いても、セラー側では特に何もする必要はありませ
んが、注文管理に使用している内部追跡システムやフルフィルメントシステムの更新に使用できます。
IPNの受信後のベストプラクティスは、通知を受信した各オブジェクトに対して、Getオペレーション
を実行することです。Getオペレーションの応答を使用して、システムを更新できます。
71
72
セラーが提供可能な購入者向けのEメールの内容
Amazonでは、次の状況で購入者にEメールを送信します。
•
•
Order Referenceオブジェクトが確認された場合。
返金がキャプチャーされる時点。
•
返金が発行される時点。
•
支払い方法が変更される時点。
Eメールの内容の大部分はAmazonが提供しますが、メッセージの本文内には、セラーが指定できるさまざま
な要素があります。次の表は、APIオペレーションパラメーターのアカウント設定に基づいてセラーが定義
できる、購入者向けのEメールの内容の一覧です。
Eメールのフィールド
ソース
セラーのカスタマーサービスのEメールアドレス
AmazonセラーアカウントかSellerCentralのアカウント情報の設定
で指定されます。
(Seller customer service e-mail address)
セラーのカスタマーサービスの電話番号
(Seller customer service phone number)
AmazonセラーアカウントかSellerCentralのアカウント情報の設定
で指定されます。
(Seller store name)
AmazonセラーアカウントかSellerCentralのアカウント情報
の設定で指定されます。SetOrderReferenceDetailsオペレ
ーションの要求パラメーターで指定したストア名でオーバ
ーライドできます。
セラーの注文ID
SetOrderReferenceDetailsオペレーションの要求リクエストしたS
ellerOrderIdが指定されます。
セラーのストア名
(Seller order identifier)
注文合計金額
(Total order amount)
注文日
(Order date)
セラーのメモ
(Seller note)
SetOrderReferenceDetailsオペレーションの要求リクエストしたO
rderTotalが指定されます。
Order Referenceオブジェクトが確認また、Open状態に移動
した時のタイムスタンプ
SetOrderReferenceDetailsオペレーション、Authorizeオ
ペレーション、Captureオペレーション、Refundオペレー
ションの要求パラメーター内のSellerNoteが指定されま
す。
72
73
テスト環境とのインテグレーションのテスト
Amazon ログイン & ペイメントテスト環境では、Amazon ログイン & ペイメント支払いオプションで本番
環境に移行する前に、Amazon ログイン & ペイメントテストインテグレーションを徹底的にテストできま
す。テストモードで実装をテストしている場合は、セラーのWebサイトでAmazon ペイメントウィジェット
の購入者の操作をシミュレートできます。
テストモードでは、AmazonへのAPIオペレーション呼び出しをテストすることもできます。このテストでは、
呼び出しが適切に構成されていることを確認し、注文全体の追跡に必要なすべての支払いパラメーターが応
答に含まれていることを確認できます。テスト環境では、支払い却下やブラウザーのCookieタイムアウトな
ど、さまざまなエラー条件をシミュレートし、チェックアウト中に問題が発生した場合の購入者の操作を適
切に管理することもできます。
購入者アカウントのテスト
セラーセントラル経由でテスト環境に初めてアクセスする場合は、インテグレーションをテストできるよう
に、テスト用の購入者アカウントを構成することをお勧めします。これらのテストアカウントは、出荷可能
な場所に関する会社のビジネスルールに違反している可能性のある配送先住所を追加した場合など、利用ケ
ースに合わせて変更できます。これらのアカウントをセラーセントラルから構成するには、「インテグレー
ション」タブに移動し、「テストアカウント」を選択します。
セラーセントラルから可能なカスタマイズについては、複数のテスト用購入者アカウントに対応できるよ
うに、多くのシナリオをテストすることをお勧めします。
テスト環境と本番環境の違い
Amazon ログイン & ペイメントで使用されるさまざまなオブジェクトは、オブジェクトの作成から有効
期限が切れるまでの時間など、一連のビジネスルールですべて管理されます。Amazon ログイン & ペイメ
ントテスト環境のテスト用に、次のビジネスルールが用意されています。
オブジェクト
本稼働のビジネスルール
テスト環境のビジネスルール
Open状態の認証オブジェクト
30日後にClosed状態に変更
2日後にClosed状態に変更
テストのシミュレーション
Amazon ログイン & ペイメントテスト環境は、特定の支払いシナリオのシミュレーションに使用で
きます。これらのシミュレーションでは、セラーのビジネスプロセスのテストに使用可能な応答を生
成できます。次の表は、特定の応答と状態遷移をどのようにシミュレートできるかをまとめたもので
す。状態と理由コードについて詳しくは、Off-Amazon Payments APIセクションリファレンスを
参照してください。
注：シミュレーション文字列で使用可能な状態と理由コードでは、必要な状態と理由コードを、Off
-Amazon Payments APIセクションのオペレーション呼び出しに指定する必要があります。組み合わ
せが無効な場合は、InvalidSandboxSimulationSpecifiedエラーになります。
さまざまなオブジェクト状態と理由コードをシミュレートするには：
Order Reference オブジェクト
状態
理由コード
Draft
シミュレーション文字列
テスト環境のシミュレーション
N/A
テスト環境のボタンをクリ
ックするか、承認されたテ
スト購入者アカウントでサ
インインします。これはDr
aft状態のOrder Reference
オブジェクトを生成しま
す。
73
Open
74
N/A
ConfirmOrderReferenceオペレー
ションによって呼び出されたDraf
tのOrder Referenceオブジェクト
を認証する。
理由コードInvalidPaymentM
ethodである場合にAuthoriz
ationオブジェクトをDeclin
ed状態に移動するようシミ
ュレーションした後に、Ord
er Referenceオブジェクト
はSuspended状態に移動しま
す。
CanceledはCancelOrderReference
オペレーションが呼び出されるこ
とによる、OpenまたはPendingのO
rder Referenceオブジェクトで
す。
Suspended
InvalidPaymentMethod
N/A
Canceled
SellerCanceled
N/A
Stale
N/A
DraftのOrder Referenceオブジェク
トが生成されてから3時間以内に確
認されていない。この場合にOrder
Referenceオブジェクトはステイル
(Stale)状態に移動します。
AmazonCanceled
N/A
テストすることはできません。.
Expired
N/A
OpenまたはPendingのOrder Refer
enceオブジェクトは、生成されて
から180日後にこの理由コードでA
mazonがClosedします。
MaxAmountCharged
N/A
Captureオペレーション呼び出しに
よって、Order Referenceオブジェ
クトの金額が、15%か8,400円（ど
ちらか少ない方）以上のキャプチ
ャーをします。
MaxAuthorizationsCaptured
N/A
OpenのOrder Referenceオブジ
ェクトを全部または部分的に10
回キャプチャーの認証を繰り返
します。
AmazonClosed
{"SandboxSimulation":
Closed
{"State":"Closed", "Rea
sonCode":"AmazonClosed"}}
SellerClosed
OpenのOrder Referenceオブジェク
トにCloseOrderReferenceオペレー
ションのClosureReasonのリクエス
トパラメータ値を指定します。
N/A
AmazonClosed理由コードの文字列
を指定なしでCloseOrderReference
オペレーションを呼び出すこと
で、OpenのOrder Referenceオブジ
ェクトをClosedします。
N/A
全てのAuthorizationオブジェクト
は認証要求を確定してから30秒後の
Pending状態です。これは同期モー
ドではシミュレーションすることは
できません。
Authorization オブジェクト
状態
理由コード
Pending
74
Open
Declined
N/A
InvalidPaymentMethod
Authorizeオペレーションを呼び出
すことで認証を要求します。非同
期モードは、Authorizationオブジ
ェクトで30秒経ったPending状態の
残りをOpen状態に移動します。同
期モードは、Authorizeオブジェク
トはすぐにOpen状態に移動しま
す。
{"State":"Declined", "Re
asonCode":"InvalidPaymentMethod", "PaymentMeth
odUpdateTimeInMins":5}}
AmazonRejected
AuthorizeオペレーションのSellerA
uthorizationNoteリクエストパラメ
ーターの値を指定します。Order Re
ferenceは、それから保留状態からO
pen状態に移動します。Order Refer
enceオブジェクトをOpen状態から保
留状態に戻さなければならない場合
は、PaymentメソッドのUpdateTimeI
nMinsパラメータで1～240分の間で
時間指定して利用することができま
す。この購入者の更新シミュレーシ
ョンは無効な支払方法です、また、
Order ReferenceオブジェクトはOpe
n状態に戻ります。
asonCode":"AmazonRejected"}}
AuthorizeオペレーションのSeller
AuthorizationNoteリクエストのパ
ラメーターを指定します。
ProcessingFailure
N/A
テストすることはできません。
TransactionTimedOut
asonCode":"TransactionTimedOut"}}
Closed
75
ExpiredUnused
{"State":"Closed", "Re
asonCode":"ExpiredUnused", "ExpirationTimeIn
Mins":1}}
MaxCapturesProcessed
N/A
AmazonClosed
AuthorizeオペレーションのSellerA
uthorizationNoteリクエストのパ
ラメーターを指定します。Authoriz
ationオブジェクトがClosedしなけ
ればならない時間をExpirationTim
eInMinsパラメータを指定して使う
ことができます。(1～60分)
Captureオペレーションを呼び出
すことでOpenAuthorizationオブ
ジェクトをキャプチャーします。
{"State":"Closed", "Re
asonCode":"AmazonClosed"}}
OrderReferenceCanceled
N/A
CancelOrderReferenceオペレー
ションを呼び出すことで、Autho
rizationオブジェクトに関連付
けされたOrder Referenceオブジ
ェクトをCanceledします。
SellerClosed
N/A
CloseAuthorizationオペレーショ
ンを呼び出すことでOpenAuthoriza
tionオブジェクトをClosedしま
す。
75
76
Capture オブジェクト
状態
理由コード
Pending
Declined
AmazonRejected
{"State":"Pending"}}
CaptureオペレーションのSellerCa
ptureNoteリクエストパラメーター
で指定します。Captureオブジェク
トは30秒間はPending状態のです。
{"ReasonCode":"AmazonRejected"}}
で指定します。
N/A
N/A
Captureオペレーションを呼び出
すことで、OpenAuthorizationオ
ブジェクトに対して資金をキャプ
チャします。
MaxAmountRefunded
N/A
Refundオペレーションを呼び出
しで、キャプチャーした金額の1
5%か8,400円（どちらか少ない
方）以上を返金します。
MaxRefundsProcessed
N/A
CompletedしたCaptureオブジェク
トに対してRefundオペレーション
を10回呼び出すことで発行しま
す。
AmazonClosed
{"State":"Declined"},
ProcessingFailure
Completed
Closed
{"ReasonCode":"AmazonClosed"}}
で指定します。
N/A
Refundオペレーションを呼び出
して返金をリクエストします。
全てのRefundオブジェクトはRe
fundリクエストを承認した後に
30秒間はPending状態になりま
す。
{"State":"Closed"},
Refund オブジェクト
状態
理由コード
Pending
Declined
AmazonRejected
{"State":"Declined", "Reas
onCode":"AmazonRejected"}}
ProcessingFailure
Completed
RefundオペレーションのSe
llerRefundNoteリクエスト
パラメーターで指定しま
す。
N/A
N/A
CompletedCaptureオブジェク
トに対してRefundオペレーシ
ョンを呼び出すことで資金を
返金します。
76
77
次の例は、オーソリのDeclined状態をInvalidPaymentMethod理由コードでどのようにシミュレートできるか
を示したものです(SellerAuthorizationNoteリクエストパラメーターを使用)。
&Action=Authorize
&AuthorizationAmount.Amount=50
&SellerAuthorizationNote=
%7B%22SandboxSimulation%22%3A%7B%22State%22%3A%22Declined%22%2C
%22ReasonCode%22%3A%22InvalidPaymentMethod%22%7D%7D
&SignatureVersion=2
&Timestamp=2013-10-03T19%3A01%3A11Z
&Version=2013-01-01
77
78
エラーの処理
Amazon PaymentsウィジェットとOff-Amazon Payments APIオペレーションは、どちらもエラーを投げ
ることができます。セラーのWebサイトで最適な購入者体験を提供するには、両方の種類のエラーを
キャッチして処理してください。
Off-Amazon Payments APIセクションのオペレーションからのエラーの処理
Off-Amazon Payments APIセクションのオペレーションからエラーが発生した場合は、エラーの内容に応じ
て、そのオペレーションを再試行できます。形式が正しくないオペレーションリクエストは、べき等にな
ります。つまり、すでに成功したリクエストで同じオペレーションを呼び出した場合は、重複したトラン
ザクションを作成しません。注文内容リクエストの場合、べき等キーはAmazonOrderReferenceIdになりま
す。オーソリ、キャプチャー、返金のリクエストの場合、べき等キーはそれぞれAuthorizationReferenceI
d、CaptureReferenceId、RefundReferenceIdになります。たとえば、同じRefundReferenceIdを指定した場
合は、同じキャプチャーオブジェクトに対して複数回返金することはできません。この機能では、下記の
表に記載した条件にエラーが一致する場合に、オペレーションを安全に再試行できます。
エラーの受信後にオペレーション呼び出しを再試行する場合は、最初のエラー応答後ただちに再試行できま
す。複数回再試行する場合は、「exponential backoff」の方法を上限まで実装することをお勧めしま
す。次に、エラーをログに記録し、手動でフォローアップと調査を行います。たとえば、1秒、2秒、4秒、1
0秒、30秒の間隔で再試行のタイミングを設定できます。実際のbackoff時間と上限は、ビジネスプロセスに
よって異なります。
次の表は、再試行可能なエラーを示しています。
HTTP コード
HTTP ステータス
説明と修正方法
500
InternalServerError
サーバーは要求を満たすのを妨げる予期しない状
態になりました。このエラーはリトライすること
は安全です。
502
Bad Gateway
ゲートウェイやプロキシーのようなクライアント
と接続先サーバーとの間のサーバーが要求を拒否
しました。この多くのケースでは断続する問題で
あり、リトライすることは安全です。この問題が
続く場合は、ネットワーク管理者に問い合わせし
てください。
503
ServiceUnavailable
RequestThrottled
サーバサイド上の予期せぬ問題であるか、サ
ーバーが過度のトランザクションクオートで
スロットルされました。スロットルリングの
詳しい説明は、Amazon MWS 開発者ガイドの
「スロットルリング：リクエストを送信でき
る頻度を制限する」を参照してください。ク
ライアントはリクエストのリトライか、リク
エストの回数を減らさなければなりません。
504
Gateway Timeout
ゲートウェイやプロキシーのようなクライアント
と接続先サーバーとの間のサーバーが要求をタイ
ムアウトしました。この多くのケースでは断続す
る問題であり、リトライすることは安全です。
詳しくは、Off-Amazon Payments APIセクションリファレンスの「エラーコード」を参照してください。
78
79
Amazon ログイン & ペイメントウィジェットからのエラーの処理
「ステップ1 - 購入者の認証用ボタンウィジェットの追加」で説明したように、エラー条件を通知でき
るようにボタン、AddressBook、およびWalletのウィジェットを構成することができます。これらのウ
ィジェットは、特定のインテグレーションエラーが発生した場合に、エラー通知を送信します。次のサ
ンプルコードは、エラーに関連するerrorCodeとerrorMessageをどのように読み取り、テキストフィー
ルドに表示できるかを示しています。これらのエラーコードにより、インテグレーションをより早くデ
バッグできるようになり、ログに記録されている場合は、本番サイトで発生する可能性のある問題を通
知できます。
<label>Debug Error Code
<div id="errorCode"></div>
<br>
<label>Debug Error Message
<div id="errorMessage"></div>
:</label>
:</label>
<script>
var amazonOrderReferenceId;
new OffAmazonPayments.Widgets.Button ({
onSignIn: function(orderReference) {
amazonOrderReferenceId = orderReference.getAmazonOrderReferenceId();
window.location = 'https://yoursite.com/redirect_page?session='
+ amazonOrderReferenceId;
},
document.getElementById("errorCode").innerHTML = error.getErrorCode() ;
document.getElementById("errorMessage").innerHTML =
error.getErrorMessage() ;
}
}).bind("payWithAmazonDiv");
</script>
次の表は、Amazon ログイン & ペイメントウィジェットから返されるさまざまなエラーコードと、対応する
エラーメッセージの一覧です。これらのエラーメッセージはウィジェット本体内に表示され、購入者が確
認できます。
エラーコード
説明
購入者に表示されたエラーメッセージ
AddressNotModifiable
order referenceが与えられた状態の場合は配
この注文では配送先住所を変更することが
送先住所を修正することができません。
できません。支援のために販売者にお問い
合わせください。
BuyerNotAssociated
InvalidAccountStatus
購入者は与えられたorder referenceでは関連
このセッションは有効ではありませ
付けされていません。ウィジェットを提供する
ん。Amazonアカウントでお支払いボタ
前に購入者はサインインしなければなりませ
ンをクリックして購入手続きを再開し
ん。
てください。
セラーアカウントは、このリクエストを実行
ボタンウィジェットを表示するときにエラ
する適切な状態ではありません。例えば、サ
ーが発生した場合は、ウィジェットは表示
スペンドや登録が完了していない場合です。
されません。購入者に表示されるエラーメ
ッセージはありません。AddressBookまた
はWalletウィジェットを表示するときにエ
ラーが発生した場合は、購入者に次のメッ
セージが表示されます。「申し訳ございま
せん。このウェブサイトからの支払の処理
中に問題があります。支援のために販売者
にお問い合わせください。」
79
InvalidOrderReferenceId
80
指定されたorder referenceのIDが無効で
申し訳ございません。このウェブサイトか
す。
らの支払の処理中に問題があります。販売
者にお問合せください。
InvalidParameterValue
指定されたパラメーターが割り当てられた値
ボタンウィジェットの表示しているときに
が有効ではありません。
ウィジェットのエラーが発生した場合は、
ウィジェットは表示されません。購入者に
表示されるエラーメッセージはありませ
ん。AddressBookまたはWalletウィジェッ
トを表示するときにエラーが発生した場合
は、購入者に次のメッセージが表示されま
す。「申し訳ございません。このウェブサ
イトからの支払の処理中に問題がありま
す。支援のために販売者にお問い合わせく
ださい。」
InvalidSellerId
提示されたセラー情報が無効です。有効なセ
ラーIDを指定してください。
ださい。」
MissingParameter
指定したパラメーターが間違っています、ま
た、規定しなければなりません。
ださい。」
PaymentMethodNotModifiable
order referenceが与えられた状態の場合は支
この注文では支払方法を変更することがで
払方法を変更することはできません。
きません。支援のために販売者にお問い合
わせください。
ReleaseEnvironmentMismatch
リリース環境でレンダリングしたウィジェッ
トはOrder Referenceオブジェクトのリリース
環境と一致しません。ウィジェットのリリー
ス環境とOrder Referenceオブジェクトは一致
しなければなりません。
80
StaleOrderReference
指定されたorder referenceは許可された時
セッションが期限になりました。Amazon
間で確認されていませんので、Canceledにな
アカウントでお支払いボタンをクリック
りました。キャンセルされたorder referenc
して再度サインインしてください。
81
eの支払方法と住所は関連付けできませんで
した。
UnknownError
サービス内の不明なエラーです。
81
82
ボタンギャラリー
デスクトップとラップトップのボタン
次の表は、デスクトップとラップトップのデバイスに表示される「Amazonアカウントでログイン」ボタンを
示しています。
ボタンパラメータ
•
type: LwA
•
color: Gold
•
type: LwA
•
color: LightGra
一般的なディスプレイ
高精細ディスプレイ
y
•
type: LwA
•
color: DarkGray
次の表は、デスクトップとラップトップのデバイスに表示される「Amazonアカウントでお支払い」ボタンを
示しています。
•
type: PwA
•
color: Gold
•
type: PwA
•
color: LightGra
y
•
type: PwA
•
color: DarkGray
タッチデバイスのボタン
次の表は、タッチデバイスに表示される「Amazonアカウントでログイン」ボタンを示しています。
•
type: LwA
•
color: Gold
•
type: LwA
•
color: LightGra
y
82
•
type: LwA
•
color: DarkGray
83
次の表は、タッチデバイスに表示される「Amazonアカウントでお支払い」ボタンを示しています。
•
type: PwA
•
color: Gold
•
type: PwA
•
color: LightGra
y
•
type: PwA
•
color: DarkGray
83
84
スタイルのガイドライン
次のガイドラインは、「Amazonアカウントでログイン」ボタンと「Amazonアカウントでお支払い」ボ
タンを使用する場合のベストプラクティスです。これらのボタンは、一切変更しないことを条件に、Am
azonによる事前の承認なしに、セラーのサイトやアプリケーションで使用できます。
セラーのWebサイトでのAmazonアカウントでログインボタンの追加
「Amazonアカウントでログイン」ボタンは、セラーのサイトまたはアプリケーションでログインする場所
に配置するようにしてください。ログインには、新規顧客の登録や、既存の顧客のログインプロンプト(チ
ェックアウト中など)が含まれます。また、顧客がログインして個人設定などを行えるように、ホームペー
ジに小さいボタン(下記を参照)を表示することもお勧めします。ALTテキストの場合は、「Amazonアカウン
トでログイン」を使用します。例：
ユーザーがログインしたら、ログインボタンを表示しないようにするか、ログアウトメッセージで置き換
えるようにしてください。
ボタンにガイドを追加する
次のテキストをログイン画面に表示することもお勧めします。
•
<セラーのサイト>でショッピングする際は、Amazon.co.jpアカウントを使用してログインしてくださ
•
•
い。
購入の支払いにはAmazon ペイメントアカウントを使用し、Amazonの保護サービスをご利用ください。
支払い情報はAmazonに安全に保存されます。
84
82
その他のサインイン製品と統合する
Amazonでは、シンプルなアイコンも提供しています。次の図は、各種のログインオプションのアイコンの
みを表示するサイトまたはアプリケーションに便利です。例：
82
83
顧客のアカウントとAmazonのリンク
現在の顧客がAmazonアカウントを使用してログインした場合、セラーはEメールアドレスを使用して顧客
を識別し、アカウントとシステム内の既存のアカウントをリンクさせます。詳しくは、「既存アカウント
でのインテグレーション」を参照してください。
83
84
セラーのサイトでのAmazonアカウントでお支払いボタンの追加
次のスクリーンショットに示すように、購入者がカートページを表示し、チェックアウトプロセスを開始
できる場合は、「Amazonアカウントでお支払い」ボタンを使用できます。
Amazon ペイメントの内容を説明し、コンバージョンを最大限に高めるために、下記のテキストを使用し
て、「これは何ですか？」のポップアップを追加することをお勧めします。
Amazon ペイメントでは、Amazonアカウントに保存している配送先情報と支払い情報を使用して、<セラー
のサイト>で注文を行うことができます。これは、信頼できる便利な支払い方法で、多くの方にご利用い
ただいております。情報やクレジットカード番号を再度入力する必要はありません。支払いの詳細は共有
されません。Amazon ペイメントを選択すると、Amazonアカウントへのセキュアなサインインが求められ
ます。サインインすると、Amazonの配送方法と支払い方法に安全にアクセスして注文を完了できます。<
セラーのサイト>のサイトを離れる必要はありません。
84
85
製品詳細ページにAmazon ペイメントを追加する
次のスクリーンショットに示すように、Amazon ペイメントボタンを追加することで、購入者は、セ
ラーのサイトのページから製品をすばやく購入できます。
85
86
ゲストとしてチェックアウト後に購入者にログインをお願いする
次のスクリーンショットに示すように、ゲストとしてチェックアウト後に、簡単な登録方法を表示できま
す。
86

Login and Pay with Amazon Integration Guide

Transcription

Similar documents

OneLogin に独自のアプリケーションを登録する手順 Custom Connector Manual 編

RDS - Amazon Web Services

Elastic Load Balancing éçºèã¬ã¤ã

Login and Pay with Amazon Integration Guide

Transcription

Similar documents

OneLogin に独自のアプリケーションを登録する手順 Custom Connector Manual 編

RDS - Amazon Web Services

Elastic Load Balancing éçºè ã¬ã¤ã

Elastic Load Balancing éçºèã¬ã¤ã