ログイン
ログイン

HAQM カスタマーアカウントへの支払い

HAQM カスタマーアカウントへの支払い

連携を開始する前に、必ず HAQM インセンティブ API アカウントを設定してください。インセンティブ API アカウントを作成します。

ログイン＆レシーブ Web サービスは、新規または既存の HAQM カスタマーに資金を支出する API を提供します。支出を行うと、HAQM カスタマーアカウントの HAQM ギフト券残高にリアルタイムで金額が加算されます。この REST ベースの Web サービスは、インセンティブ API の一部です。インセンティブ API は、HAQM ギフト券の運用をサポートする一連のサービスです。

次のユースケースでは、ログイン＆レシーブを呼び出します。

  • 既存の Web アプリケーションを使用して、顧客に即時かつ保証された支払いが必要な場合
  • 法的義務または事業上の義務を満たすために、金銭的価値を譲渡できないようにする必要がある場合
  • 支払いイベントを通知するために、顧客に電子メール通知を送信したい場合

このページでは、アプリケーションからログイン＆レシーブ API を呼び出す方法と、ログイン＆レシーブで実行できるタスクについて説明します。

主な概念と基本的な流れ

ログイン＆レシーブ API は、Login with HAQM Web サービスを使用します。これにより、ユーザーはブラウザベースまたはモバイルアプリケーション内で HAQM アカウントの認証情報を使用して HAQM アカウントを認証できます。認証が完了すると、Login with HAQM サービスは、ログイン＆レシーブ API への入力パラメータとして使用できるユーザー ID をアプリケーションに提供します。これらのサービスを組み合わせることで、エンドユーザーにとってシームレスなエクスペリエンスを実現できます。

Login with HAQM は、SDK など、好みのユーザーエクスペリエンスに合わせてカスタマイズできます。詳細については、開発者ポータルの「Login with HAQM」をご覧ください。

次に、ログイン＆レシーブのアプリケーションワークフローについて説明します。

  1. アプリケーションユーザーが HAQM アカウントの HAQM ギフト券残高に振り込みを申請します。
  2. Login with HAQM モジュールに、ユーザーに HAQM 認証情報の入力を求めるページが表示されます。
  3. 新規 HAQM カスタマーは、Login with HAQM ワークフローで新しいアカウントに登録できます。
  4. ユーザーのプログラムで Amaozon カスタマー名、E メールアドレス、郵便番号がリクエストされる場合、Login with HAQM ワークフローではこの情報をユーザーのサービスと共有することに対するユーザーの同意を求めます。
  5. モジュールは、Login with HAQM を使用して認証リクエストを開始します。
  6. ユーザーアカウントを一意に識別する ID 値は、レスポンスで JSON オブジェクトとして返されます。
  7. アプリケーションは、リクエスト本文の ID 値を使用して LoadHAQMBalance メソッドを呼び出します。
  8. LoadHAQMBalance 操作により、アカウントのギフト券の残高が更新されます。
  9. HAQM は、カスタマーアカウントのギフト券残高で資金が正常に適用または無効化されると、Amaozon カスタマーアカウントに関連付けられた E メールアドレスに確認メールを送信します。この E メールには、LoadHAQMBalance リクエストの notificationMessage パラメータで指定されたテキストが含まれます。

注：

  • ユーザーは、キャンセル を選択するか、ポップアップウィンドウを閉じることによって (この UX メソッドが使用されている場合)、Login with HAQM ワークフローをいつでもエスケープできます。
  • 氏名、メールアドレス、郵便番号などの個人識別情報を保管するには、GDPR、CCPA、その他の個人情報保護法を遵守するための追加のセキュリティ条項が必要です。

前提条件

