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

You are viewing an old version of the API
Refund payment

POST /v2/refunds

Refunds a payment.

You can refund the entire payment amount or a portion of it. You can use this endpoint to refund a card payment or record a refund of a cash or external payment. For more information, see Refund Payment.


Permissions
PAYMENTS_WRITE
Guide
Refund a payment
Try in API Explorer
Name Description
idempotency_key
string

Required

A unique string that identifies this RefundPayment request. The key can be any valid string but must be unique for every RefundPayment request.

For more information, see Idempotency.

Min Length 1
amount_money
Money

Required

The amount of money to refund.

This amount cannot be more than the total_money value of the payment minus the total amount of all previously completed refunds for this payment.

This amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts.

The currency code must match the currency associated with the business that is charging the card.

app_fee_money
Money

Beta

The amount of money the developer contributes to help cover the refunded amount. This amount is specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents).

The value cannot be more than the amount_money.

You can specify this parameter in a refund request only if the same parameter was also included when taking the payment. This is part of the application fee scenario the API supports. For more information, see Take Payments and Collect Fees.

To set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required. For more information, see Permissions.

payment_id
string

The unique ID of the payment being refunded. Must be provided and non-empty.

reason
string

A description of the reason for the refund.

Max Length 192
payment_version_token
string

Beta

Used for optimistic concurrency. This opaque token identifies the current Payment version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION_MISMATCH error is returned. If the versions match, or the field is not provided, the refund proceeds as normal.

team_member_id
string

An optional TeamMember ID to associate with this refund.

Max Length 192

Response Fields

Name Description
errors
Error [ ]

Information about errors encountered during the request.

refund
PaymentRefund

The successfully created PaymentRefund.

Examples

You are viewing an old version of the API
POST /v2/refunds
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js
curl https://connect.squareup.com/v2/refunds \
  -X POST \
  -H 'Square-Version: 2021-12-15' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "9b7f2dcf-49da-4411-b23e-a2d6af21333a",
    "payment_id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "app_fee_money": {
      "amount": 10,
      "currency": "USD"
    },
    "reason": "Example"
  }'
Response JSON
{
  "refund": {
    "id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY_KlWP8IC1557ddwc9QWTKrCVU6m0JXDz15R2Qym5eQfR",
    "status": "PENDING",
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "payment_id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY",
    "order_id": "1JLEUZeEooAIX8HMqm9kvWd69aQZY",
    "created_at": "2021-10-13T21:23:19.116Z",
    "updated_at": "2021-10-13T21:23:19.508Z",
    "app_fee_money": {
      "amount": 10,
      "currency": "USD"
    },
    "location_id": "L88917AVBK2S5",
    "reason": "Example"
  }
}

Error Descriptions

400 Bad request AMOUNT_TOO_HIGH

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

>
400 Bad request PAYMENT_NOT_REFUNDABLE

The payment is not refundable. For example, a previous refund has already been rejected and no new refunds can be accepted.

>
400 Bad request REFUND_AMOUNT_INVALID

The requested refund amount exceeds the amount available to refund.

>
400 Bad request REFUND_DECLINED

Request failed - The card issuer declined the refund.

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