<- Refunds API

Refunds API

All versions ->

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
Link to section

Request body

Example code

Link to section

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.

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.

Min Length
1
Link to section

amount_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.

Link to section

app_fee_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.

Link to section

payment_id

string

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

Link to section

destination_id

string

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.

Link to section

unlinked

boolean

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.

Link to section

location_id

string

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

Max Length
50
Link to section

customer_id

string

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.

Link to section

reason

string

A description of the reason for the refund.

Max Length
192
Link to section

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.

Link to section

team_member_id

string

An optional TeamMember ID to associate with this refund.

Max Length
192
Link to section

cash_details

Additional details required when recording an unlinked cash refund (destination_id is CASH).

Link to section

external_details

Additional details required when recording an unlinked external refund (destination_id is EXTERNAL).

Link to section

Response fields

Link to section

errors

Information about errors encountered during the request.

Link to section

refund

The successfully created PaymentRefund.

Error descriptions