---
title: Version 2 migration guide
url: amazon-pay-checkout/version-two-migration-guide.html
---


API version 2 introduces breaking changes. Update the API endpoint version parameter and follow this guide to migrate from version 1 to version 2.

* TOC
{:toc}
{::options toc_levels="3" /}

### API contract updates

Some parameters have been renamed or restructured. Check the changes below and update your code if it specifically references one of the affected parameters.

#### Checkout Session

<table width="100%" border="1">
    <tbody>
        <tr id=''>
            <td id='' style='vertical-align: top; font-weight: bold; width: 25%;' class='bold'>Parameter
                <br /></td>
            <td id='' style='vertical-align: top; font-weight: bold; width: 75%;' class='bold'>Change Description
                <br /></td>
        </tr>
        <tr id=''>
            <td id='' style='vertical-align: top;'>billingAddress
                <br /></td>
            <td id='' style='vertical-align: top;'>billingAddress moved from paymentPreferences array to top level node
                <br /></td>
        </tr>
        <tr id=''>
            <td id='' style='vertical-align: top;'>webCheckoutDetail
                <br /></td>
            <td id='' style='vertical-align: top;'>webCheckoutDetail renamed to webCheckoutDetails
                <br /></td>
        </tr>
        <tr id=''>
            <td id='' style='vertical-align: top;'>paymentDetail
                <br /></td>
            <td id='' style='vertical-align: top;'>paymentDetail renamed to paymentDetails
                <br /></td>
        </tr>
        <tr id=''>
            <td id='' style='vertical-align: top;'>statusDetail
                <br /></td>
            <td id='' style='vertical-align: top;'>statusDetail renamed to statusDetails
                <br /></td>
        </tr>
    </tbody>
</table>

#### Charge Permission

<table width="100%" border="1">
    <tbody>
        <tr id=''>
            <td id='' style='vertical-align: top; font-weight: bold; width: 25%;' class='bold'>Parameter
                <br /></td>
            <td id='' style='vertical-align: top; font-weight: bold; width: 75%;' class='bold'>Change Description
                <br /></td>
        </tr>
        <tr id=''>
            <td id='' style='vertical-align: top;'>billingAddress
                <br /></td>
            <td id='' style='vertical-align: top;'>billingAddress moved from paymentPreferences array to top level node
                <br /></td>
        </tr>
        <tr id=''>
            <td id='' style='vertical-align: top;'>chargeAmountLimit
                <br /></td>
            <td id='' style='vertical-align: top;'>Replaced with limits which encapsulates amountLimit and accountBalance
                <br /></td>
        </tr>
        <tr id=''>
            <td id='' style='vertical-align: top;'>statusDetail
                <br /></td>
            <td id='' style='vertical-align: top;'>statusDetail renamed to statusDetails
                <br /></td>
        </tr>
    </tbody>
</table>

#### Charge

<table width="100%" border="1">
    <tbody>
        <tr id=''>
            <td id='' style='vertical-align: top; font-weight: bold; width: 25%;' class='bold'>Parameter
                <br /></td>
            <td id='' style='vertical-align: top; font-weight: bold; width: 75%;' class='bold'>Change Description
                <br /></td>
        </tr>
        <tr id='CVa9CAx084w'>
            <td id='' style='vertical-align: top;'>statusDetail
                <br /></td>
            <td id='' style='vertical-align: top;'>statusDetail renamed to statusDetails
                <br /></td>
        </tr>
    </tbody>
</table>

#### Refund

<table width="100%" border="1">
    <tbody>
        <tr id=''>
            <td id='' style='vertical-align: top; font-weight: bold; width: 25%;' class='bold'>Parameter
                <br /></td>
            <td id='' style='vertical-align: top; font-weight: bold; width: 75%;' class='bold'>Change Description
                <br /></td>
        </tr>
        <tr id='CVa9CAx084w'>
            <td id='' style='vertical-align: top;'>statusDetail
                <br /></td>
            <td id='' style='vertical-align: top;'>statusDetail renamed to statusDetails
                <br /></td>
        </tr>
    </tbody>
</table>

### Complete Checkout Session API

Version 2 Checkout Session objects must be confirmed once the buyer is redirected to `amazonResultReturnUrl` to finalize `paymentIntent`. Any Checkout Session that is not confirmed within 24 hours will be cancelled. 

Replace the <a href="../amazon-pay-api-v2/checkout-session.md#get-checkout-session" target="_blank" rel="noopener noreferrer">Get Checkout Session</a> request used to verify the Checkout Session state once the buyer is redirected to `amazonResultReturnUrl` with a <a href="../amazon-pay-api-v2/checkout-session.md#complete-checkout-session" target="_blank" rel="noopener noreferrer">Complete Checkout Session</a> request. Complete Checkout session will return a success response if transaction processing was successful. Otherwise, it will return an error response.

You do not have to update any other logic you might have implemented for authorizing and capturing payment.