Upgrading to Checkout v2

Amazon Pay Checkout v2 increases checkout conversion rate by offering a streamlined checkout experience with improved decline handling and recovery. Amazon Pay will continue to support Checkout v1 but will not be updating it with new features and enhancements.

What changes between Checkout v1 and Checkout v2
What stays the same between Checkout v1 and Checkout v2
Migration best practices
Managing Checkout v1 orders using Checkout v2 APIs
- One-time payment APIs
- Automatic payment APIs

What changes between Checkout v1 and Checkout v2

Buyer experience - Payment preference selection and decline handling are completed on Amazon Pay hosted pages. It may not be optimal to replace your existing Checkout v1 integration without making any UX modifications. See Amazon Pay Checkout v2 buyer experience for more info.
APIs - Checkout v2 simplifies integration by introducing a new set of APIs and API objects. Do not use Checkout v2 APIs on Checkout v1 orders without reviewing the Managing Checkout v1 objects using Checkout v2 APIs section first. Checkout v2 APIs have new throttling limits.
Instant payment notifications (IPNs) - Checkout v2 IPNs have a different message schema with less transaction details for improved security. You must make a GET API call for the transaction specified in the message to determine transaction state. See Set up Instant Payment Notifications for more info.
Reporting APIs - Checkout v2 offers new Reporting APIs to manage reports and report schedules. If you maintain an existing Reporting API integration with MWS for Amazon Pay, you should consider updating to Checkout v2 Reporting APIs. Follow our migration guide from MWS to Checkout v2 Reporting APIs or start from scratch. The report content stays the same.
Features
- Checkout v2 does not support charging more than the original amount.

What stays the same between Checkout v1 and Checkout v2

Amazon Pay merchant account - You do not have to register for a new Amazon Pay merchant account in order to upgrade to Checkout v2.
Disbursements - Settlement window and disbursement processes stay the same.
Seller Central - The Seller Central interface stays the same and you can continue to use it to perform the same actions you did for Checkout v1 orders.

Migration best practices

Follow these recommendations for a successful upgrade:

Plan your upgrade before starting integration. You can implement Amazon Pay Checkout v2 as a new payment method integration or you can update your current integration to use Checkout v2 APIs and write migration code to manage existing Checkout v1 orders.
1. Implementing Amazon Pay Checkout v2 as a new payment method - Use Checkout v1 APIs for v1 orders and Checkout v2 APIs for v2 orders. Choose this option if you can easily create a new payment method. It allows you to safely launch Checkout v2 without impacting your Checkout v1 integration and it simplifies troubleshooting by keeping the code for each integration separate.
2. Updating your current integration to use Checkout v2 APIs - Update your integration to use Checkout v2 APIs and write migration code as described in Managing Checkout v1 objects using Checkout v2 APIs. Choose this option if it will take a lot of effort to create a new payment method. It allows you to maintain a single Amazon Pay integration but you will have to write additional code to complete in-flight transactions or issue refunds for Checkout v1 orders. If you plan on taking this approach, we recommend setting up a roll-back plan in case there’s an issue with your Checkout v2 integration and you need to temporarily switch back to Checkout v1.
Review the Checkout v2 buyer experience before starting integration. Replacing your existing Checkout v1 integration without any modifications may not be optimal. For example, if you have a multi-page checkout flow where buyers enter shipping address and billing information on different pages, you should skip directly to the final review page after the buyer selects their preferred shipping address and payment instrument on the Amazon Pay hosted page.
Perform A/B testing. Poor relative performance of Checkout v2 could be an indicator of integration errors.

Managing Checkout v1 orders using Checkout v2 APIs

If you plan on managing Checkout v1 orders using Checkout v2 APIs, do not create new Checkout v1 orders after upgrading to V2 checkout. Do not use Checkout v1 and Checkout v2 APIs at the same time and only implement what’s required for completing in-flight transactions or issuing refunds.

One-time payment APIs

