Skip to main content
Server path: /square-payments | Type: Application | PCID required: Yes

​
Tools

ToolDescription
square_payments_cancel_paymentCancelPayment
square_payments_cancel_payment_by_idempotency_keyCancelPaymentByIdempotencyKey
square_payments_complete_paymentCompletePayment
square_payments_create_bank_accountCreateBankAccount
square_payments_create_cardCreateCard
square_payments_create_gift_cardCreateGiftCard
square_payments_create_gift_card_activityCreateGiftCardActivity
square_payments_create_paymentCreatePayment
square_payments_create_payment_linkCreatePaymentLink
square_payments_delete_payment_linkDeletePaymentLink
square_payments_disable_bank_accountDisableBankAccount
square_payments_disable_cardDisableCard
square_payments_get_bank_accountGetBankAccount
square_payments_get_bank_account_by_v1idGetBankAccountByV1Id
square_payments_get_paymentGetPayment
square_payments_get_payment_refundGetPaymentRefund
square_payments_get_payoutGetPayout
square_payments_link_customer_to_gift_cardLinkCustomerToGiftCard
square_payments_list_bank_accountsListBankAccounts
square_payments_list_cardsListCards
square_payments_list_cash_drawer_shift_eventsListCashDrawerShiftEvents
square_payments_list_cash_drawer_shiftsListCashDrawerShifts
square_payments_list_gift_card_activitiesListGiftCardActivities
square_payments_list_gift_cardsListGiftCards
square_payments_list_payment_linksListPaymentLinks
square_payments_list_payment_refundsListPaymentRefunds
square_payments_list_paymentsListPayments
square_payments_list_payout_entriesListPayoutEntries
square_payments_list_payoutsListPayouts
square_payments_refund_paymentRefundPayment
square_payments_register_domainRegisterDomain
square_payments_retrieve_cardRetrieveCard
square_payments_retrieve_cash_drawer_shiftRetrieveCashDrawerShift
square_payments_retrieve_gift_cardRetrieveGiftCard
square_payments_retrieve_gift_card_from_ganRetrieveGiftCardFromGAN
square_payments_retrieve_gift_card_from_nonceRetrieveGiftCardFromNonce
square_payments_retrieve_location_settingsRetrieveLocationSettings
square_payments_retrieve_merchant_settingsRetrieveMerchantSettings
square_payments_retrieve_payment_linkRetrievePaymentLink
square_payments_unlink_customer_from_gift_cardUnlinkCustomerFromGiftCard
square_payments_update_location_settingsUpdateLocationSettings
square_payments_update_merchant_settingsUpdateMerchantSettings
square_payments_update_paymentUpdatePayment
square_payments_update_payment_linkUpdatePaymentLink

​
square_payments_cancel_payment

CancelPayment Parameters:
ParameterTypeRequiredDefaultDescription
payment_idstringYes—The ID of the payment to cancel.

​
square_payments_cancel_payment_by_idempotency_key

CancelPaymentByIdempotencyKey Parameters:
ParameterTypeRequiredDefaultDescription
idempotency_keystringYes—The idempotency_key identifying the payment to be canceled.

​
square_payments_complete_payment

CompletePayment Parameters:
ParameterTypeRequiredDefaultDescription
payment_idstringYes—The unique ID identifying the payment to be completed.
version_tokenstringNo—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.

​
square_payments_create_bank_account

CreateBankAccount Parameters:
ParameterTypeRequiredDefaultDescription
customer_idstringNo—The ID of the customer associated with the bank account to be stored.
idempotency_keystringYes—Unique ID. For more information, see the Idempotency.
source_idstringYes—The ID of the source that represents the bank account information to be stored. This field accepts the payment token created by WebSDK

​
square_payments_create_card