ログイン＆レシーブを使用するには、次の設定手順を実行します。

  • インセンティブ API 連携セットアップガイド の指示に従ってアカウントを作成し、HAQM インセンティブとの契約に同意します。
  • ウェブまたはモバイルアプリケーションを Login with HAQM Web サービスと統合して、認証と (オプションで) ユーザープロファイルデータへのアクセスを提供します。Login with HAQM とアプリケーションを統合する方法については、Login with HAQM 開発者センターの手順に従ってください。注： モバイルアプリで Login with HAQM を使用するには、Login with HAQM mobile SDK を使用する必要があります。技術的にはモバイルアプリからブラウザベースの操作が可能ですが、セキュリティ上の理由からこれを禁止しています。
  • サンドボックスは、アプリケーションを開発およびテストするときに使用するテスト環境です。サンドボックスのアクセス認証情報を取得するには、HAQM アカウントマネージャーにお問い合わせください。サンドボックスへのアクセスが許可されると、提供されているパートナー ID 値を使用して開発とテストを開始できます。サンドボックスにアクセスするためのエンドポイントの基礎となる URL は、地域およびエンドポイントセクションにあります。サンドボックスへのアクセスを利用し、HAQM インセンティブ API 連携セットアップガイドの手順に従って、ユーザーのプログラムを開発およびテストできます。

ログイン＆レシーブ API

アプリケーションは、Web サービスへの同期リクエストを行うことで、ログイン＆レシーブと対話します。このセクションでは、リクエストの構造と使用可能な操作について説明します。操作を呼び出すには、インセンティブ API エンドポイントに HTTP リクエストを送信し、レスポンスを待ちます。ゲートウェイへの REST HTTP リクエストには、リクエストメソッド、URI、ヘッダー、および XML または JSON で表された本文が含まれます。レスポンスには、HTTP ステータスコード、レスポンスヘッダー、レスポンス本文が含まれます。各 API 呼び出しに対しては、セキュリティ認証情報と AWS 署名バージョン 4 署名プロセスを使用して署名する必要があります。

以下に、各 API 操作、リクエストヘッダーおよび関連するパラメータの説明を示します。

操作

以下の操作がサポートされています。

LoadHAQMBalance

LoadHAQMBalance 操作は、Amaozon カスタマーのギフト券残高に資金を適用します。以下に、リクエスト本文のパラメータの説明を示します。

リクエストパラメータ 説明
loadBalanceRequestId 大文字と小文字が区別される partnerId (最大 40 文字) のプレフィックスが付いたリクエストを表す一意の識別子。英数字を使用、文字を含めてはならない
partnerId アカウントを表す一意の識別子 (大文字と小文字が区別されます)
amount HAQM GC 残高に追加される資金の金額
currencyCode ISO-4217 通貨コード
value 支出される金額の値は、整数で指定されます。例：100.23 = 10023。通貨が小数点に対応していない地域では、パディングは必要ありません。たとえば、日本では、231 円は 23100 ではなく 231 です
account Login with HAQM API によって提供される、アクティブな Amaozon カスタマーを識別する情報。サンドボックスリクエストの場合は、amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ を使用します
id Login with HAQM API から JSON HTTP レスポンスとして返されるユーザーの HAQM アカウントを識別する一意のカスタマーアカウント識別値
type ID の種類を指定します。有効な種類の値 = 2 (カスタマー ID)
transactionSource トランザクションソースを識別するデータ
sourceId オプション。トランザクションの識別子。このメタデータは、顧客の HAQM 残高元帳に表示されます。たとえば、<Serial Number: xxx> (最大 40 文字の Unicode 文字) からのギフト券
externalReference インセンティブ API ポータルで表示したときに、リクエストを説明するために使用できるテキストフィールド。(最大 100 文字の Unicode 文字)
notificationDetails オプション。資金の支出の理由の説明。
notificationMessage オプション。確認メールに表示される文字列 (最大 250 文字の Unicode 文字)。

リクエストの例

POST 
/LoadHAQMBalance HTTP/1.1

accept:application/json
host:agcod-v2-gamma.haqm.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
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":"HAQM123456",
    "partnerId":"HAQM",
    "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": "HAQM123456"
}

VoidHAQMBalanceLoad

この操作は、発行されたギフト券コードの資金を受領した Amaozon カスタマーがまだ使用していない場合に、以前に成功した LoadHAQMBalance リクエストを無効にします。この操作は、LoadHAQMBalance への最初の呼び出しから最大 15 分まで実行できます。その後、VoidHAQMBalanceLoa への呼び出しでは何も行われません。

