• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Update payment

PUT /v2/payments/{payment_id}

Updates a payment with the APPROVED status.

You can update the amount_money and tip_money using this endpoint.

Permissions
PAYMENTS_WRITE
Guide
Update Payment Try in API Explorer

Path Parameters

Example code
Name Description
payment_id
string
Required

The ID of the payment to update.

Request Body
Name Description
payment
Payment

The updated Payment object.
idempotency_key
string
Required

A unique string that identifies this UpdatePayment request. Keys can be any valid string but must be unique for every UpdatePayment request.

For more information, see Idempotency.

Min Length 1 Max Length 45

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
payment
Payment

The updated payment.

Examples

You are viewing an old version of the API
PUT /v2/payments/{payment_id}
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/payments/1QjqpBVyrI9S4H9sTGDWU9JeiWdZY \
  -X PUT \
  -H 'Square-Version: 2022-07-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "956f8b13-e4ec-45d6-85e8-d1d95ef0c5de",
    "payment": {
      "amount_money": {
        "amount": 1000,
        "currency": "USD"
      },
      "tip_money": {
        "amount": 100,
        "currency": "USD"
      },
      "version_token": "ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o"
    }
  }'
Response JSON 
{
  "payment": {
    "id": "1QjqpBVyrI9S4H9sTGDWU9JeiWdZY",
    "created_at": "2021-10-13T20:26:44.191Z",
    "updated_at": "2021-10-13T20:26:44.364Z",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "tip_money": {
      "amount": 100,
      "currency": "USD"
    },
    "status": "APPROVED",
    "delay_duration": "PT168H",
    "source_type": "CARD",
    "card_details": {
      "status": "AUTHORIZED",
      "card": {
        "card_brand": "VISA",
        "last_4": "1111",
        "exp_month": 11,
        "exp_year": 2022,
        "fingerprint": "sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ",
        "card_type": "DEBIT",
        "prepaid_type": "NOT_PREPAID",
        "bin": "411111"
      },
      "entry_method": "ON_FILE",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED",
      "auth_result_code": "68aLBM",
      "statement_description": "SQ *EXAMPLE TEST GOSQ.C",
      "card_payment_timeline": {
        "authorized_at": "2021-10-13T20:26:44.364Z"
      }
    },
    "location_id": "L88917AVBK2S5",
    "order_id": "nUSN9TdxpiK3SrQg3wzmf6r8LP9YY",
    "risk_evaluation": {
      "created_at": "2021-10-13T20:26:45.271Z",
      "risk_level": "NORMAL"
    },
    "note": "Example Note",
    "customer_id": "W92WH6P11H4Z77CTET0RNTGFW8",
    "total_money": {
      "amount": 1100,
      "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": "1Qjq",
    "delay_action": "CANCEL",
    "delayed_until": "2021-10-20T20:26:44.191Z",
    "application_details": {
      "square_product": "ECOMMERCE_API",
      "application_id": "sq0ids-TcgftTEtKxJTRF1lCFJ9TA"
    },
    "version_token": "rDrXnqiS7fJgexccgdpzmwqTiXui1aIKCp9EchZ7trE6o"
  }
}

Error Descriptions
400 Bad request AMOUNT_TOO_HIGH

The requested payment amount is too high for the provided payment source.

 >
400 Bad request CARDHOLDER_INSUFFICIENT_PERMISSIONS

The card issuer has declined the transaction due to restrictions on where the card can be used. For example, a gift card is limited to a single merchant.

 >
400 Bad request CVV_FAILURE

The card issuer declined the request because the CVV value is invalid.

 >
400 Bad request GENERIC_DECLINE

Square received a decline without any additional information. If the payment information seems correct, the buyer can contact their issuer to ask for more information.

 >
400 Bad request INSUFFICIENT_FUNDS

The funding source has insufficient funds to cover the payment.

 >
400 Bad request INVALID_FEES

The app_fee_money on a payment is too high.

 >
400 Bad request PAN_FAILURE

The specified card number is invalid. For example, it is of incorrect length or is incorrectly formatted.

 >
400 Bad request PAYMENT_LIMIT_EXCEEDED

Square declined the request because the payment amount exceeded the processing limit for this merchant.

 >
400 Bad request TRANSACTION_LIMIT

The card issuer has determined the payment amount is either too high or too low. The API returns the error code mostly for credit cards (for example, the card reached the credit limit). However, sometimes the issuer bank can indicate the error for debit or prepaid cards (for example, card has insufficient funds).

 >
400 Bad request VOICE_FAILURE

The card issuer declined the request because the issuer requires voice authorization from the cardholder.

 >
402 Payment required CHIP_INSERTION_REQUIRED

The card issuer requires that the card be read using a chip reader.

 >
503 Service unavailable TEMPORARY_ERROR

A temporary internal error occurred. You can safely retry your call using the same idempotency key.

 >
400 Bad request 
{
  "errors": [
    {
      "code": "AMOUNT_TOO_HIGH",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}