CreateCard Parameters:
ParameterTypeRequiredDefaultDescription
cardobjectYes—Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
idempotency_keystringYes—A unique string that identifies this CreateCard request. Keys can be any valid string and must be unique for every request. Max: 45 characters See Idempotency keys for more information.
source_idstringYes—The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id.
verification_tokenstringNo—An identifying token generated by Payments.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity. See the SCA Overview.

​
square_payments_create_gift_card

CreateGiftCard Parameters:
ParameterTypeRequiredDefaultDescription
gift_cardobjectYes—Represents a Square gift card.
idempotency_keystringYes—A unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.
location_idstringYes—The ID of the location where the gift card should be registered for reporting purposes. Gift cards can be redeemed at any of the seller’s locations.

​
square_payments_create_gift_card_activity

CreateGiftCardActivity Parameters:
ParameterTypeRequiredDefaultDescription
gift_card_activityobjectYes—Represents an action performed on a gift card that affects its state or balance. A gift card activity contains information about a specific activity type. For example, a REDEEM activity includes a redeem_activity_details field that contains information about the redemption.
idempotency_keystringYes—A unique string that identifies the CreateGiftCardActivity request.

​
square_payments_create_payment

CreatePayment Parameters:
ParameterTypeRequiredDefaultDescription
accept_partial_authorizationbooleanNo—If set to true and charging a Square Gift Card, a payment might be returned with amount_money equal to less than what was requested. For example, a request for 20whenchargingaSquareGiftCardwithabalanceof20 when charging a Square Gift Card with a balance of 5 results in an APPROVED payment of $5. You might choose to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card payment. This field cannot be true when autocomplete = true. For more information, see Partial amount with Square Gift Cards. Default: false
amount_moneyobjectNo—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.
app_fee_allocationsobject[]No—Details pertaining to recipients 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 receive a portion of the application fee, including the application developer.
app_fee_moneyobjectNo—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.
autocompletebooleanNo—If set to true, this payment will be completed when possible. If set to false, this payment is held in an approved state until either explicitly completed (captured) or canceled (voided). For more information, see Delayed capture. Default: true
billing_addressobjectNo—Represents a postal address in a country. For more information, see Working with Addresses.
buyer_email_addressstringNo—The buyer’s email address.
buyer_phone_numberstringNo—The buyer’s phone number. Must follow the following format: 1. A leading + symbol (followed by a country code) 2. The phone number can contain spaces and the special characters ( , ) , - , and .. Alphabetical characters aren’t allowed. 3. The phone number must contain between 9 and 16 digits.
cash_detailsobjectNo—Stores details about a cash payment. Contains only non-confidential information. For more information, see Take Cash Payments.
customer_detailsobjectNo—Details about the customer making the payment.
customer_idstringNo—The Customer ID of the customer associated with the payment. This is required if the source_id refers to a card on file created using the Cards API.
delay_actionstringNo—The action to be applied to the payment when the delay_duration has elapsed. The action must be CANCEL or COMPLETE. For more information, see Time Threshold. Default: CANCEL
delay_durationstringNo—The duration of time after the payment’s creation when Square automatically either completes or cancels the payment depending on the delay_action field value. For more information, see Time threshold. This parameter should be specified as a time duration, in RFC 3339 format. Note: This feature is only supported for card payments. This parameter can only be set for a delayed capture payment (autocomplete=false). Default: - Card-present payments: “PT36H” (36 hours) from the creation time. - Card-not-present payments: “P7D” (7 days) from the creation time.
external_detailsobjectNo—Stores details about an external payment. Contains only non-confidential information. For more information, see Take External Payments.
idempotency_keystringYes—A unique string that identifies this CreatePayment request. Keys can be any valid string but must be unique for every CreatePayment request. Note: The number of allowed characters might be less than the stated maximum, if multi-byte characters are used. For more information, see Idempotency.
location_idstringNo—The location ID to associate with the payment. If not specified, the main location is used.
notestringNo—An optional note to be entered by the developer when creating a payment.
offline_payment_detailsobjectNo—Details specific to offline payments.
order_idstringNo—Associates a previously created order with this payment.
reference_idstringNo—A user-defined ID to associate with the payment. You can use this field to associate the payment to an entity in an external system (for example, you might specify an order ID that is generated by a third-party shopping cart).
shipping_addressobjectNo—Represents a postal address in a country. For more information, see Working with Addresses.
source_idstringYes—The ID for the source of funds for this payment. This could be a payment token generated by the Web Payments SDK for any of its supported methods, including cards, bank transfers, Afterpay or Cash App Pay. If recording a payment that the seller received outside of Square, specify either “CASH” or “EXTERNAL”. For more information, see Take Payments.
statement_description_identifierstringNo—Optional additional payment information to include on the customer’s card statement as part of the statement description. This can be, for example, an invoice number, ticket number, or short description that uniquely identifies the purchase. Note that the statement_description_identifier might get truncated on the statement description to fit the required information including the Square identifier (SQ *) and name of the seller taking the payment.
team_member_idstringNo—An optional TeamMember ID to associate with this payment.
tip_moneyobjectNo—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.
verification_tokenstringNo—An identifying token generated by payments.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity. For more information, see SCA Overview.
CreatePaymentLink Parameters:
ParameterTypeRequiredDefaultDescription
checkout_optionsobjectNo—Checkout Options
descriptionstringNo—A description of the payment link. You provide this optional description that is useful in your application context. It is not used anywhere.
idempotency_keystringNo—A unique string that identifies this CreatePaymentLinkRequest request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency.
orderobjectNo—Contains all information related to a single order to process with Square, including line items that specify the products to purchase. Order objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
payment_notestringNo—A note for the payment. After processing the payment, Square adds this note to the resulting Payment.
pre_populated_dataobjectNo—Describes buyer data to prepopulate in the payment form. For more information, see Optional Checkout Configurations.
quick_payobjectNo—Describes an ad hoc item and price to generate a quick pay checkout link. For more information, see Quick Pay Checkout.
DeletePaymentLink Parameters:
ParameterTypeRequiredDefaultDescription
idstringYes—The ID of the payment link to delete.

