Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Payments API

Update Payments

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

Overview Permalink Get a link to this section

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: 2021-05-13' \
      -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.

    {
      "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.

    curl -X PUT \
      https://connect.squareupsandbox.com/v2/payments/{payment_id} \
      -H 'Accept: application/json' \
      -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.

    {
      "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:

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

General considerations Permalink Get a link to this section

The following considerations apply when calling UpdatePayment:

  • Payments you can update:

    • You can update only the authorized payment (status is APPROVED). Completed payments (status is COMPLETED) cannot be updated.

    • Gift card payments cannot be updated. Only the card, cash, and external payment types can be updated.

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

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

  • Concurrency support. By default, payment updates are applied in the last-write-wins manner, meaning newer updates overwrite older updates. The endpoint provides an 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. Applications can read this field before attempting any payment update.

Using optimistic concurrency Permalink Get a link to this section

By default, any updates you apply to a Payment are applied in a last-write-wins manner, meaning newer updates overwrite older updates. For many applications, this behavior is sufficient. However, in a complex scenario (for example, you have multiple applications editing the same payment), Square supports optimistic concurrency for the UpdatePayment endpoint.

Each Payment includes a version_token field that uniquely identifies a specific version of the payment. You can optionally include this version_token in an UpdatePayment (or CompletePayment) request. In this case, the update (or completion) request succeeds only if the payment has not been updated since that version_token was generated.

The following is an example of an UpdatePayment request. The request updates the payment by adding the specified tip_money. The request also specifies the version_token of the payment being updated for optimistic concurrency.

curl -X PUT \
  https://connect.squareupsandbox.com/v2/payments/{payment_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
  "idempotency_key": "{UNIQUE_KEY}",
  "payment": {
    "tip_money": {
        "amount": 15,
        "currency": "USD"
    }
    "version_token": "7cwN3m5UKHbhPKC6r1Q2j37PoreT0CyFqSw9qQkGq4E6o"
  }
}'