インスタント支払通知(IPN)を設定する

Amazon Payトランザクションに関連するイベントの通知を受信するように、インスタント支払通知(IPN)を設定します。 IPNを使用して注文の状態を更新し、トランザクションを処理します。

Note:IPNは 非同期トランザクションからの更新を処理するために使用されます。


IPNの概要

IPNメッセージは、構成可能なエンドポイントに送信されるHTTPS POSTリクエストです。 IPN Message JSONオブジェクトを解析します。

IPNスキーマ

{
    "MerchantID": "Relevant Merchant for the notification",
    "ObjectType": "one of: CHARGE_PERMISSION, CHARGE, REFUND, CHARGEBACK", 
    "ObjectId": "Id of relevant object",
    "ChargePermissionId": "Id of relevant Charge Permission",
    "NotificationType": "STATE_CHANGE",
    "NotificationId": "Randomly generated Id, used for tracking only",
    "NotificationVersion": "V2"
}

IPNパラメータ

パラメータ
説明
merchantID
IPNメッセージに関連付けられて事業者の識別子
objectType
IPNメッセージに関連付けられているオブジェクトのタイプ

可能な値: "CHARGE_PERMISSION"、CHARGE "、" REFUND "、" CHARGEBACK "
objectId
IPNメッセージに関連付けられているオブジェクトの識別子
chargePermissionId
IPNメッセージに関連付けられたCharge Permissionの識別子
notificationType
IPNメッセージタイプ

可能な値: "STATE_CHANGE"、"ATTRIBUTE_CHANGE"
notificationId
IPNメッセージ識別子。追跡目的でのみ使用されます
notificationVersion
IPNメッセージ形式のversion。これはAmazon Pay API versionとは関係ありません。

トランザクションの状態を判別するには、メッセージで指定されたトランザクションに対してGET API実行する必要があります。詳細については、「IPNタイプ」セクションを参照してください。


IPNエンドポイントの設定

Amazon Pay事業者のアカウント管理サイト セラーセントラルで本番環境ととSANDBOX環境のセットアップIPNエンドポイントを設定することができます。画面上部のメニュー中央にあるドロップダウンオプションから環境を選択します。

画面が最小化されている場合、environmentとドロップダウンオプションは次のボタンに置​​き換えられます。

環境を選択したら、次の手順に従ってIPNメッセージの受信を開始します。

  1. セラーセントラルでエンドポイントを設定します。
    1. エンドポイントを設定するには、 セラーセントラルにサインインし、[設定]をクリックして、[インテグレーション設定]をクリックします。
    2. [インスタント通知の設定]セクションで、[編集]をクリックし、インスタント通知を受信するエンドポイントで事業者URLを入力します。本番環境ではHTTPSを使用する必要がありますが、SANDBOX環境では、HTTPSの代わりにHTTPを使用できます。ただし、HTTPSエンドポイントを指定する場合は、証明書が有効であり、証明書チェーンがルート証明書に接続されている必要があります。
    3. インテグレーターが2つの異なるエンドポイントで同じイベントのIPNを受信する必要がある場合は、Integrator URLフィールドにURLを入力できます。
  2. https://digicert.com/help/などのツールを使用してエンドポイントとSSL証明書をチェックし、それらが正しく機能していることを確認します。
  3. エンドポイントに対して行われたHTTPS POSTリクエストを受信し、通知を処理できるWebサービスを実行していることを確認します。ユーザーログインを必要とする.htaccessルールなどの潜在的なアクセス保護を削除します。
  4. HTTPSが信頼できる証明書プロバイダーからの有効なSSL証明書を使用していることを確認します。詳細については、 SSL認証を参照してください。

IPNタイプ

Charge Permission

Charge Permissionオブジェクトのstateが変化するたびにIPNを受け取ります。なお、いくつかのIPNはRecurringのケースのみに送付され、OneTimeでは送付されません。 IPNを受け取るタイミングの例:

  • 購入者が pay.amazon.co.jpでOneTime及びRecurringのCharge Permissionの支払い方法を更新
  • 支払いでdeclineとなり、RecurringのCharge Permissionがchargeableからnon-chargeablestateに移行
  • 購入者が pay.amazon.co.jpでRecurringのCharge Permissionをキャンセル
  • 不正取引のためにAmazon PayがRecurringのCharge Permissionを閉じるかキャンセル
  • 13か月間使用されなかった為、Amazon PayがRecurringのCharge Permissionをclosed stateに移行

IPNメッセージの例

