refund-payment-request.md

Refund Payment Request

Describes a request to refund a payment using RefundPayment.

Structure

RefundPaymentRequest

Fields

Name	Type	Tags	Description
IdempotencyKey	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. Constraints: Minimum Length: 1
AmountMoney	Money	Required	Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
AppFeeMoney	Money	Optional	Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
PaymentId	string	Optional	The unique ID of the payment being refunded. Required when unlinked=false, otherwise must not be set.
DestinationId	string	Optional	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.
Unlinked	bool?	Optional	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.
LocationId	string	Optional	The location ID associated with the unlinked refund. Required for requests specifying unlinked=true. Otherwise, if included when unlinked=false, will throw an error. Constraints: Maximum Length: 50
CustomerId	string	Optional	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.
Reason	string	Optional	A description of the reason for the refund. Constraints: Maximum Length: 192
PaymentVersionToken	string	Optional	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.
TeamMemberId	string	Optional	An optional TeamMember ID to associate with this refund. Constraints: Maximum Length: 192
CashDetails	DestinationDetailsCashRefundDetails	Optional	Stores details about a cash refund. Contains only non-confidential information.
ExternalDetails	DestinationDetailsExternalRefundDetails	Optional	Stores details about an external refund. Contains only non-confidential information.

Example (as JSON)

{
  "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",
  "destination_id": "destination_id6",
  "unlinked": false,
  "location_id": "location_id8"
}