Sign in
Refunds

RefundPayment

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.

post/v2/refunds

Request body

idempotency_keystring required

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

Keys are limited to a max of 45 characters - however, the number of allowed characters might be less than 45, if multi-byte characters are used.

For more information, see Idempotency.

app_fee_allocationsAppFeeAllocation[] nullable— unresolved $ref

Details pertaining to contributors to the refund of the application fee. The sum of the amounts in the app_fee_allocations must equal the app_fee_money amount, if present. If populated, an allocation must be present for every party that expects to contribute a portion of the refunded application fee, including the application developer.

payment_idstring nullable

The unique ID of the payment being refunded. Required when unlinked=false, otherwise must not be set.

destination_idstring nullable

The ID indicating where funds will be refunded to. Required for unlinked refunds. For more information, see Process an Unlinked Refund.

For refunds linked to Square payments, destination_id is usually omitted; in this case, funds will be returned to the original payment source. The field may be specified in order to request a cross-method refund to a gift card. For more information, see Cross-method refunds to gift cards.

unlinkedboolean nullable

Indicates that the refund is not linked to a Square payment. If set to true, destination_id and location_id must be supplied while payment_id must not be provided.

location_idstring nullable

The location ID associated with the unlinked refund. Required for requests specifying unlinked=true. Otherwise, if included when unlinked=false, will throw an error.

customer_idstring nullable

The Customer ID of the customer associated with the refund. This is required if the destination_id refers to a card on file created using the Cards API. Only allowed when unlinked=true.

reasonstring nullable

A description of the reason for the refund.

payment_version_tokenstring nullable

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_idstring nullable

An optional TeamMember ID to associate with this refund.

Example request

{
  "amount_money": {
    "amount": 1000,
    "currency": "USD"
  },
  "app_fee_money": {
    "amount": 10,
    "currency": "USD"
  },
  "idempotency_key": "9b7f2dcf-49da-4411-b23e-a2d6af21333a",
  "payment_id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY",
  "reason": "Example"
}

Response

Success

Example response

{
  "refund": {
    "amount_money": {
      "amount": 1000,
      "currency": "USD"
    },
    "app_fee_money": {
      "amount": 10,
      "currency": "USD"
    },
    "created_at": "2021-10-13T21:23:19.116Z",
    "id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY_KlWP8IC1557ddwc9QWTKrCVU6m0JXDz15R2Qym5eQfR",
    "location_id": "L88917AVBK2S5",
    "order_id": "1JLEUZeEooAIX8HMqm9kvWd69aQZY",
    "payment_id": "R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY",
    "reason": "Example",
    "status": "PENDING",
    "updated_at": "2021-10-13T21:23:19.508Z"
  }
}

Changes