以前の HAQMBalanceLoad リクエストが成功したことを確認できない場合は、アプリケーションでこの操作を呼び出す必要があります。たとえば、LoadHAQMBalance への呼び出しで結果が返されない場合は、VoidHAQMBalanceLoad を呼び出して、Amaozon カスタマーのギフト券残高に資金が追加されないようにします。

以下に、リクエスト本文のパラメータの説明を示します。

注： 以下のパラメータはすべて、以前の LoadHAQMBalance リクエストで使用されたパラメータと一致していなければなりません。

パラメータ 説明
loadBalanceRequestId 以前に成功した LoadHAQMBalance リクエストで使用された一意の識別子
partnerId アカウントを表す一意の識別子 (大文字と小文字が区別されます)
amount LoadHAQMBalance リクエストで提供された金額
currencyCode 使用される ISO-4217 通貨コード
value HAQM カスタマーの HAQM ギフト券残高から削除される元のトランザクションの金額値 (例：100.23 = 10023)。通貨が小数点に対応していない地域では、パディングは必要ありません。たとえば、日本では、231 円は 23100 ではなく 231 です。
account 無効操作が適用される顧客の口座番号 (前回のロード操作から)。サンドボックスリクエストの場合は、amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ を使用します
id 1 つの HAQM カスタマーアカウントに対する一意の識別値。元は、Login with HAQM API から JSON HTTP レスポンスとして返されました。
type ID の種類を指定します。2 (カスタマー ID) に設定する必要があります

リクエストの例

POST 
/VoidHAQMBalanceLoad HTTP/1.1

accept:application/json
host:agcod-v2-gamma.haqm.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidHAQMBalanceLoad
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": "HAQM123456",
    "partnerId": "HAQM",
    "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":"HAQM123456"
}

GetAvailableFunds

GetAvailableFunds を参照してください。

リクエストのテスト

連携をテストするために、モックリクエストを作成して API からのレスポンスをシミュレーションできます。モックリクエストからのレスポンスは、ID パラメータによって制御されます。たとえば、ID F0000 を渡すと Success レスポンスがシミュレーションされ、ID F1000 を渡すと一般的なエラーがシミュレーションされます。使用可能なレスポンスの完全なリストについては、エラーコードを参照してください。モックリクエストを呼び出すために必要な (最小) パラメータは次のとおりです。

{
  "loadBalanceRequestId": "HAQM123456",
  "account": {
    "id": "F2044",
    "type": "0"
  }
}

注： 他のフィールドに渡された値は、単純にレスポンスでエコーされ、必須ではありません。

モックリクエストの例

POST /LoadHAQMBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.haqm.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
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":"HAQM123456",
    "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 アカウントでのみ実施可能です。

サンドボックス： 「モック」リクエストを作成して、LoadHAQMBalance APIからのレスポンスをシミュレーションします。

プロダクション：

  • Login with HAQM コンポーネントを使用して、HAQM カスタマーアカウントの有効な customer.id 値を受け取ります。
  • LoadHAQMBalance および VoidHAQMBalanceLoad エンドポイントを呼び出します。
  • アプリケーションとユーザーエクスペリエンスのエンドツーエンドのテストを完了します。
