Updating a payment intent

Note

Before updating the payment intent, check that the payment intent has not expired. The payment intent is valid for 24 hours from the creationDate. To check if the payment intent is still valid, compare the creationDate returned in the PaymentIntentResponse with the current time. If your customer's shopping cart is more than 24 hours old, updating the original payment intent results in a 404 error.

There are various customer actions where you must update the payment intent. You must update the payment intent with the new amount to be charged if your customer completes any of the following actions:

  • Adds a tip

  • Applies a discount

  • Adds more items to their order

You can choose to update the payment intent if your customer wants to sign into their profile during the checkout process. If your customer has not signed into their profile during the checkout process, they can choose to sign in when they update the payment intent. Include the customerId in the POST request body to /v1/payment-intents/{paymentIntentId} endpoint to update the payment intent. Then invoke the fetchUpdates function to fetch the updates applied to the payment intent, including the updated amount and the customerId. The client-side of your integration calls the fetchUpdates function in the Toast object, which re-renders the hosted checkout integration iframe to show the customer’s saved cards and the Remember this card checkbox.

To update the payment amount, send a POST request to the /v1/payment-intents/{paymentIntentId} endpoint of the payment intents API with the updated amount to be charged upon checkout. If you update the amount, you must include the tip amount in the AmountDetails object. You must update the payment intent with the final amount and tip before the customer enters payment details in the iframe. You update the payment intent from the server component of your integration (not from the client browser).

Note

If you only want to update the customer's email address, you do not have to update the amount or amountDetails.

Example request body

{
    "amount" : 2000, 1
    "email": "john.smith@email.com", 2
    "amountDetails": { 
        "tip": 100 3
    }
}

1

The updated payment amount to be charged in minor units represented as a positive integer. In this example, 2000 represents twenty USD and zero cents.

2

This value only appears if you include a customer's email address when you create or update a payment intent.

3

The tip amount to be charged. Tip can only be added when you update the payment intent. In this example, 100 represents one USD and zero cents.


Example response body

{
    "id": "86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c",
    "externalReferenceId": "73edc827-0c18-485f-b581-1ef79f93b940",
    "sessionSecret": "PI_86bbcf0c-b483-4bbc-81bf-c2a9cd2baa2c_SECRET_EqYQ5^CgQWc4J?KBwq2jfv&Ov",
    "amount": 2000,
    "currency": "USD",
    "captureMethod": "MANUAL",
    "status": "REQUIRES_PAYMENT_METHOD", 1
    "paymentMethodId": "f718c101-70e4-45fe-8fc1-67ba0a12a8c5",
    "creationDate": "2023-09-29T16:42:36.239579Z",
    "usage": null,
    "customerId": "4b2dfc5a-88a3-11ee-b9d1-0242ac120002", 
    "amountDetails": {
        "tip": 100
    }, 
    "email": "john.smith@email.com", 
    "paymentMethodConfigurationDetails": { 
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"  
    },
    "latestPayment": null,
    "offSession": false,   
    "standingInstructionType": null, 
    "mandateId": null
}

1

The status of the payment intent. A payment intent with a status of PROCESSING or REQUIRES_CAPTURE cannot be updated. Any request to update the payment intent with either of those statuses returns an error.

For more information, see Payment intent statuses.