実店舗で資金を受け取る
連携を開始する前に、必ず HAQM インセンティブ API アカウントを設定してください。HAQM Cash オンボーディング手順
HAQM Balance Load (ABL) は、顧客の HAQM ギフト券残高にリアルタイムで資金を直接ロードできるシステムです。このシステムを利用するには、顧客がアクティブな HAQM カスタマーであることを証明できることが必要です。
HAQM Balance Load (ABL) は、顧客の HAQM ギフト券残高にリアルタイムで資金を直接ロードできるシステムです。このシステムを利用するには、顧客がアクティブな HAQM カスタマーであることを証明できることが必要です。HAQM Cash は、HAQM Balance Load サービスを使用して、顧客が HAQM カスタマーアカウントを識別するバーコードまたは携帯電話番号を提供することにより、ネットワーク内の実際の小売店 (実店舗) でHAQM ギフト券の資金をロードできるようにします。有効な HAQM アカウントが見つからない場合、顧客は印刷された領収書に HAQM ギフト券コードを取得することができます。このコードは、実装によって許可されていれば、後でアカウントにギフト券コードを登録することができます。
- HAQM Balance Load との連携
- HAQM Cash
- メトリックス
- 国別のトランザクションごとの最小金額と最大金額
- 2 ステップ残高ロードプロセス
- 1 ステップ残高ロードプロセス
- 操作例
- テストデータ
- デジタル署名：署名プロセス
- AWS V4 署名の例
HAQM Balance Load との連携
これらの操作エンドポイントに対して、ロードする資金を指定して、同期リクエストを行うことができます。操作は、操作の成功または失敗を示すステータスを持って各リクエストに応答します。
これらの API は、HAQM との契約を締結し、HAQM カスタマーのギフト券残高に資金をロードするためのソリューション (通常は販売時点管理システム) を構築するパートナーが利用できます。
HAQM Cash
| 国 | サービス名 |
|---|---|
| 米国、メキシコ、日本、カナダ | HAQM Cash |
| イギリス、アラブ首長国連邦 | Top up in store |
| イタリア | Ricarica in cassa |
| フランス | Recharge près de chez vous |
| スペイン | Recargas en tienda |
| ドイツ | Vor ort aufladen |
HAQM Cash サービス (国によってサービス名が異なる場合があります) を使用すると、HAQM カスタマーは HAQM ギフト券の残高に資金をロードしたり、実店舗 (ブリック・アンド・モルタル：B&M) においてリアルタイムでギフト券コードを取得することができます。このトランザクションは、ディストリビューターの実店舗サイトのネットワーク内で開始され、ロードリクエストを処理し、該当するトランザクションを HAQM に直接ルーティングします。
パートナーの実店舗において顧客の HAQM アカウントを示すには、次の 2 つの方法があります。
- 顧客の HAQM アカウントに関連付けされているパーソナライズされたバーコード (HAQM が生成したもの) を表示する (購入者は HAQM のアプリまたは HAQM のウェブサイトから HAQM Cash バーコードを取得する)。
- 販売時点で HAQM アカウントに関連付けられている電話番号を入力/提供する。
注: アカウント識別形式やその他の詳細は、国によって異なる場合があります。
顧客の識別方法 (バーコードまたは電話番号など) に加えて、顧客は自分のアカウントにロードしたい資金の金額を店員に伝えます (米国では最低 5 ドル、1 回のロードにつき最大 500 ドル)。この情報は蓄積された後に HAQM に送信され、その後はロードリクエストの確認または拒否で応答します。以下に詳述するように、2 ステップまたは 1 ステップのロードリクエストプロセスを使用できます。
メトリックス
連携を開始するには、HAQM Cash のオンボーディング手順に記載されているステップバイステップガイドをご覧ください。
サインアップすると、大文字と小文字が区別される一意のパートナー ID が届きます。ユーザーのプログラムには、インセンティブ API へのすべてのリクエストにこの識別子が含まれます。
国別のトランザクションごとの最小金額と最大金額
| 国 | 通貨 | 最小トランザクション | 最大トランザクション |
|---|---|---|---|
| カナダ | CAD | C$ 5 | C$ 500 |
| フランス | EUR | € 5 | € 500 |
| イタリア | EUR | € 5 | € 500 |
| 日本 | JPY | ¥ 500 | ¥ 49 000 |
| メキシコ | MXN | $ 100 | $ 5 000 |
| スペイン | EUR | € 5 | € 500 |
| アラブ首長国連邦 | AED | 10 AED | 500 AED |
| 英国 | GBP | £ 5 | £ 250 |
| 米国 | USD | $ 5 | $ 500 |
注: リストに記載されていない国を対象とした連携の場合は、アカウントマネージャに最小ロード量と最大ロード量を確認してください。
2 ステップ残高ロードプロセス
2 ステップ残高ロードプロセスでは、次の 2 つの API を使用します。 ValidateAccountForHAQMBalanceLoad と LoadHAQMBalance。典型的なプロセスを以下に説明します。
- 店頭のレジ担当者が顧客の HAQM Cash バーコードをスキャンするか、電話番号を入力し、顧客がどのくらいの金額をロードするかを尋ねます。
- レジ担当者が POS ターミナルに金額を入力し、顧客に内容を確認します。
- POS が HAQM に ValidateAccountForHAQMBalanceLoad リクエストを送信します。HAQM がリクエストされた金額を HAQM ギフト券残高に読み込む資格があるかどうかをチェックします。
- ValidateAccountForHAQMBalanceLoad レスポンスによってリクエストが確認された場合、レジ担当者は顧客から現金を受け取り、POS はディストリビューターネットワークを介して HAQM に LoadHAQMBalance リクエストを送信します。HAQM では、事前のアクティベーション (つまり、店頭レジ担当者がお金を受け取る前にLoadHAQMBalance を呼び出す) を行うことを推奨していません。
- HAQM はリクエストを処理し、まず顧客の適格性を確認します。HAQM アカウントが特定できれば、リクエストされた資金を顧客の HAQM ギフト券残高にロードします。確認のレスポンスが送信されます。アカウントが不適格な場合は、却下レスポンスが返されます。残高のロード処理に対して顧客が電話番号を提供し、その電話番号を HAQM アカウントに関連付けることができない場合、オペレーションは有効なギフト券コードを提供する形で応答します。この場合、ギフト券コードは領収書に印刷し、顧客に渡さなければなりません。
図1.2 ステップ残高ロードプロセスの図
1 ステップ残高ロードプロセス
上記の 2 ステップの手順で説明されているように、ValidateAccountForHAQMBalanceLoad リクエストを送信できない場合は、LoadHAQMBalance リクエストを直接使用するように選択できます。ここでは、1 ステップ残高ロードプロセスについて説明します。
- 店頭のレジ担当者が顧客の HAQM Cash バーコードをスキャンするか、電話番号を入力し、顧客がどのくらいの金額をロードするかを尋ねます。
- レジ担当者は、POS ターミナルに金額を入力し、顧客に確認してから、現金を受け取ります。
- POS は、お客様のネットワークを使用して HAQM にLoadHAQMBalance リクエストを送信します。
- リクエストを処理するために、HAQM は顧客の資格を確認します。HAQM アカウントが特定できれば、HAQM はリクエストされた資金を顧客のギフト券の残高にロードします。確認のレスポンスが送信されます。アカウントが不適格な場合は、却下レスポンスが返されます。顧客が電話番号を提供し、その電話番号をどの HAQM アカウントにも関連付けることができない場合、オペレーションは有効なギフト券コードを提供する形で応答します。この場合、ギフト券コードは領収書に印刷し、顧客に提示する必要があります。
図 2.1 ステップ残高ロードプロセスの図
操作例
| API | 説明 |
|---|---|
| ValidateAccountForHAQMBalanceLoad | 顧客の HAQM アカウントが LoadHAQMBalance およびその他のチェックで使用できるかどうかを確認します。 |
| LoadHAQMBalance | 顧客の HAQM ギフト券残高に資金をロードします。HAQM アカウントが一致しない場合、顧客が後からオンラインで引き換えることができる、ギフト券コードを発行します。 |
| VoidHAQMBalanceLoad | 以前に成功した LoadHAQMBalance リクエストを無効にします。 |
リクエストパラメータ
アカウント
account パラメータは、エンドカスタマーをアクティブな HAQM カスタマーとして識別します。
これは、id と type で構成される複合構造です。
ID： HAQM が顧客の HAQM アカウントを特定するのに役立つ一意の識別子 (HAQM Cash の場合、ID はバーコード番号または顧客の電話番号になります)。
オペレーションでは、次の 2 つのタイプ値がサポートされます。
| 値 | 説明 |
|---|---|
| 1 | バーコード |
| 4 | 電話番号 |
| 2、3 | これらの値は、HAQM Cash と無関係な商品にのみ適用され、使用しないでください。 |
type： エンドカスタマーのアカウント ID のタイプ。バーコード、電話番号、メールアドレスなどの顧客識別子をサポートします。
partnerId
partnerId パラメータは、オンボーディングプロセス中に HAQM から提供される一意の識別子です。この値は、HAQM のパートナー連携マネージャーによって割り当てられ、ディストリビューターを一意に識別します。この値では、大文字と小文字が区別されます。
loadBalanceRequestId
リクエストを表すために生成する一意の識別子。この値の先頭には partnerId 値が付けられ、40 文字未満である必要があります。
amount
amount パラメータは、ロードする資金を指定します。通貨コードと値で構成される複合パラメータです。
currencyCode: ISO-4217 の通貨コード。value: リクエストされた金額の値。このフィールドは整数です (例： 100.23は10023)。小数点に対応していない通貨では、パディングは必要ありません。たとえば、日本では、231 円は 231 になり、23100 ではありません。
timestamp
リクエストを開始した際に 1970 年 1 月 1 日 00:00 UTC から経過したのミリ秒単位の UNIX UTC のタイムスタンプ。
例： 2018-08-23T15:34:43+00:00 は 1535038483000 になります
voidIfUsed
エンドカスタマーがすでに資金 (すべてまたは一部) を使用していても、LoadHAQMBalance を無効にするかどうかを示すブール値。
使用例： 顧客がロードされた資金の一部をすでに使用して、void リクエストが行われた場合、元のロードされた金額から、残りの資金がすべて取り消されます。
HAQM Cash のユースケースの場合、この値は常に true である必要があります。
transactionSource
HAQM Balance Load が生成された場所を特定するための位置情報データ。このパラメータは HAQM Cash の商品に必要です。
このパラメータは、次の項目を組み合わせたものです。
| 項目 | 説明 |
|---|---|
sourceId |
トランザクションソースエンティティの識別子 (例： ストア番号またはストア ID)。 |
institutionId |
トランザクションソースの親エンティティの識別子 (例： マーチャント ID)。親エンティティが存在しない場合は、sourceId をコピーします。 |
sourceDetails |
トランザクションソースの詳細情報を提供する文字列。 |
sourceDetails の値には、ソースの名前として値を持つ institutionName キーが含まれている必要があります (例：マーチャント名)。ソースの場所、電話番号などの情報を含める必要があります。
institutionName の値は、資金が追加されたことを示すメールの次の文に表示されます： 「資金が institutionName の HAQM 残高に追加されました。」
HAQM ストアの位置情報データを送信するには、2 つのオプションがあります。
- 長い形式：トランザクション (
sourceId、institutionId、sourceDetailsを含める必要があります) ごとに特定の店舗の位置情報データを指定します。 - 短い形式：API リクエストに
sourceIdとinstitutionIdのみを指定します。HAQM がデータを解析できるように、別の位置情報マッピングファイルを送信する必要があります。
注： sourceDetails は、次の例のように JSON Blob としてフォーマットする必要があります。
"transactionSource":{
"sourceId":"558978547",
"institutionId":"97263700008",
"sourceDetails":"{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}"
}
トランザクションソースの例については、「実店舗トランザクションソース」を参照してください。
バーコードアカウントタイプ
前提条件
HAQM Cash 製品と連携し、アカウントタイプ 1 (バーコードベース) をサポートするには、POS (販売時点情報管理) システムに、携帯電話のバーコードをスキャンし、コード 128 形式の 1D バーコードをサポートできるバーコードスキャナーが必要です。
バーコード形式
HAQM は、バーコードの構築に独自の製品コードと IIN を使用します。HAQM バーコードの長さは 30 桁で、次の要素で構成されます。
- 11 桁の UPC
- 13 桁の EAN または JAN
- 6 桁の IIN
- 12 桁の PAN
- 1 桁のチェックサム
HAQM はLUHN アルゴリズムを使用してチェックサム桁を生成し、アルゴリズムは IIN + PAN に適用されます。
以下の HAQM の商品コード (UPC/EAN/JAN) と IIN およびバーコードの例をご覧ください。製品コードは国によって異なることに注意してください。
製品コード (UPC 11、EAN 13、JAN 13)
| 国 | 製品コードの例 |
|---|---|
| 米国 | 85143200701 |
| カナダ | 85143200702 |
| メキシコ | 85143200703 |
| 英国 | 85143200704 |
| ドイツ | 1230000042413 |
| フランス | 1230000042512 |
| イタリア | 85143200707 |
| スペイン | 1230000042727 |
| 日本 | 4582274041003 |
- グローバル発行者識別番号 (IIN)： 608574
図3.1a 30 桁のバーコードの例
図4.1b 32 桁のバーコードの例
電話番号アカウントタイプ
前提条件
電話番号は、サポートされている別のアカウントタイプ (タイプ 4) です。HAQM Cash 製品と連携し、電話番号のアカウントタイプをサポートするには、POS システムでオペレーターが電話番号の桁を入力し、動的なギフト券コードで領収書を印刷できるようにする必要があります。特定のシナリオでは、HAQM Cash トランザクションは、顧客が後でアカウントに入金するためにオンラインで利用できる動的なギフト券コードを含む紙の領収書を返却する必要があります。
電話番号の形式
電話番号の入力は、次のいずれかの形式に従う必要があります。
| 形式 | 説明 |
|---|---|
| E.164 形式 | E.164 は、公衆網の各デバイス (公衆交換電話網) がグローバルに一意の番号を持つことを保証する国際電話番号計画です。 |
| ローカル番号の形式 | 厳密に数値です。つまり、ダッシュ、スペース、または括弧 (-, ' ', or ()) を含めることはできません。番号は有効なローカル番号で、市外局番を含める必要があります。たとえば、米国では、有効なローカル番号は10桁で、2066231234 のように設定されます。 |
E.164 番号は最大 15 桁で、次のようにフォーマットされます。
[+] [国コード] [市外局番を含む加入者番号]
たとえば、+14155552671 (米国番号)、+442071838750 (英国番号) のように指定します。
電話番号を E.164 形式で送信することをお勧めします。
注: 現在、トランザクションが行われている対応国でのローカル電話番号のみをサポートしています。したがって、顧客がたとえば米国のお店でメキシコの電話番号を使用しようとすると、トランザクションは POS で拒否されます。
領収書の要件
領収書の要件は、LoadHAQMBalance の呼び出しによる電話フォームファクタベースのロードが顧客のアカウント (確認済みの電話番号) に資金を適用したか、またはギフト券コード (未確認の電話番号) を発行したかに応じて、POS システムのコンテンツを変更できるかどうかによって異なります。
| シナリオ | ギフト券コードは領収書に表示されますか？ | 指示テキスト (POS が領収書テキストを変更できる場合) |
|---|---|---|
| 確認済みの電話番号 | いいえ。 (資金が顧客の口座に自動的に適用されます。LoadHAQMBalance レスポンスにはギフト券コードは含まれません。) |
HAQM 残高に資金が追加されました。 HAQM Cash のトランザクションは、法律で定められている場合を除き、返金できません。HAQM Cash に資金が追加されたという確認が届くまで、この領収書を保管してください。その他の制限事項が適用されます。利用規約全文については、www.amazon.co.jp/gc-legal を参照してください。 |
| 未確認の電話番号 | はい。 (LoadHAQMBalance がギフト券コードを発行します) |
ギフト券コード： AR7E-VJTKKU-TFJ トランザクションが完了していません。www.amazon.co.jp/gc/redeem にアクセスし、この領収書に記載されているギフト券コードを入力して、HAQM 残高に資金を追加しない限り、資金は追加されません。 HAQM Cash のトランザクションは、法律で定められている場合を除き、返金できません。その他の制限事項が適用されます。利用規約全文については、www.amazon.co.jp/gc-legal を参照してください。 |
| 有効なバーコード | いいえ。 (資金が顧客の口座に自動的に適用されます。LoadHAQMBalance レスポンスにはギフト券コードは含まれません) |
HAQM 残高に資金が追加されました。 |
| 無効なバーコード | いいえ。 (トランザクションが失敗します。LoadHAQMBalance レスポンスにはギフト券コードは含まれません。) |
(領収書を印刷する必要がないか、トランザクションに失敗した領収書を印刷する必要があります。) |
デフォルトの指示テキスト
POS システムが領収書の内容を変更できない場合は、次のテキストが表示されます。
- HAQM 残高に資金が追加されたという確認が届くまで、この領収書を保管します。資金が自動的にアカウントに振り込まれていない場合は、www.amazon.co.jp/gc/redeem にアクセスしてトランザクションを完了してください。HAQM Cash のトランザクションは、法律で定められている場合を除き、返金できません。その他の制限事項が適用されます。利用規約全文については、www.amazon.co.jp/gc-legal を参照してください。
ValidateAccountForHAQMBalanceLoad
ValidateAccountForHAQMBalanceLoad 操作は、対象となる金額がこの国で許可されている範囲内にあるかどうかを検証し、顧客の HAQM アカウントが残高のロードプロセスの対象であるかどうかを確認します。
バーコードアカウントタイプの場合、適格性チェックは、バーコードが有効な HAQM カスタマーアカウントにリンクされており、HAQM ギフト券残高に資金を追加することが承認されているかどうかを検証します。
電話番号アカウントタイプの場合、指定された電話番号が有効な電話番号であることが検証されます。電話が 1 つの HAQM カスタマーアカウントに関連付けられていると識別できる場合は、顧客の適格性ステータスも検証されます。そうしないと、身元不明の電話番号 (HAQM のカスタマーに関連付けられていない) は拒否されず、有効なアカウントとして扱われます。この場合、オペレーションはPARTIAL_SUCCESSで応答します。このような未確認の電話番号の場合、LoadHAQMBalance 操作は後で顧客が手動で引き換えるためのギフト券コードを返します。
注： この操作は推奨されますが、後で HAQM のLoadBalance 操作を成功させるための前提条件ではありません。
リクエストパラメータ
図 5 ValidAccountForHAQMBalance のリクエストパラメータ
成功レスポンス、部分的な成功レスポンス
図 6 ValidAccountForHAQMBalanceLoad の成功レスポンス
失敗レスポンス
以下の必須文字列は、ValidateAccountForHAQMBalanceLoadException に表示されます。
errorCodeerrorTypeerrorMessagestatus例 1： バーコードタイプのアカウントに対するリクエストと成功レスポンス
リクエスト
POST /ValidateAccountForHAQMBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.haqm.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.ValidateAccountForHAQMBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
Payload=
<ValidateAccountForHAQMBalanceLoadRequest>
<account>
<id>851432007016085741001033001453</id>
<type>1</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<timestamp>1464933146000</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails>
{"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
</sourceDetails>
</transactionSource>
</ValidateAccountForHAQMBalanceLoadRequest>
レスポンス
<ValidateAccountForHAQMBalanceLoadResponse>
<account>
<id>851432007016085741001033001453</id>
<type>1</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>
例 2： 電話番号タイプのアカウントに対するリクエストと成功レスポンス
リクエスト
POST /ValidateAccountForHAQMBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.haqm.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForHAQMBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadHAQMBalanceRequest>
<account>
<id>2061231234</id>
<type>4</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<timestamp>1464933146000</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails>{ "institutionName": "Walgreens",
"Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone": "+12061232333"}
</sourceDetails>
</transactionSource>
</LoadHAQMBalanceRequest>
レスポンス
<ValidateAccountForHAQMBalanceLoadResponse>
<account>
<id>+12061231234</id>
<type>4</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>
例 3： 電話番号タイプのアカウントのリクエストと一部成功レスポンス
リクエスト
POST /ValidateAccountForHAQMBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.haqm.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForHAQMBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<ValidateAccountForHAQMBalanceLoadRequest>
<account>
<id>2061231235</id>
<type>4</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<timestamp>1464933146000</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails>
{"institutionName":"Walgreens", "Address":"1234 Sample
Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
</sourceDetails>
</transactionSource>
</ValidateAccountForHAQMBalanceLoadRequest>
レスポンス
<ValidateAccountForHAQMBalanceLoadResponse>
<account>
<id>+12061231235</id>
<type>4</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>PARTIAL_SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>
例 4： 失敗レスポンス
失敗レスポンス
<ValidateAccountForHAQMBalanceLoadException>
<errorCode>F200</errorCode>
<errorType>InvalidRequestInput</errorType>
<errorMessage>API request body is null/empty</errorMessage>
<status>FAILURE</status>
</ValidateAccountForHAQMBalanceLoadException>
例 5： 失敗レスポンスの再送信
失敗レスポンス
<ValidateAccountForHAQMBalanceLoadException>
<errorCode>F400</errorCode>
<errorType>SystemTemporarilyUnavailable</errorType> <errorMessage>HAQM system is temporarily not available</errorMessage>
<status>RESEND</status>
</ValidateAccountForHAQMBalanceLoadException>
F400 エラーでは、意図しない支出が発生しないように、慎重な再試行処理が必要です。「エラー処理」を参照してください。
例 6： レスポンスの比較 (バーコードと電話番号タイプの場合)
電話番号が確認された場合の電話番号タイプ (タイプ値 4) に対するレスポンス
確認済み電話番号 (電話番号が HAQM アカウントに関連付けられ、確認済み)
<ValidateAccountForHAQMBalanceLoadResponse>
<account>
<id>+14252134543</id>
<type>4</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>
未確認の電話番号 (HAQM アカウントに関連付けられていない、または確認されていない電話番号)
<ValidateAccountForHAQMBalanceLoadResponse>
<account>
<id>+14252134543</id>
<type>4</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>
<ValidateAccountForHAQMBalanceLoadResponse>
<account>
<id>+12061231234</id>
<type>4</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>PARTIAL_SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>
バーコードタイプのレスポンス (タイプ値 1)
有効/アクティブなバーコード
<ValidateAccountForHAQMBalanceLoadResponse>
<account>
<id>851432007016085741001033001453</id>
<type>1</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
</ValidateAccountForHAQMBalanceLoadResponse>
無効/非アクティブなバーコード
<ValidateAccountForHAQMBalanceLoadException>
<errorCode>F200</errorCode>
<errorType>UndefinedAccountId</errorType>
<errorMessage>AccountId provided in request does not exist in HAQM system</errorMessage>
<status>FAILURE</status>
</ValidateAccountForHAQMBalanceLoadException>
LoadHAQMBalance
LoadHAQMBalance 操作は、顧客の HAQM ギフト券残高に資金をロードするか、有効なギフト券コードを返します (指定された電話番号が未確認の場合、つまり HAQM アカウントで電話番号が確認されていない場合)。この操作は、HAQM が同一のすべてのパラメータ (account、partnerId、amount、transactionSource) を持つloadBalanceRequestId の LoadHAQMBalance リクエストを受ける場合、最初の呼び出しからの同じレスポンスが返されます。指定する loadBalanceRequestId の長さは最大 40 文字で、partnerId をプレフィックスとして付け、一意である必要があります。
リクエストパラメータ
図 8 LoadBalanceRequest のパラメータ
バーコードアカウントタイプの成功レスポンス
図 9 LoadBalanceRequest の成功
電話番号アカウントタイプに対する成功レスポンス
LoadHAQMBalance レスポンスパラメータ
| パラメータ名 | 必須 | 制約 | 警告数 |
|---|---|---|---|
account |
はい | – | オブジェクト |
loadBalanceRequestId |
はい | プレフィックス済みとpartnerId (最大40文字) |
文字列 |
amount |
はい | – | オブジェクト |
status |
はい | – | 文字列 |
additionalInfo |
はい | – | オブジェクト |
additionalInfoフィールドは JSON 形式のテキストで、ギフト券コードなどの情報が含まれています。詳細については、例を参照してください。
失敗レスポンス
LoadHAQMBalanceException には、4 つの文字列パラメータが含まれています。
- errorCode
- errorType
- errorMessage
- status
LoadHAQMBalance の失敗レスポンスの例：
<LoadHAQMBalanceException>
<errorCode>F100</errorCode>
<errorType>GeneralError</errorType>
<errorMessage>HAQM Internal Error</errorMessage>
<status>FAILURE</status>
</LoadHAQMBalanceException>
例 1： バーコードタイプのアカウントに対するLoadHAQMBalance リクエストと成功レスポンス
リクエスト
POST /LoadHAQMBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadHAQMBalanceRequest>
<account>
<id>851432007016085741001033001453</id>
<type>1</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<timestamp>1464933146000</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails>{ "institutionName": "Walgreens",
"Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone": "+12061232333"}
</sourceDetails>
</transactionSource>
</LoadHAQMBalanceRequest>
レスポンス
<LoadHAQMBalanceResponse>
<account>
<id>851432007016085741001033001453</id>
<type>1</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</LoadHAQMBalanceResponse>
例 2： LoadHAQMBalance リクエストと成功レスポンス (電話番号のアカウントタイプ) と未確認の電話番号 (ギフト券コードは手動で申請する必要があります)
リクエスト
POST /LoadHAQMBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadHAQMBalanceRequest>
<account>
<id>2061231234</id>
<type>4</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<timestamp>1464933146000</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails>{ "institutionName": "Walgreens",
"Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone": "+12061232333"}
</sourceDetails>
</transactionSource>
</LoadHAQMBalanceRequest>
成功レスポンス
<LoadHAQMBalanceResponse>
<account>
<id>+12061231234</id>
<type>4</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<additionalInfo>
{"claimcode":"ABCD-EFGH-JK123"}
</additionalInfo>
</LoadHAQMBalanceResponse>
失敗レスポンス
<LoadHAQMBalanceException>
<errorCode>F100</errorCode>
<errorType>GeneralError</errorType>
<errorMessage>HAQM Internal Error</errorMessage>
<status>FAILURE</status>
</LoadHAQMBalanceException>
例 3： LoadHAQMBalance リクエストと成功レスポンス (電話番号のアカウントタイプ) と確認済みの電話番号 (資金は自動的に適用/請求されます)
リクエスト
POST /LoadHAQMBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadHAQMBalanceRequest>
<account>
<id>2061231234</id>
<type>4</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<timestamp>1464933146000</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails>
{"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10,
Seattle, WA, US, 98101", "Phone":"+12061232333"}
</sourceDetails>
</transactionSource>
</LoadHAQMBalanceRequest>
レスポンス
<LoadHAQMBalanceResponse>
<account>
<id>+12061231234</id>
<type>4</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<additionalInfo>{"claimcode":"XXXX-XXXXXX-XXXX"}</additionalInfo>
</LoadHAQMBalanceResponse>
LoadHAQMBalance の失敗レスポンスの例：
失敗レスポンス
<LoadHAQMBalanceException>
<errorCode>F100</errorCode>
<errorType>GeneralError</errorType>
<errorMessage>HAQM Internal Error</errorMessage>
<status>FAILURE</status>
</LoadHAQMBalanceException>
LoadHAQMBalance の再送信レスポンスの例：
失敗レスポンス
<LoadHAQMBalanceException>
<errorCode>F400</errorCode>
<errorType>SystemTemporarilyUnavailable</errorType>
<errorMessage>HAQM system is temporarily not available</errorMessage>
<status>RESEND</status>
</LoadHAQMBalanceException>
実店舗での追加要件
実店舗で発生するすべての LoadHAQMBalance への呼び出しには、トランザクションが発生した場所の詳細を含める必要があります。これらのエンドポイントへのリクエストには、イベントの物理的な場所を記述する transactionSource オブジェクトを含めることができます。
注： ログイン＆レシーブで使用される LoadHAQMBalance には、transactionSource オブジェクトを含めることはできません。
transactionSource のフィールド |
説明 |
|---|---|
sourceId |
トランザクションソースエンティティの識別子 (例： ストア番号またはストア ID)。 |
institutionId |
トランザクションソースの親エンティティの識別子 (例： マーチャント ID)。親エンティティが存在しない場合は、sourceId をコピーします。 |
sourceDetails |
トランザクションソースの詳細情報を提供する文字列。これは、institutionName キーと、その値としてソース名 (マーチャント名など) が含まれている必要があります。ソースの場所、電話番号などの情報を含める必要があります。 |
institutionParentCompany |
instituitionName の親会社名です。親会社がない場合は、institutionName を繰り返す必要があります。 |
HAQM に店舗ロケーションデータを送信するには、次の 2 つのオプションがあります。
- 長い形式 - パートナーは、トランザクションごとに特定の店舗ロケーションデータを含めます (
sourceId、institutionId、sourceDetailsを含める必要があります)。 - 短い形式 - パートナーは API リクエストに
sourceIdとinstitutionIdのみを指定します。これらの識別子を物理的な場所にマップする個別のロケーションマッピングファイルを送信する必要があります。ロケーションマッピングファイルの手順はこのスプレッドシートを参照してください。
XML 形式と JSON 形式のトランザクションソースの「長い形式」ペイロードのサンプルを以下に示します。sourceDetails は JSON blob としてフォーマットする必要があることに注意してください。JSON の例では、JSON blob はバックスラッシュを使用して引用符をエスケープします。
XML 本文の長い形式の例 (sourceDetails の値はJSON blob としてフォーマットする必要があります)：
<LoadHAQMBalanceRequest>
<account>
<id>851432007016085741001033001453</id>
<type>1</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<timestamp>1464933146</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails>{ "institutionName": "Walgreens",
"Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone": "+12061232333"}
</sourceDetails>
</transactionSource>
</LoadHAQMBalanceRequest>
transactionSource の JSON 本文の短い形式の例：
{
"loadBalanceRequestId": "Amxx134565",
"partnerId": "Amxx1",
"amount": {
"currencyCode": "USD",
"value": 1000
},
"account": {
"id": "5551112222",
"type": "4"
},
"timestamp": 1574704599588,
"transactionSource": {
"sourceId": "12345",
"institutionId": "A123"
},
"externalReference": "serviceId:123",
"notificationDetails": {
"notificationMessage": "Thank you for loading balance at 12345!"
}
}
VoidHAQMBalanceLoad
POS がリクエストを正常に実行したことを保証できない場合 (たとえば、ネットワークの問題によるメッセージの欠落など)、POS またはディストリビューターは VoidHAQMBalanceLoad リクエストを実行して、資金が顧客の HAQM ギフト券残高に追加されないようにする必要があります。POS で障害が発生した場合、レジ担当者は常に現金をエンドカスタマーに返します。VoidHAQMBalanceLoad を実行することの重要性は、資金が正常に追加されたものの、確認メッセージが POS で受信されなかった場合に備えて、顧客の HAQM ギフト券残高からすぐに金額が削除されるようにすることです。
VoidHAQMBalanceLoad 操作では、元のリクエストから 15 分以内に限り、LoadHAQMBalance の正常なリクエストを無効化します。VoidHAQMBalanceLoad 操作は、LoadHAQMBalance リクエストから資金をロードするために使用された元の loadBalanceRequestId を必要とします。currencyCode、value、sourceId、institutionId の各フィールドは、元の LoadHAQMBalance シングリクエストで提供された各値と一致する必要があります。VoidHAQMBalanceLoad 操作は冪等です｡
リクエストパラメータ
図12 VoidHAQMBalanceLoad リクエストの図
成功レスポンス
図13 VoidHAQMBalanceLoad の成功レスポンスの図
失敗レスポンス
VoidHAQMBalanceLoad リクエストが失敗すると、以下の文字列パラメータを含む VoidHAQMBalanceLoad 例外が返されます。
errorCodeerrorTypeerrorMessagestatus
例 1： VoidHAQMBalanceLoad リクエストと成功レスポンス (バーコードアカウントタイプ)：
リクエスト
POST /VoidHAQMBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidHAQMBalanceLoadRequest>
<account>
<id>851432007016085741001033001453</id>
<type>1</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<timestamp>1464933146000</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails{"institutionName":"Walgreens",
"Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone":"+12061232333"}</sourceDetails>
</transactionSource>
<voidIfUsed>True</voidIfUsed>
</VoidHAQMBalanceLoadRequest>
レスポンス
<VoidHAQMBalanceLoadResponse>
<account>
<id>851432007016085741001033001453</id>
<type>1</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</VoidHAQMBalanceLoadResponse>
例 2： VoidHAQMBalanceLoad リクエストと成功レスポンス (電話番号のアカウントタイプ)：
リクエスト
POST /VoidHAQMBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.haqm.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidHAQMBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidHAQMBalanceLoadRequest>
<account>
<id>7574662233</id>
<type>4</type>
</account>
<partnerId>PartnerUS</partnerId>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
<timestamp>1464933146000</timestamp>
<transactionSource>
<sourceId>12344332</sourceId>
<institutionId>A1234</institutionId>
<sourceDetails>{"institutionName":"Walgreens",
"Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone":"+12061232333"}</sourceDetails>
</transactionSource>
<voidIfUsed>True</voidIfUsed>
</VoidHAQMBalanceLoadRequest>
レスポンス
<VoidHAQMBalanceLoadResponse>
<account>
<id>+17574662233</id>
<type>4</type>
</account>
<amount>
<currencyCode>USD</currencyCode>
<value>4570</value>
</amount>
<status>SUCCESS</status>
<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</VoidHAQMBalanceLoadResponse>
例 3： VoidHAQMBalanceLoad の失敗レスポンスの例：
失敗レスポンス
<VoidHAQMBalanceLoadException>
<errorCode>F200</errorCode>
<errorType>LoadBalanceRequestIdDoesNotExist</errorType>
<errorMessage>Balance Load with provided loadBalanceRequestId does not exist</errorMessage>
<status>FAILURE</status>
</VoidHAQMBalanceLoadException>
例 4： VoidHAQMBalanceLoad の再送信レスポンスの例：
失敗レスポンス
<VoidHAQMBalanceLoadException>
<errorCode>F400</errorCode>
<errorType>SystemTemporarilyUnavailable</errorType>
<errorMessage>HAQM system is temporarily not available</errorMessage>
<status>RESEND</status>
</VoidHAQMBalanceLoadException>
テストデータ
開発中のテストを支援するために、テスト (haqm.com) アカウントを作成しました。サンドボックス環境と本番環境では別のアカウントを使用できます。これらのトークンは、http://s3.amazonaws.com/AGCOD/tech_spec/amazon-test-tokens.txt で参照してください。
また、ユーザーのプログラムが一般的なリクエストの失敗をどのように処理するかをテストするために使用できるモックコードも参照してください。
デジタル署名：署名プロセス
インセンティブ API 操作へのすべてのリクエストは、インセンティブ API セキュリティ認証情報と署名バージョン 4 の署名アルゴリズムを使用してデジタル署名する必要があります。
AWS V4 署名の例
(US-East-1 リージョン内)
署名するペイロード：
{
"account": {
"id": "0360002414571003423331033001453",
"type": "1"
},
"partnerId": "PartnerUS",
"amount": {
"currencyCode": "USD",
"value": 4570
},
"loadBalanceRequestId": "PartnerUSrequestId1",
"timestamp": 1464933146000,
"transactionSource": {
"sourceId": "12344332",
"institutionId": "A1234",
"sourceDetails": "{'name': 'Store'}"
}
}
ハッシュ化されたペイロード
24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1
正規リクエスト (空の行を含む)
POST
/LoadHAQMBalance
accept:application/json content-type:application/json host:agcod-v2-gamma.haqm.com x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
accept;content-type;host;x-amz-date;x-amz-target
24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1
ハッシュ化された正規リクエスト
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14
署名する文字列
AWS4-HMAC-SHA256
20160708T073147Z
20160708/us-east-1/AGCODService/aws4_request
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14
派生した署名キー
780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453
署名
(AWS 認証情報が異なるため、署名は異なります。)
66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a
署名済みペイロード
POST /LoadHAQMBalance HTTP/1.1
accept:application/json content-type:application/json host:agcod-v2-gamma.haqm.com x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance Authorization:AWS4-HMAC-SHA256 Credential=<Access Key Id used for signing>/20160708/useast-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a
{
"account": {
"id": "0360002414571003423331033001453",
"type": "1"
},
"partnerId": "PartnerUS",
"amount": {
"currencyCode": "USD",
"value": 4570
},
"loadBalanceRequestId": "PartnerUSrequestId1",
"timestamp": 1464933146000,
"transactionSource": {
"sourceId": "12344332",
"institutionId": "A1234",
"sourceDetails": "{'name': 'Store'}"
}
}