テスト 操作 予測される結果
1.haqm.com (またはローカル) のテストアカウントを作成する Load Balance API 呼び出しをテストするために、地域に HAQM アカウントのセットを作成します。 アカウントが作成されます。
2.Login with HAQM モジュールを検証する 1.成功したログインを検証する
2.有効な認証トークン
3.user.id が返されたことを検証する		 アカウントごとに、
1.ログインに成功した
2.認証トークンが提供されている
3.一意の user.id 値が指定されている
3.LoadHAQMBalance を検証する アプリケーション UX ワークフローを使用して、ステップ (1) で作成したテストアカウントに対してこのメソッドを金額値 (例：$0.10) で呼び出します
2.HAQM アカウントにログインし、「ギフト券残高を表示」を選択する
4.通知メッセージが確認メールに表示され、API リクエストに挿入された notificationMessage パラメータと一致することを確認します。
5.haqm.com アカウントに登録されている E メールアドレスに E メールが送信されたことを確認する		 1. Load への呼び出しごとに status = success が返されます
2.アカウントのギフト券残高がロードされた金額と一致する
3.通知メッセージが提供されたメッセージと一致する
4.E メールメッセージを受信
5.amount.value で指定された値がインセンティブ API ポータルのアカウントから引き落とされる
4.LoadHAQMBalance の冪等性を検証する 1.同じ loadBalanceRequestId と user.idを使用してメソッドを複数回呼び出す
2.HAQM アカウントにログインする
3.ギフト券残高を表示する		 1. 呼び出しごとにstatus = success が返される
2.最初の呼び出しの amount.value が適用されるが、その後の LoadHAQMBalance メソッドへの呼び出しは無視された
5.VoidHAQMBalanceLoad を検証する 1.以前に作成した loadBalanceRequestId を使用してトランザクションを無効化する
2.該当する user.id の haqm.com アカウントにログインする
3.残高が無効になった
4.haqm.com アカウントに登録されている E メールアドレスに E メールが送信されたことを確認する
5.インセンティブ API ポータルにログインし、トランザクションを表示する		 1. Void への呼び出しごとに status = success が返される
2.アカウントのギフト券残高がロードされた金額と一致する
3.通知メッセージが提供されたメッセージと一致する
4.E メールメッセージを受信
5.amount.value で指定された資金がインセンティブ API ポータルの口座に払い戻された

パフォーマンス

API は、1 秒あたり 10 トランザクション (TPS) の最大レートでトランザクションを処理するように設計されています。

注： サンドボックス環境は SLA によって管理されず、トランザクションレートが不安定に見えることがあります。

エラーコード

エラーを表示するために、コードの規約を使用しています。たとえば、原因がクライアント側にある場合、API は F2xx エラーを返し、問題が HAQM システムの問題によるものであれば F1XX で応答します。一般に、エラーコードは、次の表のように変換されます。

エラーコード 説明
F100 HAQM 内部エラー
F200 F200：無効なリクエストエラー (リクエストペイロードに誤りがある)
F300 アカウント関連のエラー (通常、オンボーディング、認証、アクセス関連の問題などによる)
F400 再試行可能エラー (一時的な問題)。エラー処理を参照してください
F500 不明なエラー
エラータイプ
エラーコード/ モックコード		 説明
GeneralError
F100 / F1000		 HAQM 内部エラー
BalanceLoadCannotBeVoided
F100 / F1001		 HAQM の内部エラーのため、ロードバランスを無効にすることができません
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 は、HAQM システムには存在しません
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 は、HAQM システムには存在しません
InvalidAccessKey
F300 / F3001		 リクエストに署名するために使用されるセキュリティアクセスキーが HAQM システムに存在しません (中国では適用されません)
InvalidAccessKey
F300 / F3001		 API リクエストの署名に使用されるアクセスキー (中国) が HAQM システムに存在しません
AccessDenied
F300 / F3002		 アカウントがブロックされています
InsufficientFunds
F300 / F3003		 アカウントにリクエスト金額を発行するのに十分な資金がありません (各パートナーには一定の購入可能限度額が与えられ、パートナーは購入可能限度額までの残高のみを発行できます。購入可能限度額は、パートナーが支払いを行うとリセットされます)
IssuanceCapExceeded
F300 / F3004		 指定した期間内に契約で定義された残高発行限度額に達しました
OperationNotPermitted
F300 / F3006		 リクエストは拒否されます。パートナーに API を呼び出す権限がありません (HAQM Balance Load ディストリビューター以外のパートナーが、オンボーディング前に HAQM Balance Load API を呼び出そうとすると発生します)
ActiveContractNotFound
F300 / F3009		 パートナーアカウントの設定が完了していません
CustomerSurpassedDailyVelocityLimit
F300 / F3010		 顧客が 1 日の速度制限を超えています
CustomerAccountBlocked
F300 / F3011		 この HAQM アカウントはこのトランザクションの実行を許可されていません
SystemTemporarilyUnavailable
F400 / F4000		 HAQM システムは一時的に利用できません。エラー処理を参照してください
GeneralError
F500 / F5000		 不明なエラー