Update Payment and Tip Amounts

Applies to: Payments API

Learn how to add tips or update payment amounts to an authorized payment.

You can call UpdatePayment to change the payment amount and tip amount after a payment is created. By default, any updates you apply to a Payment object are applied in a last-write-wins manner, meaning newer updates overwrite older updates. You have the option to include a payment version in the update request to avoid this.

• Only authorized payments can be updated. Payments with the status of APPROVED can be updated. Completed payments (status is COMPLETED) cannot be updated. For more information, see Delayed Capture of a Card Payment.
• You can update only the delay_action, amount_money, and tip_money Payment fields.
• You cannot update a payment after the capture/cancel time threshold for the payment expires.
• The UpdatePayment endpoint isn't supported for payments to sellers in Japan. The payment.location_id indicates the location where the payment is taken.

When a delayed-capture payment is created, it includes the capabilities field indicating what updates are allowed on the payment. Not every payment can be updated. For example, some regions might not support updating card payments. Applications should read this field before attempting any payment update.

The following example shows the capabilities field from a Payment object returned in a Payments API response. In this example, the payment amount and tip amount can be adjusted up or down. The action taken by Square when the delay duration expires can also be edited.

 "capabilities": [
          "EDIT_AMOUNT_UP",
          "EDIT_AMOUNT_DOWN",
          "EDIT_TIP_AMOUNT_UP",
          "EDIT_TIP_AMOUNT_DOWN",
          "EDIT_DELAY_ACTION"
 ]

The capabilities field isn't present in COMPLETED payments.

In the following example, you create a payment using CreatePayment and then change the amount and tip using UpdatePayment:

1. Call CreatePayment to take a $10 payment.

   Create payment

   cURL

   The following is an example response. Note these fields:

   • The amount_money field shows that $10 is charged. Because there's no tip, total_money is the same as amount_money. The approved_money field shows that the bank authorized the $10 payment.
   • The payment status is APPROVED.
   • The capabilities field shows the updates that are allowed on this payment.

   Note

   The following update examples show the use of the version_token field to ensure optimistic concurrency in the update operations. This is an optional update request field. For more information about version_token, see Payment versioning.

   {
     "payment": {
       "id": "XllelosAAfmkf9mOa0YB4PqSZACZY",
       "created_at": "2021-03-02T19:53:31.055Z",
       "updated_at": "2021-03-02T19:53:31.164Z",
       "amount_money": {
         "amount": 1000,
         "currency": "USD"
       },
       "status": "APPROVED",
       "delay_duration": "PT168H",
       "source_type": "CARD",
       "card_details": {
         "status": "AUTHORIZED",
         "card": {
         ...
         },
        ...
       },
        ...
       "total_money": {
         "amount": 1000,
         "currency": "USD"
       },
       "approved_money": {
         "amount": 1000,
         "currency": "USD"
       },
       "capabilities": [
         "EDIT_AMOUNT_UP",
         "EDIT_AMOUNT_DOWN",
         "EDIT_TIP_AMOUNT_UP",
         "EDIT_TIP_AMOUNT_DOWN",
         "EDIT_DELAY_ACTION"
       ],
       "receipt_number": "Xlle",
       "delay_action": "CANCEL",
       "delayed_until": "2021-03-09T19:53:31.055Z",
       "version_token": "9TKsTawsWZvdZZD5uhAZFWfd3chxFXB49cgFpD2Kujf6o"
     }
   }

2. Call UpdatePayment to update amount_money and tip_money:

   • Increase amount_money from $10 to $15.
   • Add tip_money of $3 to the payment.
   • Override the default delay action to complete the payment instead of canceling it.

   Update payment

   cURL

   The following is an example response. It shows:

   • The updated amount_money and tip_money added to the payment. The total_money field shows the changes accordingly.
   • The approved_money field remained $10, indicating that Square didn't obtain reauthorization.
   • The delay_action field is now COMPLETE, which means that if the seller forgets to close out the bill, the payment is completed on expiration of delay period.

   {
     "payment": {
       "id": "XllelosAAfmkf9mOa0YB4PqSZACZY",
       "created_at": "2021-03-02T19:53:31.055Z",
       "updated_at": "2021-03-02T19:53:31.164Z",
       "amount_money": {
         "amount": 1500,
         "currency": "USD"
       },
       "tip_money": {
         "amount": 300,
         "currency": "USD"
       },
       "status": "APPROVED",
       "delay_duration": "PT168H",
       "source_type": "CARD",
       "card_details": {
   ...
       },
       "location_id": "S8GWD5R9QB376",
   ...
       "total_money": {
         "amount": 1800,
         "currency": "USD"
       },
       "approved_money": {
         "amount": 1000,
         "currency": "USD"
       },
       "capabilities": [
         "EDIT_AMOUNT_UP",
         "EDIT_AMOUNT_DOWN",
         "EDIT_TIP_AMOUNT_UP",
         "EDIT_TIP_AMOUNT_DOWN",
         "EDIT_DELAY_ACTION"
       ],
       "receipt_number": "Xlle",
       "delay_action": "COMPLETE",
       "delayed_until": "2021-03-09T19:53:31.055Z",
       "version_token": "a8afrYYBtF1hIawsw3ET5wIlgzhSywsdhRvUHev2pxT6o"
     }
   }

   If you want to update only tip_money or amount_money, you specify only the necessary fields in the request body. The following request body shows the tip_money update:

   {
     "idempotency_key": "{UNIQUE_KEY}",
     "payment": {
       "tip_money": {
           "amount": 1000,
           "currency": "USD"
       },
       "version_token": "a8afrYYBtF1hIawsw3ET5wIlgzhSywsdhRvUHev2pxT6o"
     }
   }

Square recommends the following best practices for payments that you might update:

• Include tips in the original CreatePayment request, if possible - Because UpdatePayment isn't guaranteed to succeed, your applications should use a workflow that collects the tip amount and includes it in the original CreatePayment request.
• Use payment versioning - By default, payment updates are applied in the last-write-wins manner, meaning newer updates overwrite older updates. You can avoid this problem by using the optional Payment.version_token field that supports optimistic concurrency.

The following considerations apply when calling UpdatePayment:

• UpdatePayment requests aren't guaranteed to succeed - For example:
  • Square might limit the maximum amount a payment can be increased. If an UpdatePayment request exceeds this limit, an AMOUNT_TOO_HIGH error is returned.
  • If Square chooses to obtain reauthorization, an UpdatePayment request that increases the payment amount might fail. If an UpdatePayment request fails, the unmodified payment can still be completed. If UpdatePayment isn't successful, you might consider alternatives to increase the payment. For example:
    • Complete the unmodified payment amount and ask the customer to pay the additional amount with the same card or new payment method.
    • Create a new payment with the same card or a new payment method. After the payment is authorized, cancel the original payment.
• The approved_money field - When you initially obtain payment authorization, the approved_money field in the resulting Payment tracks the amount approved. When applications call UpdatePayment, Square might choose to obtain reauthorization. If Square obtains reauthorization, it updates the approved_money to reflect the new amount authorized.