{
    "Type" : "Notification", 
    "MessageId" : "a7045d68-12c9-5bc2-8447-0bb63262b8dd", 
    "TopicArn" : "arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54",
    "Message" : "{\"MerchantID\":\"AEMGQX8TKDO54\",\"ObjectType\":\"CHARGE_PERMISSION\",\"ObjectId\":\"S01-0539563-2966012\",\"NotificationType\":\"STATE_CHANGE\",\"NotificationId\":\"dda4e3a5-ed5f-4766-b47f-4d8eb133bb01\",\"NotificationVersion\":\"V2\"}",
    "Timestamp" : "2020-03-07T22:21:31.169Z",
    "SignatureVersion" : "1", 
    "Signature" : "hyj+azIy4dxAf2JmB/AgNSYmW+vL09+wXUq4oiLUUhfgQY1/wvNzT5Nq3ezF1+/EjVc+5RTe0axXgyhTn3vUO93q9nmWXm+LjojbGilcSg0Ey40P5XEaOTYhVWzq12ffR5cUqG2PN0uLFN2WQuNIFCko3uPf1N74mnQNj27FWVUt/NjNwZ6kigJBmzio/Vv25B6RGXp71fXPunT5CeoGkcQyhlUn3l0Y65jME0OjNaQhAG05t1F8D8h1vY9ouRjiTuUCdiprv6udnb1P3WyK4JtdAJ3OtORkKK73gklSKzC2rQL7y1VDOE2C4wJZcVxj57EcQFFkb4wAfzsUeZ+Sfg==",
    "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem",
    "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54:9bea22b9-d89f-452c-bf36-4d6d20e12df4"
}

Charge

Chargeオブジェクトのstateが変化するたびにIPNを受け取ります。 Get Chargeを使用してChargeの状態を確認し、Chargeが成功したかどうかを確認します。 IPNを受け取るタイミングの例:

  • Create Chargeを実行。
  • Chargeのオーソリ実施すると、AuthorizationInitiated状態で保留のレスポンスを受信します
  • Chargeの売上請求実施すると、CaptureInitiated状態で保留のレスポンスを受信します
  • Chargeがキャンセルされる

IPNメッセージの例

{
    "Type" : "Notification", 
    "MessageId" : "a7045d68-12c9-5bc2-8447-0bb63262b8dd", 
    "TopicArn" : "arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54",
    "Message" : "{\"MerchantID\":\"AEMGQX8TKDO54\",\"ObjectType\":\"CHARGE\",\"ObjectId\":\"S01-0000000-0000000-C000000\",\"ChargePermissionId\":\"S01-0000000-0000000\",\"NotificationType\":\"STATE_CHANGE\",\"NotificationId\":\"dda4e3a5-ed5f-4766-b47f-4d8eb133bb01\",\"NotificationVersion\":\"V2\"}",
    "Timestamp" : "2020-03-07T22:21:31.169Z",
    "SignatureVersion" : "1", 
    "Signature" : "hyj+azIy4dxAf2JmB/AgNSYmW+vL09+wXUq4oiLUUhfgQY1/wvNzT5Nq3ezF1+/EjVc+5RTe0axXgyhTn3vUO93q9nmWXm+LjojbGilcSg0Ey40P5XEaOTYhVWzq12ffR5cUqG2PN0uLFN2WQuNIFCko3uPf1N74mnQNj27FWVUt/NjNwZ6kigJBmzio/Vv25B6RGXp71fXPunT5CeoGkcQyhlUn3l0Y65jME0OjNaQhAG05t1F8D8h1vY9ouRjiTuUCdiprv6udnb1P3WyK4JtdAJ3OtORkKK73gklSKzC2rQL7y1VDOE2C4wJZcVxj57EcQFFkb4wAfzsUeZ+Sfg==",
    "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem",
    "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54:9bea22b9-d89f-452c-bf36-4d6d20e12df4"
}

Refund

返金オブジェクトのstateが変わるたびにIPNを受け取ります。返金は非同期で処理されるため、返金の処理が完了するとIPNを受け取ります。 Get Refundを使用して返金の状態を確認し、返金が成功したかどうかを確認します。

IPNメッセージの例