Checkout v1 API	Checkout v2 migration steps
Authorize	Create Charge using a Checkout v1 `AmazonOrderReferenceId`. Order Reference object must be in the Open state. Set `captureNow` to true to capture payment using the same transaction. Use the `CanHandlePendingAuthorization` parameter to specify whether authorization should be synchronous or asynchronous.
CancelOrderReference	Close Charge Permission using Checkout v1 `AmazonOrderReferenceId`. Set `cancelPendingCharges` to True.
Capture	Follow these steps: 1. Modify the Checkout v1 `AmazonAuthorizationId` and change the 21st character from the letter "A" to the letter "C". Example: S01-5797829-1888777-A043451 to S01-5797829-1888777-C043451. 2. Capture Charge using the modified value.
CloseAuthorization	Follow these steps: 1. Modify the Checkout v1 `AmazonAuthorizationId` and change the 21st character from the letter "A" to the letter "C". Example: S01-5797829-1888777-A043451 to S01-5797829-1888777-C043451. 2. Cancel Charge using the modified value.
CloseOrderReference	Close Charge Permission using Checkout v1 AmazonOrderReferenceId. Set `cancelPendingCharges` to False.
GetAuthorizationDetails	Follow these steps: 1. Modify the Checkout v1 `AmazonAuthorizationId` and change the 21st character from the letter "A" to the letter "C". Example: S01-5797829-1888777-A043451 to S01-5797829-1888777-C043451. 2. Get Charge using the modified value. Checkout v1 Authorization state and corresponding Checkout v2 Charge state: Pending = AuthorizationInitiated Open = Authorized Closed = Captured if `ReasonCode` is MaxAmountCaptured, Canceled for all other `ReasonCode` Declined = Declined
GetCaptureDetails	Get Charge using Checkout v1 `AmazonCaptureId`. Checkout v1 Capture state and corresponding Checkout v2 Charge state: Pending state = CaptureInitiated Completed state = Captured Closed state = Canceled Declined state = Declined
GetOrderReferenceDetails	Get Charge Permission using Checkout v1 `AmazonOrderReferenceId`. Checkout v1 Object Reference state and corresponding Checkout v2 Charge Permission state: Open = Chargeable before successful Capture or Closed after successful Capture Closed = Closed Canceled = Closed Suspended = NonChargeable
GetRefundDetails	Get Refund using Checkout v1 `AmazonRefundId`. Checkout v1 Refund state and corresponding Checkout v2 Refund state: Pending = RefundInitiated Completed = Refunded Declined = Declined
Refund	Create Refund using Checkout v1 `AmazonCaptureId`. Capture object must be in the Completed state.

Automatic payment APIs

Checkout v1 API	Checkout v2 migration steps
AuthorizeOnBillingAgreement	Create Charge using a Checkout v1 `AmazonBillingAgreementId`. The Billing Agreement object must be in the Open state. Set `captureNow` to true to capture payment using the same transaction. Use the `CanHandlePendingAuthorization` parameter to specify whether authorization should be synchronous or asynchronous.
CloseBillingAgreement	Close Charge Permission using Checkout v1 `AmazonBillingAgreementId`. Set `cancelPendingCharges` to False.
CreateOrderReferenceForId	Checkout v2 does not offer an equivalent API. If you are using this API to create an Order Reference object for future payment authorization, you will need to refactor your code to only call Create Charge using the Checkout v1 `AmazonBillingAgreementId` once you're ready to authorize and/or capture payment. If you are using this API to authorize and/or capture payment immediately, you should call Create Charge using the Checkout v1 `AmazonBillingAgreementId`.
GetBillingAgreementDetails	Get Charge Permission using Checkout v1 `AmazonBillingAgreementId`. Checkout v1 Billing Agreement state and corresponding Checkout v2 Charge Permission state: Open = Chargeable Closed = Closed Canceled = Closed Suspended = NonChargeable
SetBillingAgreementDetails	Update Charge Permission using Checkout v1 `AmazonBillingAgreementId`.
ValidateBillingAgreement	Checkout v2 does not offer an equivalent API. Amazon Pay automatically validates the payment method associated to a Charge Permission object when it is created. You should remove this API request from your code.