​
square_payments_disable_bank_account

DisableBankAccount Parameters:
ParameterTypeRequiredDefaultDescription
bank_account_idstringYes—The ID of the bank account to disable.

​
square_payments_disable_card

DisableCard Parameters:
ParameterTypeRequiredDefaultDescription
card_idstringYes—Unique ID for the desired Card.

​
square_payments_get_bank_account

GetBankAccount Parameters:
ParameterTypeRequiredDefaultDescription
bank_account_idstringYes—Square-issued ID of the desired BankAccount.

​
square_payments_get_bank_account_by_v1id

GetBankAccountByV1Id Parameters:
ParameterTypeRequiredDefaultDescription
v1_bank_account_idstringYes—Connect V1 ID of the desired BankAccount. For more information, see Retrieve a bank account by using an ID issued by V1 Bank Accounts API.

​
square_payments_get_payment

GetPayment Parameters:
ParameterTypeRequiredDefaultDescription
payment_idstringYes—A unique ID for the desired payment.

​
square_payments_get_payment_refund

GetPaymentRefund Parameters:
ParameterTypeRequiredDefaultDescription
refund_idstringYes—The unique ID for the desired PaymentRefund.

​
square_payments_get_payout

GetPayout Parameters:
ParameterTypeRequiredDefaultDescription
payout_idstringYes—The ID of the payout to retrieve the information for.
LinkCustomerToGiftCard Parameters:
ParameterTypeRequiredDefaultDescription
gift_card_idstringYes—The ID of the gift card to be linked.
customer_idstringYes—The ID of the customer to link to the gift card.

​
square_payments_list_bank_accounts