{
    "Type" : "Notification", 
    "MessageId" : "a7045d68-12c9-5bc2-8447-0bb63262b8dd", 
    "TopicArn" : "arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54",
    "Message" : "{\"MerchantID\":\"AEMGQX8TKDO54\",\"ObjectType\":\"REFUND\",\"ObjectId\":\"S01-0000000-0000000-R000000\",\"ChargePermissionId\":\"S01-0000000-0000000\",\"NotificationType\":\"STATE_CHANGE\",\"NotificationId\":\"326100f2-eyd3-4a8b-113d-8f48cd2f8f0w\",\"NotificationVersion\":\"V2\"}",
    "Timestamp" : "2020-03-07T22:21:31.169Z",
    "SignatureVersion" : "1", 
    "Signature" : "hyj+azIy4dxAf2JmB/AgNSYmW+vL09+wXUq4oiLUUhfgQY1/wvNzT5Nq3ezF1+/EjVc+5RTe0axXgyhTn3vUO93q9nmWXm+LjojbGilcSg0Ey40P5XEaOTYhVWzq12ffR5cUqG2PN0uLFN2WQuNIFCko3uPf1N74mnQNj27FWVUt/NjNwZ6kigJBmzio/Vv25B6RGXp71fXPunT5CeoGkcQyhlUn3l0Y65jME0OjNaQhAG05t1F8D8h1vY9ouRjiTuUCdiprv6udnb1P3WyK4JtdAJ3OtORkKK73gklSKzC2rQL7y1VDOE2C4wJZcVxj57EcQFFkb4wAfzsUeZ+Sfg==",
    "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem",
    "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54:9bea22b9-d89f-452c-bf36-4d6d20e12df4"
}

チャージバック

チャージバックステータスが変更されるたびにIPNを受け取ります。 chargePermissionIdを参照して、セラーセントラルでチャージバックの詳細を確認してください。 IPNを受け取るタイミングの例:

  • 購入者がチャージバックを提出しました
  • チャージバックのケースは事業者申請で解決されました
  • チャージバックのケースは、購入者申請で解決されました

IPNメッセージの例

{
    "Type" : "Notification", 
    "MessageId" : "b8043d28-13c9-1bc2-1883-0cc63262b8ee", 
    "TopicArn" : "arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54",
    "Message" : "{\"MerchantID\":\"AEMGQX8TKDO54\",\"ObjectType\":\"CHARGEBACK\",\"ObjectId\":\"S01-0000000-0000000-C000000\",\"ChargePermissionId\":\"S01-0000000-0000000\",\"NotificationType\":\"STATE_CHANGE\",\"NotificationId\":\"9b4155a0-c396-46d0-83f7-db1cd2cb1568\",\"NotificationVersion\":\"V2\"}",
    "Timestamp" : "2020-03-10T22:21:31.169Z",
    "SignatureVersion" : "1", 
    "Signature" : "utm+azIy4dxAf2JmB/YtHNYmW+vL09+wXUq4oiLIIKfgQY1/wvNzT5Nq3ezF1+/EjVc+1RTe0axXgyhTn3vUO93q9nmZXm+LjojbGilcSg0Ey40P5XEaOTYhVWzq12ffR5cUqG2PN0uLFN2WQuNIFCko3uPf1N74mnQNj27FWVUt/NjNwZ6kigJBmzio/Vv25B6RGXp71fXPunT5CeoGkcQyhlUn3l0Y65jME0OjNaQhAG05t1F8D8h1vY9ouRjiTuUCdiprv6udnb1P3WyK4JtdAJ3OtORkKK73gklSKzC2rQL7y1VDOE2C4wJZcVxj57EcQFFkb4wAfzsUeZ+Sfg==",
    "SigningCertURL" : "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem",
    "UnsubscribeURL" : "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:291180941288:A3BXB0YN3XH17HAEMGQX8TKDO54:9bea22b9-d89f-452c-bf36-4d6d20e12df4"
}

IPN再試行ロジック

次の場合、IPN送信を再試行します。

  • エンドポイントは、HTTPステータスコード100〜101および500〜599で応答
  • リクエストがタイムアウト(15秒)。リクエストのタイムアウトが発生した場合、次の再試行はタイムアウト後の指定された間隔で発生することに注意してください。たとえば、再試行間隔が20秒で、リクエストがタイムアウトした場合、次のリクエストの開始は、タイムアウトしたリクエストの開始から35秒後になります。
  • タイムアウト、エンドポイントに到達できない、SSL証明書の不良などによる接続エラー。

Note:メッセージの最大有効期間は1時間です。


ベストプラクティス

SANDBOXでテストする

SANDBOXは本番環境に行く前に、インテグレーションをテストすることができます。常に最初にSANDBOX環境でIPN機能を設定してテストすることをお勧めします。本番運用開始前に、必ず本番エンドポイントを追加してください。

重複通知を処理する

通知が重複する場合があります。 IPNを処理するためのコードがべき等であることを確認してください。考えられる解決策は、すでに処理した通知をログに記録し、同じ通知IDを持つ重複する通知をスキップすることです。