• 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: 2021-12-15' \
  -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 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 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).

 >
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"
    }
  ]
}