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
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.
- Features
- With Checkout v2, you can only create one successful authorization per order. This means that multi-capture payment flows are not supported.
- 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.
- Reporting - Checkout v1 and Checkout v2 orders show up on the same reports. There are no Checkout v2 reporting APIs so you do not have to update your existing reporting integration.
- 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.
- 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.
- 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.
| 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.Note: you can only charge more than the original amount using Checkout v1 Order Reference objects. This feature is not supported in Checkout v2. |
| 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 = Canceled 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 Permision 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.
|