ListBankAccounts Parameters:
ParameterTypeRequiredDefaultDescription
cursorstringNo—The pagination cursor returned by a previous call to this endpoint. Use it in the next ListBankAccounts request to retrieve the next set of results. See the Pagination guide for more information.
limitintegerNo—Upper limit on the number of bank accounts to return in the response. Currently, 1000 is the largest supported limit. You can specify a limit of up to 1000 bank accounts. This is also the default limit.
location_idstringNo—Location ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific location.
customer_idstringNo—Customer ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific customer.

​
square_payments_list_cards

ListCards Parameters:
ParameterTypeRequiredDefaultDescription
cursorstringNo—A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Pagination for more information.
customer_idstringNo—Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned.
include_disabledbooleanNo—Includes disabled cards. By default, all enabled cards owned by the merchant are returned.
reference_idstringNo—Limit results to cards associated with the reference_id supplied.
sort_orderstringNo—Sorts the returned list by when the card was created with the specified order. This field defaults to ASC.

​
square_payments_list_cash_drawer_shift_events

ListCashDrawerShiftEvents Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringYes—The ID of the location to list cash drawer shifts for.
shift_idstringYes—The shift ID.
limitintegerNo—Number of resources to be returned in a page of results (200 by default, 1000 max).
cursorstringNo—Opaque cursor for fetching the next page of results.

​
square_payments_list_cash_drawer_shifts

ListCashDrawerShifts Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringYes—The ID of the location to query for a list of cash drawer shifts.
sort_orderstringNo—The order in which cash drawer shifts are listed in the response, based on their opened_at field. Default value: ASC
begin_timestringNo—The inclusive start time of the query on opened_at, in ISO 8601 format.
end_timestringNo—The exclusive end date of the query on opened_at, in ISO 8601 format.
limitintegerNo—Number of cash drawer shift events in a page of results (200 by default, 1000 max).
cursorstringNo—Opaque cursor for fetching the next page of results.

​
square_payments_list_gift_card_activities

ListGiftCardActivities Parameters:
ParameterTypeRequiredDefaultDescription
gift_card_idstringNo—If a gift card ID is provided, the endpoint returns activities related to the specified gift card. Otherwise, the endpoint returns all gift card activities for the seller.
typestringNo—If a type is provided, the endpoint returns gift card activities of the specified type. Otherwise, the endpoint returns all types of gift card activities.
location_idstringNo—If a location ID is provided, the endpoint returns gift card activities for the specified location. Otherwise, the endpoint returns gift card activities for all locations.
begin_timestringNo—The timestamp for the beginning of the reporting period, in RFC 3339 format. This start time is inclusive. The default value is the current time minus one year.
end_timestringNo—The timestamp for the end of the reporting period, in RFC 3339 format. This end time is inclusive. The default value is the current time.
limitintegerNo—If a limit is provided, the endpoint returns the specified number of results (or fewer) per page. The maximum value is 100. The default value is 50. For more information, see Pagination.
cursorstringNo—A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see Pagination.
sort_orderstringNo—The order in which the endpoint returns the activities, based on created_at. - ASC - Oldest to newest. - DESC - Newest to oldest (default).

​
square_payments_list_gift_cards

ListGiftCards Parameters:
ParameterTypeRequiredDefaultDescription
typestringNo—If a type is provided, the endpoint returns gift cards of the specified type. Otherwise, the endpoint returns gift cards of all types.
statestringNo—If a state is provided, the endpoint returns the gift cards in the specified state. Otherwise, the endpoint returns the gift cards of all states.
limitintegerNo—If a limit is provided, the endpoint returns only the specified number of results per page. The maximum value is 200. The default value is 30. For more information, see Pagination.
cursorstringNo—A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see Pagination.
customer_idstringNo—If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.
ListPaymentLinks Parameters:
ParameterTypeRequiredDefaultDescription
cursorstringNo—A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see Pagination.
limitintegerNo—A limit on the number of results to return per page. The limit is advisory and the implementation might return more or less results. If the supplied limit is negative, zero, or greater than the maximum limit of 1000, it is ignored. Default value: 100

