Amazon カスタマーアカウントへの支払い
連携を開始する前に、必ず Amazon インセンティブ API アカウントを設定してください。インセンティブ API アカウントを作成します。
ログイン&レシーブ Web サービスは、新規または既存の Amazon カスタマーに資金を支出する API を提供します。支出を行うと、Amazon カスタマーアカウントの Amazon ギフト券残高にリアルタイムで金額が加算されます。この REST ベースの Web サービスは、インセンティブ API の一部です。インセンティブ API は、Amazon ギフト券の運用をサポートする一連のサービスです。
次のユースケースでは、ログイン&レシーブを呼び出します。
- 既存の Web アプリケーションを使用して、顧客に即時かつ保証された支払いが必要な場合
- 法的義務または事業上の義務を満たすために、金銭的価値を譲渡できないようにする必要がある場合
- 支払いイベントを通知するために、顧客に電子メール通知を送信したい場合
このページでは、アプリケーションからログイン&レシーブ API を呼び出す方法と、ログイン&レシーブで実行できるタスクについて説明します。
主な概念と基本的な流れ
ログイン&レシーブ API は、Login with Amazon Web サービスを使用します。これにより、ユーザーはブラウザベースまたはモバイルアプリケーション内で Amazon アカウントの認証情報を使用して Amazon アカウントを認証できます。認証が完了すると、Login with Amazon サービスは、ログイン&レシーブ API への入力パラメータとして使用できるユーザー ID をアプリケーションに提供します。これらのサービスを組み合わせることで、エンドユーザーにとってシームレスなエクスペリエンスを実現できます。
Login with Amazon は、SDK など、好みのユーザーエクスペリエンスに合わせてカスタマイズできます。詳細については、開発者ポータルの「Login with Amazon」をご覧ください。
次に、ログイン&レシーブのアプリケーションワークフローについて説明します。
- アプリケーションユーザーが Amazon アカウントの Amazon ギフト券残高に振り込みを申請します。
- Login with Amazon モジュールに、ユーザーに Amazon 認証情報の入力を求めるページが表示されます。
- 新規 Amazon カスタマーは、Login with Amazon ワークフローで新しいアカウントに登録できます。
- ユーザーのプログラムで Amaozon カスタマー名、E メールアドレス、郵便番号がリクエストされる場合、Login with Amazon ワークフローではこの情報をユーザーのサービスと共有することに対するユーザーの同意を求めます。
- モジュールは、Login with Amazon を使用して認証リクエストを開始します。
- ユーザーアカウントを一意に識別する ID 値は、レスポンスで JSON オブジェクトとして返されます。
- アプリケーションは、リクエスト本文の ID 値を使用して LoadAmazonBalance メソッドを呼び出します。
- LoadAmazonBalance 操作により、アカウントのギフト券の残高が更新されます。
- Amazon は、カスタマーアカウントのギフト券残高で資金が正常に適用または無効化されると、Amaozon カスタマーアカウントに関連付けられた E メールアドレスに確認メールを送信します。この E メールには、LoadAmazonBalance リクエストの notificationMessage パラメータで指定されたテキストが含まれます。
注:
- ユーザーは、キャンセル を選択するか、ポップアップウィンドウを閉じることによって (この UX メソッドが使用されている場合)、Login with Amazon ワークフローをいつでもエスケープできます。
- 氏名、メールアドレス、郵便番号などの個人識別情報を保管するには、GDPR、CCPA、その他の個人情報保護法を遵守するための追加のセキュリティ条項が必要です。
前提条件
ログイン&レシーブを使用するには、次の設定手順を実行します。
- インセンティブ API 連携セットアップガイド の指示に従ってアカウントを作成し、Amazon インセンティブとの契約に同意します。
- ウェブまたはモバイルアプリケーションを Login with Amazon Web サービスと統合して、認証と (オプションで) ユーザープロファイルデータへのアクセスを提供します。Login with Amazon とアプリケーションを統合する方法については、Login with Amazon 開発者センターの手順に従ってください。注: モバイルアプリで Login with Amazon を使用するには、Login with Amazon mobile SDK を使用する必要があります。技術的にはモバイルアプリからブラウザベースの操作が可能ですが、セキュリティ上の理由からこれを禁止しています。
- サンドボックスは、アプリケーションを開発およびテストするときに使用するテスト環境です。サンドボックスのアクセス認証情報を取得するには、Amazon アカウントマネージャーにお問い合わせください。サンドボックスへのアクセスが許可されると、提供されているパートナー ID 値を使用して開発とテストを開始できます。サンドボックスにアクセスするためのエンドポイントの基礎となる URL は、地域およびエンドポイントセクションにあります。サンドボックスへのアクセスを利用し、Amazon インセンティブ API 連携セットアップガイドの手順に従って、ユーザーのプログラムを開発およびテストできます。
ログイン&レシーブ API
アプリケーションは、Web サービスへの同期リクエストを行うことで、ログイン&レシーブと対話します。このセクションでは、リクエストの構造と使用可能な操作について説明します。操作を呼び出すには、インセンティブ API エンドポイントに HTTP リクエストを送信し、レスポンスを待ちます。ゲートウェイへの REST HTTP リクエストには、リクエストメソッド、URI、ヘッダー、および XML または JSON で表された本文が含まれます。レスポンスには、HTTP ステータスコード、レスポンスヘッダー、レスポンス本文が含まれます。各 API 呼び出しに対しては、セキュリティ認証情報と AWS 署名バージョン 4 署名プロセスを使用して署名する必要があります。
以下に、各 API 操作、リクエストヘッダーおよび関連するパラメータの説明を示します。
操作
以下の操作がサポートされています。
LoadAmazonBalance
LoadAmazonBalance 操作は、Amaozon カスタマーのギフト券残高に資金を適用します。以下に、リクエスト本文のパラメータの説明を示します。
リクエストパラメータ | 説明 |
---|---|
loadBalanceRequestId |
大文字と小文字が区別される partnerId (最大 40 文字) のプレフィックスが付いたリクエストを表す一意の識別子。英数字を使用、文字を含めてはならない |
partnerId |
アカウントを表す一意の識別子 (大文字と小文字が区別されます) |
amount |
Amazon GC 残高に追加される資金の金額 |
currencyCode |
ISO-4217 通貨コード |
value |
支出される金額の値は、整数で指定されます。例:100.23 = 10023。通貨が小数点に対応していない地域では、パディングは必要ありません。たとえば、日本では、231 円は 23100 ではなく 231 です |
account |
Login with Amazon API によって提供される、アクティブな Amaozon カスタマーを識別する情報。サンドボックスリクエストの場合は、amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ を使用します |
id |
Login with Amazon API から JSON HTTP レスポンスとして返されるユーザーの Amazon アカウントを識別する一意のカスタマーアカウント識別値 |
type |
ID の種類を指定します。有効な種類の値 = 2 (カスタマー ID) |
transactionSource |
トランザクションソースを識別するデータ |
sourceId |
オプション。トランザクションの識別子。このメタデータは、顧客の Amazon 残高元帳に表示されます。たとえば、 |
externalReference |
インセンティブ API ポータルで表示したときに、リクエストを説明するために使用できるテキストフィールド。(最大 100 文字の Unicode 文字) |
notificationDetails |
オプション。資金の支出の理由の説明。 |
notificationMessage |
オプション。確認メールに表示される文字列 (最大 250 文字の Unicode 文字)。 |
リクエストの例
POST
/LoadAmazonBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{ "loadBalanceRequestId":"Amazon123456",
"partnerId":"Amazon",
"amount":{
"currencyCode":"USD",
"value": 1000
},
"account":{
"id":"amz1.account.123512341234",
"type":"2"
},
"transactionSource":{
"sourceId":"Customer Service"
},
"externalReference":"serviceId:123",
"notificationDetails":{
"notificationMessage":"Thank you for your purchase!"
}
}
レスポンスの例
{
"status": "Success",
"amount": {
"currencyCode": "USD",
"value": 9000
},
"account": {
"id": "amz1.account.123512341234",
"type": "2"
},
"loadBalanceRequestId": "Amazon123456"
}
VoidAmazonBalanceLoad
この操作は、発行されたギフト券コードの資金を受領した Amaozon カスタマーがまだ使用していない場合に、以前に成功した LoadAmazonBalance リクエストを無効にします。この操作は、LoadAmazonBalance への最初の呼び出しから最大 15 分まで実行できます。その後、VoidAmazonBalanceLoa への呼び出しでは何も行われません。
以前の AmazonBalanceLoad リクエストが成功したことを確認できない場合は、アプリケーションでこの操作を呼び出す必要があります。たとえば、LoadAmazonBalance への呼び出しで結果が返されない場合は、VoidAmazonBalanceLoad を呼び出して、Amaozon カスタマーのギフト券残高に資金が追加されないようにします。
以下に、リクエスト本文のパラメータの説明を示します。
注: 以下のパラメータはすべて、以前の LoadAmazonBalance リクエストで使用されたパラメータと一致していなければなりません。
パラメータ | 説明 |
---|---|
loadBalanceRequestId |
以前に成功した LoadAmazonBalance リクエストで使用された一意の識別子 |
partnerId |
アカウントを表す一意の識別子 (大文字と小文字が区別されます) |
amount |
LoadAmazonBalance リクエストで提供された金額 |
currencyCode |
使用される ISO-4217 通貨コード |
value |
Amazon カスタマーの Amazon ギフト券残高から削除される元のトランザクションの金額値 (例:100.23 = 10023)。通貨が小数点に対応していない地域では、パディングは必要ありません。たとえば、日本では、231 円は 23100 ではなく 231 です。 |
account |
無効操作が適用される顧客の口座番号 (前回のロード操作から)。サンドボックスリクエストの場合は、amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ を使用します |
id |
1 つの Amazon カスタマーアカウントに対する一意の識別値。元は、Login with Amazon API から JSON HTTP レスポンスとして返されました。 |
type |
ID の種類を指定します。2 (カスタマー ID) に設定する必要があります |
リクエストの例
POST
/VoidAmazonBalanceLoad HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{
"loadBalanceRequestId": "Amazon123456",
"partnerId": "Amazon",
"amount": {
"currencyCode": "USD",
"value": 1000
},
"account": {
"id": "amz1.account.123512341234",
"type": "2"
}
}
レスポンスの例
{
"status":"Success",
"amount":{
"currencyCode":"USD",
"value":1000
},
"account":{
"id":"amz1.account.123512341234",
"type":"2"
},
"loadBalanceRequestId":"Amazon123456"
}
GetAvailableFunds
GetAvailableFunds を参照してください。
リクエストのテスト
連携をテストするために、モックリクエストを作成して API からのレスポンスをシミュレーションできます。モックリクエストからのレスポンスは、ID パラメータによって制御されます。たとえば、ID F0000 を渡すと Success レスポンスがシミュレーションされ、ID F1000 を渡すと一般的なエラーがシミュレーションされます。使用可能なレスポンスの完全なリストについては、エラーコードを参照してください。モックリクエストを呼び出すために必要な (最小) パラメータは次のとおりです。
{
"loadBalanceRequestId": "Amazon123456",
"account": {
"id": "F2044",
"type": "0"
}
}
注: 他のフィールドに渡された値は、単純にレスポンスでエコーされ、必須ではありません。
モックリクエストの例
POST /LoadAmazonBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{ "loadBalanceRequestId":"Amazon123456",
"partnerId":"",
"amount":{
"currencyCode":"",
"value":""
},
"account":{
"id":"F2044",
"type":"0"
},
"transactionSource":{
"sourceId":""
},
"externalReference":"",
"notificationDetails":{
"notificationMessage":""
}
}
モックレスポンスの例
{
"errorCode": "F2044",
"errorMessage": "Source Id is too long.Received 41 characters.Maximum
number of characters is 40",
"errorType": "SourceIdTooLong",
"status": "FAILURE"
}
ログイン&レシーブのテストスクリプト
サンドボックス環境を使用して、連携の一部のコンポーネントを確認できます。ただし、アプリケーションのユーザーエクスペリエンスの完全なエンドツーエンドのテストは、本番環境 API アカウントでのみ実施可能です。
サンドボックス: 「モック」リクエストを作成して、LoadAmazonBalance APIからのレスポンスをシミュレーションします。
プロダクション:
- Login with Amazon コンポーネントを使用して、Amazon カスタマーアカウントの有効な customer.id 値を受け取ります。
- LoadAmazonBalance および VoidAmazonBalanceLoad エンドポイントを呼び出します。
- アプリケーションとユーザーエクスペリエンスのエンドツーエンドのテストを完了します。
テスト | 操作 | 予測される結果 |
---|---|---|
1.amazon.com (またはローカル) のテストアカウントを作成する | Load Balance API 呼び出しをテストするために、地域に Amazon アカウントのセットを作成します。 | アカウントが作成されます。 |
2.Login with Amazon モジュールを検証する | 1.成功したログインを検証する 2.有効な認証トークン 3.user.id が返されたことを検証する |
アカウントごとに、 1.ログインに成功した 2.認証トークンが提供されている 3.一意の user.id 値が指定されている |
3.LoadAmazonBalance を検証する | アプリケーション UX ワークフローを使用して、ステップ (1) で作成したテストアカウントに対してこのメソッドを金額値 (例:$0.10) で呼び出します 2.Amazon アカウントにログインし、「ギフト券残高を表示」を選択する 4.通知メッセージが確認メールに表示され、API リクエストに挿入された notificationMessage パラメータと一致することを確認します。5.amazon.com アカウントに登録されている E メールアドレスに E メールが送信されたことを確認する |
1. Load への呼び出しごとに status = success が返されます2.アカウントのギフト券残高がロードされた金額と一致する 3.通知メッセージが提供されたメッセージと一致する 4.E メールメッセージを受信 5. amount.value で指定された値がインセンティブ API ポータルのアカウントから引き落とされる |
4.LoadAmazonBalance の冪等性を検証する | 1.同じ loadBalanceRequestId と user.id を使用してメソッドを複数回呼び出す2.Amazon アカウントにログインする 3.ギフト券残高を表示する |
1. 呼び出しごとにstatus = success が返される2.最初の呼び出しの amount.value が適用されるが、その後の LoadAmazonBalance メソッドへの呼び出しは無視された |
5.VoidAmazonBalanceLoad を検証する | 1.以前に作成した loadBalanceRequestId を使用してトランザクションを無効化する2.該当する user.id の amazon.com アカウントにログインする 3.残高が無効になった 4.amazon.com アカウントに登録されている E メールアドレスに E メールが送信されたことを確認する 5.インセンティブ API ポータルにログインし、トランザクションを表示する |
1. Void への呼び出しごとに status = success が返される2.アカウントのギフト券残高がロードされた金額と一致する 3.通知メッセージが提供されたメッセージと一致する 4.E メールメッセージを受信 5. amount.value で指定された資金がインセンティブ API ポータルの口座に払い戻された |
パフォーマンス
API は、1 秒あたり 10 トランザクション (TPS) の最大レートでトランザクションを処理するように設計されています。
注: サンドボックス環境は SLA によって管理されず、トランザクションレートが不安定に見えることがあります。
エラーコード
エラーを表示するために、コードの規約を使用しています。たとえば、原因がクライアント側にある場合、API は F2xx エラーを返し、問題が Amazon システムの問題によるものであれば F1XX で応答します。一般に、エラーコードは、次の表のように変換されます。
エラーコード | 説明 |
---|---|
F100 | Amazon 内部エラー |
F200 | F200:無効なリクエストエラー (リクエストペイロードに誤りがある) |
F300 | アカウント関連のエラー (通常、オンボーディング、認証、アクセス関連の問題などによる) |
F400 | 再試行可能エラー (一時的な問題)。エラー処理を参照してください |
F500 | 不明なエラー |
エラータイプ エラーコード/ モックコード |
説明 |
---|---|
GeneralError F100 / F1000 |
Amazon 内部エラー |
BalanceLoadCannotBeVoided F100 / F1001 |
Amazon の内部エラーのため、ロードバランスを無効にすることができません |
InvalidRequestInput F200 / F2000 |
リクエスト本文が null です |
InvalidPartnerIdInput F200 / F2002 |
partnerId は null にできません |
InvalidAmountInput F200 / F2003 |
金額を null にすることはできません |
InvalidAmountValue F200 / F2004 |
金額は 0 より大きくなければなりません |
InvalidCurrencyCodeInput F200 / F2005 |
通貨コードを null にすることはできません |
InvalidRequestIdInput F200 / F2006 |
loadBalanceRequestId は null にできません |
MaxAmountExceeded F200 / F2015 |
金額が国内市場セグメントで許容される最大値を超えています (例:米国で500ドル) |
FractionalAmountNotAllowed F200 / F2017 |
通貨では端数を使用できません (例:JP) |
RequestIdTooLong F200 / F2021 |
loadBalanceRequestId が 40 文字を超えています |
RequestIdMustStartWithPartnerName F200 / F2022 |
loadBalanceRequestId は partnerId で始まる必要があります |
InvalidAccountType F200 / F2033 |
リクエストで提供されたアカウントタイプは未定義です |
UndefinedAccountId F200 / F2034 |
リクエストで指定された AccountId は、Amazon システムには存在しません |
AccountIdNotInValidStatus F200 / F2035 |
AccountId が、リクエストされた操作に対して有効なステータスではありません (例:AccountId が非アクティブです) |
InvalidCurrencyInMarketplace F200 / F2036 |
AccountId が作成される国の市場セグメントで通貨コードがサポートされていません |
AmountBelowMinThreshold F200 / F2037 |
金額が最低必要金額を下回っています |
LoadBalanceRequestIdAlreadyUsed F200 / F2038 |
ロード API で提供された loadBalanceRequestId は既に使用されています (たとえば、指定された loadBalanceRequestId の冪等性チェックが失敗した場合)。 |
LoadBalanceRequestIdDoesNotExist F200 / F2039 |
無効な API で提供された loadBalanceRequestId の Load リクエストは存在しません |
RequestMismatchFromLoadRequest F200 / F2040 |
void リクエストで渡されたパラメータが Load リクエストのパラメータと一致しません |
BalanceLoadCannotBeVoided F200 / F2041 |
ロードバランスが使われ、voidIfUsed フラグが false の場合 |
ExternalReferenceTooLong F200 / F2042 |
使用される値が Unicode 文字の最大文字数を超えています |
NotificationMessageTooLong F200 / F2043 |
notificationDetails パラメータで使用される値が 250 文字 (Unicode) を超えています |
SourceIdTooLong F200 / F2044 |
sourceID フィールドで使用されている値が、Unicode 文字の最大文字数 (40 文字) を超えています |
BalanceLoadCannotBeVoided F200 / F2045 |
残高を無効にすることができません。リクエストが制限時間以降に到着しました |
InvalidPartnerId F300 / F3000 |
API リクエストで使用される partnerId は、Amazon システムには存在しません |
InvalidAccessKey F300 / F3001 |
リクエストに署名するために使用されるセキュリティアクセスキーが Amazon システムに存在しません (中国では適用されません) |
InvalidAccessKey F300 / F3001 |
API リクエストの署名に使用されるアクセスキー (中国) が Amazon システムに存在しません |
AccessDenied F300 / F3002 |
アカウントがブロックされています |
InsufficientFunds F300 / F3003 |
アカウントにリクエスト金額を発行するのに十分な資金がありません (各パートナーには一定の購入可能限度額が与えられ、パートナーは購入可能限度額までの残高のみを発行できます。購入可能限度額は、パートナーが支払いを行うとリセットされます) |
IssuanceCapExceeded F300 / F3004 |
指定した期間内に契約で定義された残高発行限度額に達しました |
OperationNotPermitted F300 / F3006 |
リクエストは拒否されます。パートナーに API を呼び出す権限がありません (Amazon Balance Load ディストリビューター以外のパートナーが、オンボーディング前に Amazon Balance Load API を呼び出そうとすると発生します) |
ActiveContractNotFound F300 / F3009 |
パートナーアカウントの設定が完了していません |
CustomerSurpassedDailyVelocityLimit F300 / F3010 |
顧客が 1 日の速度制限を超えています |
CustomerAccountBlocked F300 / F3011 |
この Amazon アカウントはこのトランザクションの実行を許可されていません |
SystemTemporarilyUnavailable F400 / F4000 |
Amazon システムは一時的に利用できません。エラー処理を参照してください |
GeneralError F500 / F5000 |
不明なエラー |