Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

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

  • 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

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:

  1. 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.
  2. 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.
  3. 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.