CV2へのアップグレード

Amazon Pay Checkout v2(CV2)は、オーソリエラーのハンドリングとお支払い方法の更新を改善し合理化された決済エクスペリエンスを提供することにより、決済コンバージョン率を向上させます。


Checkout v1(CV1)とCheckout v2(CV2)で何が変わるか

  • 購入者のエクスペリエンス - 支払い設定の選択とdeclineの処理は、Amazon Payがホストするページで完了します。 UXを変更せずに、既存のCV1インテグレーションを置き換えることは最適ではない場合があります。詳細については、 Amazon Pay Checkout v2 購入者エクスペリエンスをご覧ください。
  • API - CV2では、新しいAPIとAPIオブジェクトを導入し、インテグレーションを簡素化します。最初にCV2 APIを使用したCV1オブジェクトの管理セクションを確認せずに、CV1の注文でCV2 APIをご利用しないでください。
  • インスタント支払い通知(IPN)- CV2 IPNには、セキュリティを向上させるためにトランザクションの詳細が少ない、異なるメッセージスキーマがあります。トランザクションのstateを判別するには、メッセージで指定されたトランザクションに対してGET APIを実行する必要があります。詳細については、インスタント支払通知を設定するを参照してください。

Checkout v1(CV1)とCheckout v2(CV2)で変わらないもの

  • Amazon Pay事業者アカウント - CV2にアップグレードするために、新しいAmazon Pay事業者アカウントに登録する必要はありません。
  • 支払い - 決済期間と支払いプロセスは同じままです。
  • レポート - CV1とCV2の注文は同じレポートに表示されます。 CV2はレポートAPIはないため、既存のレポートインテグレーションを更新する必要はありません。
  • セラーセントラル - セラーセントラルのインターフェースは同じままであり、引き続きそれを使用して、CV1の注文に対して行なっていたのと同じアクションを実行できます。

移行のベストプラクティス

アップグレードを成功させるには、次の推奨事項に従ってください。

  1. インテグレーションを開始する前に、アップグレードを計画してください。 Amazon Pay CV2を新しい支払い方法のインテグレーションとして実装するか、既存のCV1注文を管理するために現在のインテグレーションを更新してCV2 APIを使用した移行コードを記述することができます。
    1. 新しい支払い方法としてのAmazon Pay CV2の実装 - CV1の注文にはCV1 APIを使用し、CV2の注文にはCV2 APIを使用します。新しい支払い方法を簡単に作成できる場合は、このオプションを選択してください。 CV1インテグレーションに影響を与えることなくCV2を安全に起動でき、各インテグレーションのコードを個別に保持することでトラブルシューティングを簡素化します。
    2. CV2 APIを使用するように現在のインテグレーションを更新する - CV2 APIを使用するようにインテグレーションを更新し、CV2 APIを使用したCV1オブジェクトの管理の説明に従って移行コードを記述します。新しい支払い方法を作成するのに多大な労力がかかる場合は、このオプションを選択してください。これにより、単一のAmazon Payインテグレーションを維持できますが、CV1の注文に対して売上請求までの処理または返金を行うには追加のコードを作成する必要があります。このアプローチを採用する予定の場合は、CV2のインテグレーションに問題があり、一時的にCV1に戻す必要がある場合に備えて、ロールバックプランを設定することをお勧めします。
  2. インテグレーションを開始する前に、CV2の購入者エクスペリエンスを確認してください。既存のCV1インテグレーションを変更せずに置き換えることは、最適ではない場合があります。たとえば、CV1では異なるページに配送先住所とお支払い方法の情報を入力する複数ページの決済フローがある場合、CV2では購入者がAmazon Payでホストされているページで希望の配送先住所とお支払い方法を選択した後、最終レビューページに直接スキップする必要があります。
  3. A / Bテストを実行します。 CV2の相対的なパフォーマンスが低いことは、インテグレーションエラーの指標である可能性があります。

Checkout v2(CV2) APIを使用したCheckout v1(CV1)注文の管理

CV2にアップグレードした後、新たなCV1の注文を作成しないでください。CV1で作成された古い注文に対してCV2 APIで処理する場合は、下記の表を参考に該当する処理を実行してください。

ワンタイムペイメントAPI

CV1 API
CV2移行手順
Authorize
CV1のAmazonOrderReferenceIdを使用したCreate Charge。 Order Reference objectはOpen状態である必要があります。

