Learn how to update a payment created using the Square Payments API.
Payments API

Update Payments

Learn how to use the UpdatePayment endpoint to update a payment created using the Payments API.

Important

The UpdatePayment endpoint is not supported for payments to sellers in Australia and Japan. The payment.location_id indicates the location where the payment is taken.

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 are applied in a last-write-wins manner, meaning newer updates overwrite older updates. You can optionally include a payment version for optimistic concurrency (see Using optimistic concurrency).

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
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    curl https://connect.squareupsandbox.com/v2/payments \
      -X POST \
      -H 'Square-Version: 2022-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "autocomplete": false,
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "source_id": "cnon:card-nonce-ok"
      }'

    The following is an example response. Note these fields:

    • The amount_money field shows that $10 is charged. Because there is no tip, total_money is the same as amount_money. The approved_money 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.

    • For more information about version_token, see Using optimistic concurrency.

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40
    {
      "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"
        ],
        "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.

    Update Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    curl https://connect.squareupsandbox.com/v2/payments/{payment_id} \
      -X PUT \
      -H 'Square-Version: 2022-11-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "payment": {
          "amount_money": {
            "amount": 1500,
            "currency": "USD"
          },
          "tip_money": {
            "amount": 300,
            "currency": "USD"
          }
        }
      }'

    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.

    • That approved_money remained the same ($10), indicating that Square did not obtain reauthorization.

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40
    • 41
    {
      "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"
        ],
        "receipt_number": "Xlle",
        "delay_action": "CANCEL",
        "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:

The following considerations apply when calling UpdatePayment:

  • Fields you can update. You can update only the amount_money and tip_money Payment fields.

  • UpdatePayment requests are not 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 is not 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.

  • Include tips in the original CreatePayment request, if possible. Because UpdatePayment is not guaranteed to succeed, we recommend that your applications use a workflow that collects the tip amount and includes it in the original CreatePayment request.

  • 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.

  • Update timeline. After a payment is authorized, you can update the payment for a period of time. For the default thresholds that apply when capturing or canceling an authorized payment, see Time threshold.

  • Concurrency support. By default, payment updates are applied in the last-write-wins manner, meaning newer updates overwrite older updates. The endpoint provides optional support for optimistic concurrency.

  • In addition, note the following Payment field considerations:

    • The approved_money field. When you initially obtain payment authorization, the approved_money 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.

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

The following is an example of an UpdatePayment request that uses optimistic concurrency to ensure that the update is not overwritten by a newer update. The request updates the payment by adding the specified tip_money. The version_token in the request must be obtained from the Payment object that the request intends to update. In this example, the version_token is obtained from the CreatePayment response that returned the Payment to be updated.

Update Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/payments/{payment_id} \
  -X PUT \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "payment": {
      "tip_money": {
        "amount": 15,
        "currency": "USD"
      },
      "version_token": "9TKsTawsWZvdZZD5uhAZFWfd3chxFXB49cgFpD2Kujf6o"
    }
  }'

For more information about optimistic concurrency in the Payments API, see Optimistic concurrency.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.