​
square_payments_list_payment_refunds

ListPaymentRefunds Parameters:
ParameterTypeRequiredDefaultDescription
begin_timestringNo—Indicates the start of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the created_at field for each PaymentRefund. Default: The current time minus one year.
end_timestringNo—Indicates the end of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the created_at field for each PaymentRefund. Default: The current time.
sort_orderstringNo—The order in which results are listed by PaymentRefund.created_at: - ASC - Oldest to newest. - DESC - Newest to oldest (default).
cursorstringNo—A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
location_idstringNo—Limit results to the location supplied. By default, results are returned for all locations associated with the seller.
statusstringNo—If provided, only refunds with the given status are returned. For a list of refund status values, see PaymentRefund. Default: If omitted, refunds are returned regardless of their status.
source_typestringNo—If provided, only returns refunds whose payments have the indicated source type. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, and EXTERNAL. For information about these payment source types, see Take Payments. Default: If omitted, refunds are returned regardless of the source type.
limitintegerNo—The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. If the supplied value is greater than 100, no more than 100 results are returned. Default: 100
updated_at_begin_timestringNo—Indicates the start of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the updated_at field for each PaymentRefund. Default: If omitted, the time range starts at begin_time.
updated_at_end_timestringNo—Indicates the end of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the updated_at field for each PaymentRefund. Default: The current time.
sort_fieldstringNo—The field used to sort results by. The default is CREATED_AT.

​
square_payments_list_payments

ListPayments Parameters:
ParameterTypeRequiredDefaultDescription
begin_timestringNo—Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the created_at field for each Payment. Inclusive. Default: The current time minus one year.
end_timestringNo—Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the created_at field for each Payment. Default: The current time.
sort_orderstringNo—The order in which results are listed by ListPaymentsRequest.sort_field: - ASC - Oldest to newest. - DESC - Newest to oldest (default).
cursorstringNo—A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
location_idstringNo—Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller.
totalintegerNo—The exact amount in the total_money for a payment.
last_4stringNo—The last four digits of a payment card.
card_brandstringNo—The brand of the payment card (for example, VISA).
limitintegerNo—The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: 100
is_offline_paymentbooleanNo—Whether the payment was taken offline or not.
offline_begin_timestringNo—Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the offline_payment_details.client_created_at field for each Payment. If set, payments without a value set in offline_payment_details.client_created_at will not be returned. Default: The current time.
offline_end_timestringNo—Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the offline_payment_details.client_created_at field for each Payment. If set, payments without a value set in offline_payment_details.client_created_at will not be returned. Default: The current time.
updated_at_begin_timestringNo—Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the updated_at field for each Payment.
updated_at_end_timestringNo—Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the updated_at field for each Payment.
sort_fieldstringNo—The field used to sort results by. The default is CREATED_AT.

​
square_payments_list_payout_entries

ListPayoutEntries Parameters:
ParameterTypeRequiredDefaultDescription
payout_idstringYes—The ID of the payout to retrieve the information for.
sort_orderstringNo—The order in which payout entries are listed.
cursorstringNo—A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination. If request parameters change between requests, subsequent results may contain duplicates or missing records.
limitintegerNo—The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: 100

​
square_payments_list_payouts

ListPayouts Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringNo—The ID of the location for which to list the payouts. By default, payouts are returned for the default (main) location associated with the seller.
statusstringNo—If provided, only payouts with the given status are returned.
begin_timestringNo—The timestamp for the beginning of the payout creation time, in RFC 3339 format. Inclusive. Default: The current time minus one year.
end_timestringNo—The timestamp for the end of the payout creation time, in RFC 3339 format. Default: The current time.
sort_orderstringNo—The order in which payouts are listed.
cursorstringNo—A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination. If request parameters change between requests, subsequent results may contain duplicates or missing records.
limitintegerNo—The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: 100