同じトランザクションを使用して支払いを売上請求するするには、captureNowをtrueに設定します。オーソリを同期にするか非同期にするかを指定するにはCanHandlePendingAuthorizationパラメータを使用してください。
Cancel OrderReference
 CV1のAmazonOrderReferenceIdを使用したClose Charge PermissioncancelPendingChargesをTrueに設定します。
Capture
次の手順を実行します:
1. CV1のAmazonAuthorizationIdの21番目の文字を文字「A」から文字「C」に変更します。例:S01-5797829-1888777-A043451からS01-5797829-1888777-C043451。
2. 変更された値を使用してCapture Chargeを実行します。
Close Authorization
次の手順を実行します:
1. CV1のAmazonAuthorizationIdの21番目の文字を文字「A」から文字「C」に変更します。例:S01-5797829-1888777-A043451からS01-5797829-1888777-C043451。
2. 変更された値を使用してCancel Chargeを実行します。
Close OrderReference
CV1のAmazonOrderReferenceIdを使用したClose Charge PermissioncancelPendingChargesをFalseに設定します。
Get AuthorizationDetails
次の手順を実行します:
1. CV1のAmazonAuthorizationIdの21番目の文字を文字「A」から文字「C」に変更します。例:S01-5797829-1888777-A043451からS01-5797829-1888777-C043451。
2. 変更された値を使用してGet Charge を実行します。

CV1 Authorizationの状態とCV2 Chargeの状態の対応は次の通りです:
Pending = AuthorizationInitiated
Open = Authorized
Closed = ReasonCodeがMaxAmountCapturedの場合はCaptured, その他の全てのReasonCodeの場合は、Canceled
Declined = Declined
Get CaptureDetails
CV1のAmazonCaptureIdを使用したGet Charge

CV1 Captureの状態とCV2 Chargeの状態の対応は次の通りです:
Pending = CaptureInitiated
Completed = Captured
Closed = Canceled
Declined = Declined
Get OrderReferenceDetails
 CV1のAmazonOrderReferenceIdを使用したGet Charge Permission

CV1 ObjectReference状態とCV2 ChargePermisionの状態の対応は次の通りです:
Open = Captureの成功前は、Chargeable。Captureの成功後は、Closed
Closed = Closed
Canceled = Closed
Suspended = NonChargeable
Get RefundDetails
CV1のAmazonRefundIdを使用したGet Refund

CV1 Refundの状態とCV2 Refundの状態の対応は次の通りです:
Pending = RefundInitiated
Completed = Refunded
Declined = Declined
Refund
CV1のAmazonCaptureIdを使用したCreate Refund。 CaptureオブジェクトはCompleted状態である必要があります。

Auto Pay API

CV1 API
CV2 移行手順
AuthorizeOnBillingAgreement
 CV1のAmazonBillingAgreementIdを使用したCreate Charge。Billing AgreementオブジェクトはOpen状態である必要があります。 

同じトランザクションを使用して支払いを売上請求するするには、captureNowをtrueに設定します。オーソリを同期にするか非同期にするかを指定するにはCanHandlePendingAuthorizationパラメータを使用してください。
CloseBillingAgreement
CV1のAmazonBillingAgreementIdを使用したClose Charge PermissioncancelPendingChargesをFalseに設定してください.
CreateOrderReferenceForId
CV2では同等のAPIを提供していません。

このAPIを将来のオーソリ取得するためにOrder Reference objectの生成で利用している場合は、CV1のAmazonBillingAgreementIdを使用したCreate Chargeを実行するようにコードをリファクタリングしてください。

このAPIを即時のオーソリや売上請求のために使用している場合は、AmazonBillingAgreementIdを使用したCreate Chargeを実行してください。
GetBillingAgreementDetails
CV1の AmazonBillingAgreementIdを使用したGet Charge Permission

CV1 Billing Agreementの状態とCV2 Charge Permisionの状態の対応は次の通りです:
Open = Chargeable
Closed = Closed
Canceled = Closed
Suspended = NonChargeable
SetBillingAgreementDetails
CV1のAmazonBillingAgreementIdを使用したUpdate Charge Permission。 
ValidateBillingAgreement
CV2では同等のAPIを提供していません。 Amazon PayはCharge Permissionオブジェクトが作成されるときに、それに関連付けられている支払い方法を自動的に検証します。このAPIリクエストはコードから削除する必要があります。.