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

You are viewing an old version of the API
Create refund

Deprecated
Effective August 15th, 2019

Initiates a refund for a previously charged tender.

You must issue a refund within 120 days of the associated payment. See this article for more information on refund behavior.

NOTE: Card-present transactions with Interac credit cards cannot be refunded using the Connect API. Interac transactions must refunded in-person (e.g., dipping the card using POS app).

Permissions
PAYMENTS_WRITE

Deprecation date
2019-08-15
Retirement date
2021-09-01
Replaced by
RefundPayment
Migration guide
Name Description
location_id
string

Required

The ID of the original transaction's associated location.

transaction_id
string

Required

The ID of the original transaction that includes the tender to refund.

Name Description
idempotency_key
string

Required

A value you specify that uniquely identifies this refund among refunds you've created for the tender.

If you're unsure whether a particular refund succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the refund.

See Idempotency keys for more information.

Max Length 192 Min Length 1
tender_id
string

Required

The ID of the tender to refund.

A Transaction has one or more tenders (i.e., methods of payment) associated with it, and you refund each tender separately with the Connect API.

Max Length 192 Min Length 1
reason
string

A description of the reason for the refund.

Default value: Refund via API

Max Length 192
amount_money
Money

Required

The amount of money to refund.

Note that you specify the amount in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See Working with monetary amounts for details.

This amount cannot exceed the amount that was originally charged to the tender that corresponds to tender_id.

Response Fields

Name Description
errors
Error [ ]

Any errors that occurred during the request.

refund
Refund

The created refund.

Examples

You are viewing an old version of the API
POST /v2/locations/{location_id}/transactions/{transaction_id}/refund
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
curl https://connect.squareup.com/v2/locations/18YC4JDH91E1H/transactions/KnL67ZIwXCPtzOrqj0HrkxMF/refund \
  -X POST \
  -H 'Square-Version: 2020-08-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "86ae1696-b1e3-4328-af6d-f1e04d947ad2",
    "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
    "reason": "a reason",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    }
  }'
Response JSON
{
  "refund": {
    "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
    "location_id": "18YC4JDH91E1H",
    "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
    "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
    "created_at": "2016-02-12T00:28:18Z",
    "reason": "some reason",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "additional_recipients": [
      {
        "location_id": "057P5VYJ4A5X1",
        "description": "Application fees",
        "amount_money": {
          "amount": 10,
          "currency": "USD"
        },
        "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF"
      }
    ],
    "status": "PENDING"
  }
}

Error Descriptions

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
{
  "errors": [
    {
      "code": "PAYMENT_NOT_REFUNDABLE",
      "category": "REFUND_ERROR"
    }
  ]
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?