​
square_payments_refund_payment

RefundPayment Parameters:
ParameterTypeRequiredDefaultDescription
amount_moneyobjectYes—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.
app_fee_allocationsobject[]No—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.
app_fee_moneyobjectNo—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.
cash_detailsobjectNo—Stores details about a cash refund. Contains only non-confidential information.
customer_idstringNo—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.
destination_idstringNo—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.
external_detailsobjectNo—Stores details about an external refund. Contains only non-confidential information.
idempotency_keystringYes—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.
location_idstringNo—The location ID associated with the unlinked refund. Required for requests specifying unlinked=true. Otherwise, if included when unlinked=false, will throw an error.
payment_idstringNo—The unique ID of the payment being refunded. Required when unlinked=false, otherwise must not be set.
payment_version_tokenstringNo—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.
reasonstringNo—A description of the reason for the refund.
team_member_idstringNo—An optional TeamMember ID to associate with this refund.
unlinkedbooleanNo—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.

​
square_payments_register_domain

RegisterDomain Parameters:
ParameterTypeRequiredDefaultDescription
domain_namestringYes—A domain name as described in RFC-1034 that will be registered with ApplePay.

​
square_payments_retrieve_card

RetrieveCard Parameters:
ParameterTypeRequiredDefaultDescription
card_idstringYes—Unique ID for the desired Card.

​
square_payments_retrieve_cash_drawer_shift

RetrieveCashDrawerShift Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringYes—The ID of the location to retrieve cash drawer shifts from.
shift_idstringYes—The shift ID.

​
square_payments_retrieve_gift_card

RetrieveGiftCard Parameters:
ParameterTypeRequiredDefaultDescription
idstringYes—The ID of the gift card to retrieve.

​
square_payments_retrieve_gift_card_from_gan

RetrieveGiftCardFromGAN Parameters:
ParameterTypeRequiredDefaultDescription
ganstringYes—The gift card account number (GAN) of the gift card to retrieve. The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported. Square-issued gift cards have 16-digit GANs.

​
square_payments_retrieve_gift_card_from_nonce

RetrieveGiftCardFromNonce Parameters:
ParameterTypeRequiredDefaultDescription
noncestringYes—The payment token of the gift card to retrieve. Payment tokens are generated by the Web Payments SDK or In-App Payments SDK.

​
square_payments_retrieve_location_settings

RetrieveLocationSettings Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringYes—The ID of the location for which to retrieve settings.

​
square_payments_retrieve_merchant_settings

RetrieveMerchantSettings
RetrievePaymentLink Parameters:
ParameterTypeRequiredDefaultDescription
idstringYes—The ID of link to retrieve.
UnlinkCustomerFromGiftCard Parameters:
ParameterTypeRequiredDefaultDescription
gift_card_idstringYes—The ID of the gift card to be unlinked.
customer_idstringYes—The ID of the customer to unlink from the gift card.

​
square_payments_update_location_settings

UpdateLocationSettings Parameters:
ParameterTypeRequiredDefaultDescription
location_idstringYes—The ID of the location for which to retrieve settings.
location_settingsobjectYes—Location Settings

​
square_payments_update_merchant_settings

UpdateMerchantSettings Parameters:
ParameterTypeRequiredDefaultDescription
merchant_settingsobjectYes—Merchant Settings

​
square_payments_update_payment

UpdatePayment Parameters:
ParameterTypeRequiredDefaultDescription
payment_idstringYes—The ID of the payment to update.
idempotency_keystringYes—A unique string that identifies this UpdatePayment request. Keys can be any valid string but must be unique for every UpdatePayment request. For more information, see Idempotency.
paymentobjectNo—Represents a payment processed by the Square API.
UpdatePaymentLink Parameters:
ParameterTypeRequiredDefaultDescription
idstringYes—The ID of the payment link to update.
payment_linkobjectYes—Payment Link