{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/square/main/json-schema/square-list-payout-entries-response-schema.json", "title": "ListPayoutEntriesResponse", "description": "The response to retrieve payout records entries.", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/square-payouts-api-openapi.yml#/components/schemas/ListPayoutEntriesResponse", "type": "object", "x-release-status": "PUBLIC", "properties": { "payout_entries": { "type": "array", "items": { "$ref": "#/$defs/PayoutEntry" }, "description": "The requested list of payout entries, ordered with the given or default sort order." }, "cursor": { "type": "string", "description": "The pagination cursor to be used in a subsequent request. If empty, this is the final response.\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)." }, "errors": { "type": "array", "items": { "$ref": "#/$defs/Error" }, "description": "Information about errors encountered during the request." } }, "$defs": { "ActivityType": { "type": "string", "enum": [ "ADJUSTMENT", "APP_FEE_REFUND", "APP_FEE_REVENUE", "AUTOMATIC_SAVINGS", "AUTOMATIC_SAVINGS_REVERSED", "CHARGE", "DEPOSIT_FEE", "DEPOSIT_FEE_REVERSED", "DISPUTE", "ESCHEATMENT", "FEE", "FREE_PROCESSING", "HOLD_ADJUSTMENT", "INITIAL_BALANCE_CHANGE", "MONEY_TRANSFER", "MONEY_TRANSFER_REVERSAL", "OPEN_DISPUTE", "OTHER", "OTHER_ADJUSTMENT", "PAID_SERVICE_FEE", "PAID_SERVICE_FEE_REFUND", "REDEMPTION_CODE", "REFUND", "RELEASE_ADJUSTMENT", "RESERVE_HOLD", "RESERVE_RELEASE", "RETURNED_PAYOUT", "SQUARE_CAPITAL_PAYMENT", "SQUARE_CAPITAL_REVERSED_PAYMENT", "SUBSCRIPTION_FEE", "SUBSCRIPTION_FEE_PAID_REFUND", "SUBSCRIPTION_FEE_REFUND", "TAX_ON_FEE", "THIRD_PARTY_FEE", "THIRD_PARTY_FEE_REFUND", "PAYOUT", "AUTOMATIC_BITCOIN_CONVERSIONS", "AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED", "CREDIT_CARD_REPAYMENT", "CREDIT_CARD_REPAYMENT_REVERSED", "LOCAL_OFFERS_CASHBACK", "LOCAL_OFFERS_FEE", "PERCENTAGE_PROCESSING_ENROLLMENT", "PERCENTAGE_PROCESSING_DEACTIVATION", "PERCENTAGE_PROCESSING_REPAYMENT", "PERCENTAGE_PROCESSING_REPAYMENT_REVERSED", "PROCESSING_FEE", "PROCESSING_FEE_REFUND", "UNDO_PROCESSING_FEE_REFUND", "GIFT_CARD_LOAD_FEE", "GIFT_CARD_LOAD_FEE_REFUND", "UNDO_GIFT_CARD_LOAD_FEE_REFUND", "BALANCE_FOLDERS_TRANSFER", "BALANCE_FOLDERS_TRANSFER_REVERSED", "GIFT_CARD_POOL_TRANSFER", "GIFT_CARD_POOL_TRANSFER_REVERSED", "SQUARE_PAYROLL_TRANSFER", "SQUARE_PAYROLL_TRANSFER_REVERSED" ], "x-enum-elements": [ { "name": "ADJUSTMENT", "description": "A manual adjustment applied to the seller's account by Square." }, { "name": "APP_FEE_REFUND", "description": "A refund for an application fee on a payment." }, { "name": "APP_FEE_REVENUE", "description": "Revenue generated from an application fee on a payment." }, { "name": "AUTOMATIC_SAVINGS", "description": "An automatic transfer from the payment processing balance to the Square Savings account. These are generally proportional to the seller's sales." }, { "name": "AUTOMATIC_SAVINGS_REVERSED", "description": "An automatic transfer from the Square Savings account back to the processing balance. These are generally proportional to the seller's refunds." }, { "name": "CHARGE", "description": "A credit card payment capture." }, { "name": "DEPOSIT_FEE", "description": "A fee assessed because of a deposit, such as an instant deposit." }, { "name": "DEPOSIT_FEE_REVERSED", "description": "Indicates that Square returned a fee that was previously assessed because of a deposit, such as an instant deposit, back to the seller's account." }, { "name": "DISPUTE", "description": "The balance change due to a dispute event." }, { "name": "ESCHEATMENT", "description": "An escheatment entry for remittance." }, { "name": "FEE", "description": "The cost plus adjustment fee." }, { "name": "FREE_PROCESSING", "description": "Square offers free payments processing for a variety of business scenarios, including seller\nreferrals or when Square wants to apologize (for example, for a bug, customer service, or repricing complication).\nThis entry represents a credit to the seller for the purposes of free processing." }, { "name": "HOLD_ADJUSTMENT", "description": "An adjustment made by Square related to holding a payment." }, { "name": "INITIAL_BALANCE_CHANGE", "description": "An external change to a seller's balance (initial, in the sense that it causes the creation of the other activity types, such as a hold and refund)." }, { "name": "MONEY_TRANSFER", "description": "The balance change from a money transfer." }, { "name": "MONEY_TRANSFER_REVERSAL", "description": "The reversal of a money transfer." }, { "name": "OPEN_DISPUTE", "description": "The balance change for a chargeback that's been filed." }, { "name": "OTHER", "description": "Any other type that doesn't belong in the rest of the types." }, { "name": "OTHER_ADJUSTMENT", "description": "Any other type of adjustment that doesn't fall under existing types." }, { "name": "PAID_SERVICE_FEE", "description": "A fee paid to a third-party seller." }, { "name": "PAID_SERVICE_FEE_REFUND", "description": "A fee refunded to a third-party seller." }, { "name": "REDEMPTION_CODE", "description": "Repayment for a redemption code." }, { "name": "REFUND", "description": "A refund for an existing card payment." }, { "name": "RELEASE_ADJUSTMENT", "description": "An adjustment made by Square related to releasing a payment." }, { "name": "RESERVE_HOLD", "description": "Fees paid for a funding risk reserve." }, { "name": "RESERVE_RELEASE", "description": "Fees released from a risk reserve." }, { "name": "RETURNED_PAYOUT", "description": "An entry created when Square receives a response for the ACH file that Square sent indicating that the\nsettlement of the original entry failed." }, { "name": "SQUARE_CAPITAL_PAYMENT", "description": "A capital merchant cash advance (MCA) assessment. These are generally proportional to the merchant's sales but can be issued for other reasons related to the MCA." }, { "name": "SQUARE_CAPITAL_REVERSED_PAYMENT", "description": "A capital merchant cash advance (MCA) assessment refund. These are generally proportional to the merchant's refunds but can be issued for other reasons related to the MCA." }, { "name": "SUBSCRIPTION_FEE", "description": "A fee charged for subscription to a Square product." }, { "name": "SUBSCRIPTION_FEE_PAID_REFUND", "description": "A Square subscription fee that's been refunded." }, { "name": "SUBSCRIPTION_FEE_REFUND", "description": "The refund of a previously charged Square product subscription fee." }, { "name": "TAX_ON_FEE", "description": "The tax paid on fee amounts." }, { "name": "THIRD_PARTY_FEE", "description": "Fees collected by a third-party platform." }, { "name": "THIRD_PARTY_FEE_REFUND", "description": "Refunded fees from a third-party platform." }, { "name": "PAYOUT", "description": "The balance change due to a money transfer. Note that this type is never returned by the Payouts API." }, { "name": "AUTOMATIC_BITCOIN_CONVERSIONS", "description": "Indicates that the portion of each payment withheld by Square was automatically converted into bitcoin using Cash App. The seller manages their bitcoin in their Cash App account." }, { "name": "AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED", "description": "Indicates that a withheld payment, which was scheduled to be converted into bitcoin using Cash App, was deposited back to the Square payments balance." }, { "name": "CREDIT_CARD_REPAYMENT", "description": "Indicates that a repayment toward the outstanding balance on the seller's Square credit card was made." }, { "name": "CREDIT_CARD_REPAYMENT_REVERSED", "description": "Indicates that a repayment toward the outstanding balance on the seller's Square credit card was reversed." }, { "name": "LOCAL_OFFERS_CASHBACK", "description": "Cashback amount given by a Square Local Offers seller to their customer for a purchase." }, { "name": "LOCAL_OFFERS_FEE", "description": "A commission fee paid by a Square Local Offers seller to Square for a purchase discovered through Square Local Offers." }, { "name": "PERCENTAGE_PROCESSING_ENROLLMENT", "description": "When activating Percentage Processing, a credit is applied to the seller’s account to offset any negative balance caused by a dispute." }, { "name": "PERCENTAGE_PROCESSING_DEACTIVATION", "description": "Deducting the outstanding Percentage Processing balance from the seller’s account. It's the final installment in repaying the dispute-induced negative balance through percentage processing." }, { "name": "PERCENTAGE_PROCESSING_REPAYMENT", "description": "Withheld funds from a payment to cover a negative balance. It's an installment to repay the amount from a dispute that had been offset during Percentage Processing enrollment." }, { "name": "PERCENTAGE_PROCESSING_REPAYMENT_REVERSED", "description": "The reversal of a percentage processing repayment that happens for example when a refund is issued for a payment." }, { "name": "PROCESSING_FEE", "description": "The processing fee for a payment. If sellers opt for Gross Settlement, i.e., direct bank withdrawal instead of deducting fees from daily sales, the processing fee is recorded separately as a new payout entry, not part of the CHARGE payout entry." }, { "name": "PROCESSING_FEE_REFUND", "description": "The processing fee for a payment refund issued by sellers enrolled in Gross Settlement. The refunded processing fee is recorded separately as a new payout entry, not part of the REFUND payout entry." }, { "name": "UNDO_PROCESSING_FEE_REFUND", "description": "When undoing a processing fee refund in a Gross Settlement payment, this payout entry type is used." }, { "name": "GIFT_CARD_LOAD_FEE", "description": "Fee collected during the sale or reload of a gift card. This fee, which is a portion of the amount loaded on the gift card, is deducted from the merchant's payment balance." }, { "name": "GIFT_CARD_LOAD_FEE_REFUND", "description": "Refund for fee charged during the sale or reload of a gift card." }, { "name": "UNDO_GIFT_CARD_LOAD_FEE_REFUND", "description": "The undo of a refund for a fee charged during the sale or reload of a gift card." }, { "name": "BALANCE_FOLDERS_TRANSFER", "description": "A transfer of funds to a banking folder. In the United States, the folder name is 'Checking Folder'; in Canada, it's 'Balance Folder.'" }, { "name": "BALANCE_FOLDERS_TRANSFER_REVERSED", "description": "A reversal of transfer of funds from a banking folder. In the United States, the folder name is 'Checking Folder'; in Canada, it's 'Balance Folder.'" }, { "name": "GIFT_CARD_POOL_TRANSFER", "description": "A transfer of gift card funds to a central gift card pool account. In franchises, when gift cards are loaded or reloaded at any location, the money transfers to the franchisor's account." }, { "name": "GIFT_CARD_POOL_TRANSFER_REVERSED", "description": "A reversal of transfer of gift card funds from a central gift card pool account. In franchises, when gift cards are loaded or reloaded at any location, the money transfers to the franchisor's account." }, { "name": "SQUARE_PAYROLL_TRANSFER", "description": "A payroll payment that was transferred to a team member’s bank account." }, { "name": "SQUARE_PAYROLL_TRANSFER_REVERSED", "description": "A payroll payment to a team member’s bank account that was deposited back to the seller’s account by Square." } ], "x-release-status": "PUBLIC" }, "Currency": { "type": "string", "enum": [ "UNKNOWN_CURRENCY", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SLE", "SOS", "SRD", "SSP", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "USS", "UYI", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF", "XPT", "XTS", "XXX", "YER", "ZAR", "ZMK", "ZMW", "BTC", "XUS" ], "x-enum-elements": [ { "name": "UNKNOWN_CURRENCY", "description": "Unknown currency" }, { "name": "AED", "description": "United Arab Emirates dirham" }, { "name": "AFN", "description": "Afghan afghani" }, { "name": "ALL", "description": "Albanian lek" }, { "name": "AMD", "description": "Armenian dram" }, { "name": "ANG", "description": "Netherlands Antillean guilder" }, { "name": "AOA", "description": "Angolan kwanza" }, { "name": "ARS", "description": "Argentine peso" }, { "name": "AUD", "description": "Australian dollar" }, { "name": "AWG", "description": "Aruban florin" }, { "name": "AZN", "description": "Azerbaijani manat" }, { "name": "BAM", "description": "Bosnia and Herzegovina convertible mark" }, { "name": "BBD", "description": "Barbados dollar" }, { "name": "BDT", "description": "Bangladeshi taka" }, { "name": "BGN", "description": "Bulgarian lev" }, { "name": "BHD", "description": "Bahraini dinar" }, { "name": "BIF", "description": "Burundian franc" }, { "name": "BMD", "description": "Bermudian dollar" }, { "name": "BND", "description": "Brunei dollar" }, { "name": "BOB", "description": "Boliviano" }, { "name": "BOV", "description": "Bolivian Mvdol" }, { "name": "BRL", "description": "Brazilian real" }, { "name": "BSD", "description": "Bahamian dollar" }, { "name": "BTN", "description": "Bhutanese ngultrum" }, { "name": "BWP", "description": "Botswana pula" }, { "name": "BYR", "description": "Belarusian ruble" }, { "name": "BZD", "description": "Belize dollar" }, { "name": "CAD", "description": "Canadian dollar" }, { "name": "CDF", "description": "Congolese franc" }, { "name": "CHE", "description": "WIR Euro" }, { "name": "CHF", "description": "Swiss franc" }, { "name": "CHW", "description": "WIR Franc" }, { "name": "CLF", "description": "Unidad de Fomento" }, { "name": "CLP", "description": "Chilean peso" }, { "name": "CNY", "description": "Chinese yuan" }, { "name": "COP", "description": "Colombian peso" }, { "name": "COU", "description": "Unidad de Valor Real" }, { "name": "CRC", "description": "Costa Rican colon" }, { "name": "CUC", "description": "Cuban convertible peso" }, { "name": "CUP", "description": "Cuban peso" }, { "name": "CVE", "description": "Cape Verdean escudo" }, { "name": "CZK", "description": "Czech koruna" }, { "name": "DJF", "description": "Djiboutian franc" }, { "name": "DKK", "description": "Danish krone" }, { "name": "DOP", "description": "Dominican peso" }, { "name": "DZD", "description": "Algerian dinar" }, { "name": "EGP", "description": "Egyptian pound" }, { "name": "ERN", "description": "Eritrean nakfa" }, { "name": "ETB", "description": "Ethiopian birr" }, { "name": "EUR", "description": "Euro" }, { "name": "FJD", "description": "Fiji dollar" }, { "name": "FKP", "description": "Falkland Islands pound" }, { "name": "GBP", "description": "Pound sterling" }, { "name": "GEL", "description": "Georgian lari" }, { "name": "GHS", "description": "Ghanaian cedi" }, { "name": "GIP", "description": "Gibraltar pound" }, { "name": "GMD", "description": "Gambian dalasi" }, { "name": "GNF", "description": "Guinean franc" }, { "name": "GTQ", "description": "Guatemalan quetzal" }, { "name": "GYD", "description": "Guyanese dollar" }, { "name": "HKD", "description": "Hong Kong dollar" }, { "name": "HNL", "description": "Honduran lempira" }, { "name": "HRK", "description": "Croatian kuna" }, { "name": "HTG", "description": "Haitian gourde" }, { "name": "HUF", "description": "Hungarian forint" }, { "name": "IDR", "description": "Indonesian rupiah" }, { "name": "ILS", "description": "Israeli new shekel" }, { "name": "INR", "description": "Indian rupee" }, { "name": "IQD", "description": "Iraqi dinar" }, { "name": "IRR", "description": "Iranian rial" }, { "name": "ISK", "description": "Icelandic króna" }, { "name": "JMD", "description": "Jamaican dollar" }, { "name": "JOD", "description": "Jordanian dinar" }, { "name": "JPY", "description": "Japanese yen" }, { "name": "KES", "description": "Kenyan shilling" }, { "name": "KGS", "description": "Kyrgyzstani som" }, { "name": "KHR", "description": "Cambodian riel" }, { "name": "KMF", "description": "Comoro franc" }, { "name": "KPW", "description": "North Korean won" }, { "name": "KRW", "description": "South Korean won" }, { "name": "KWD", "description": "Kuwaiti dinar" }, { "name": "KYD", "description": "Cayman Islands dollar" }, { "name": "KZT", "description": "Kazakhstani tenge" }, { "name": "LAK", "description": "Lao kip" }, { "name": "LBP", "description": "Lebanese pound" }, { "name": "LKR", "description": "Sri Lankan rupee" }, { "name": "LRD", "description": "Liberian dollar" }, { "name": "LSL", "description": "Lesotho loti" }, { "name": "LTL", "description": "Lithuanian litas" }, { "name": "LVL", "description": "Latvian lats" }, { "name": "LYD", "description": "Libyan dinar" }, { "name": "MAD", "description": "Moroccan dirham" }, { "name": "MDL", "description": "Moldovan leu" }, { "name": "MGA", "description": "Malagasy ariary" }, { "name": "MKD", "description": "Macedonian denar" }, { "name": "MMK", "description": "Myanmar kyat" }, { "name": "MNT", "description": "Mongolian tögrög" }, { "name": "MOP", "description": "Macanese pataca" }, { "name": "MRO", "description": "Mauritanian ouguiya" }, { "name": "MUR", "description": "Mauritian rupee" }, { "name": "MVR", "description": "Maldivian rufiyaa" }, { "name": "MWK", "description": "Malawian kwacha" }, { "name": "MXN", "description": "Mexican peso" }, { "name": "MXV", "description": "Mexican Unidad de Inversion" }, { "name": "MYR", "description": "Malaysian ringgit" }, { "name": "MZN", "description": "Mozambican metical" }, { "name": "NAD", "description": "Namibian dollar" }, { "name": "NGN", "description": "Nigerian naira" }, { "name": "NIO", "description": "Nicaraguan córdoba" }, { "name": "NOK", "description": "Norwegian krone" }, { "name": "NPR", "description": "Nepalese rupee" }, { "name": "NZD", "description": "New Zealand dollar" }, { "name": "OMR", "description": "Omani rial" }, { "name": "PAB", "description": "Panamanian balboa" }, { "name": "PEN", "description": "Peruvian sol" }, { "name": "PGK", "description": "Papua New Guinean kina" }, { "name": "PHP", "description": "Philippine peso" }, { "name": "PKR", "description": "Pakistani rupee" }, { "name": "PLN", "description": "Polish zBoty" }, { "name": "PYG", "description": "Paraguayan guaraní" }, { "name": "QAR", "description": "Qatari riyal" }, { "name": "RON", "description": "Romanian leu" }, { "name": "RSD", "description": "Serbian dinar" }, { "name": "RUB", "description": "Russian ruble" }, { "name": "RWF", "description": "Rwandan franc" }, { "name": "SAR", "description": "Saudi riyal" }, { "name": "SBD", "description": "Solomon Islands dollar" }, { "name": "SCR", "description": "Seychelles rupee" }, { "name": "SDG", "description": "Sudanese pound" }, { "name": "SEK", "description": "Swedish krona" }, { "name": "SGD", "description": "Singapore dollar" }, { "name": "SHP", "description": "Saint Helena pound" }, { "name": "SLL", "description": "Sierra Leonean first leone" }, { "name": "SLE", "description": "Sierra Leonean second leone" }, { "name": "SOS", "description": "Somali shilling" }, { "name": "SRD", "description": "Surinamese dollar" }, { "name": "SSP", "description": "South Sudanese pound" }, { "name": "STD", "description": "São Tomé and Príncipe dobra" }, { "name": "SVC", "description": "Salvadoran colón" }, { "name": "SYP", "description": "Syrian pound" }, { "name": "SZL", "description": "Swazi lilangeni" }, { "name": "THB", "description": "Thai baht" }, { "name": "TJS", "description": "Tajikstani somoni" }, { "name": "TMT", "description": "Turkmenistan manat" }, { "name": "TND", "description": "Tunisian dinar" }, { "name": "TOP", "description": "Tongan pa'anga" }, { "name": "TRY", "description": "Turkish lira" }, { "name": "TTD", "description": "Trinidad and Tobago dollar" }, { "name": "TWD", "description": "New Taiwan dollar" }, { "name": "TZS", "description": "Tanzanian shilling" }, { "name": "UAH", "description": "Ukrainian hryvnia" }, { "name": "UGX", "description": "Ugandan shilling" }, { "name": "USD", "description": "United States dollar" }, { "name": "USN", "description": "United States dollar (next day)" }, { "name": "USS", "description": "United States dollar (same day)" }, { "name": "UYI", "description": "Uruguay Peso en Unidedades Indexadas" }, { "name": "UYU", "description": "Uruguyan peso" }, { "name": "UZS", "description": "Uzbekistan som" }, { "name": "VEF", "description": "Venezuelan bolívar soberano" }, { "name": "VND", "description": "Vietnamese ’Óng" }, { "name": "VUV", "description": "Vanuatu vatu" }, { "name": "WST", "description": "Samoan tala" }, { "name": "XAF", "description": "CFA franc BEAC" }, { "name": "XAG", "description": "Silver" }, { "name": "XAU", "description": "Gold" }, { "name": "XBA", "description": "European Composite Unit" }, { "name": "XBB", "description": "European Monetary Unit" }, { "name": "XBC", "description": "European Unit of Account 9" }, { "name": "XBD", "description": "European Unit of Account 17" }, { "name": "XCD", "description": "East Caribbean dollar" }, { "name": "XDR", "description": "Special drawing rights (International Monetary Fund)" }, { "name": "XOF", "description": "CFA franc BCEAO" }, { "name": "XPD", "description": "Palladium" }, { "name": "XPF", "description": "CFP franc" }, { "name": "XPT", "description": "Platinum" }, { "name": "XTS", "description": "Code reserved for testing" }, { "name": "XXX", "description": "No currency" }, { "name": "YER", "description": "Yemeni rial" }, { "name": "ZAR", "description": "South African rand" }, { "name": "ZMK", "description": "Zambian kwacha" }, { "name": "ZMW", "description": "Zambian kwacha" }, { "name": "BTC", "description": "Bitcoin" }, { "name": "XUS", "description": "USD Coin" } ], "description": "Indicates the associated currency for an amount of money. Values correspond\nto [ISO 4217](https://wikipedia.org/wiki/ISO_4217).", "x-release-status": "PUBLIC" }, "Error": { "type": "object", "description": "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.", "x-release-status": "PUBLIC", "required": [ "category", "code" ], "properties": { "category": { "$ref": "#/$defs/ErrorCategory", "description": "The high-level category for the error.\nSee [ErrorCategory](#type-errorcategory) for possible values" }, "code": { "$ref": "#/$defs/ErrorCode", "description": "The specific code of the error.\nSee [ErrorCode](#type-errorcode) for possible values" }, "detail": { "type": "string", "description": "A human-readable description of the error for debugging purposes." }, "field": { "type": "string", "description": "The name of the field provided in the original request (if any) that\nthe error pertains to." } } }, "ErrorCategory": { "type": "string", "enum": [ "API_ERROR", "AUTHENTICATION_ERROR", "INVALID_REQUEST_ERROR", "RATE_LIMIT_ERROR", "PAYMENT_METHOD_ERROR", "REFUND_ERROR", "MERCHANT_SUBSCRIPTION_ERROR", "EXTERNAL_VENDOR_ERROR" ], "x-enum-elements": [ { "name": "API_ERROR", "description": "An error occurred with the Connect API itself." }, { "name": "AUTHENTICATION_ERROR", "description": "An authentication error occurred. Most commonly, the request had\na missing, malformed, or otherwise invalid `Authorization` header." }, { "name": "INVALID_REQUEST_ERROR", "description": "The request was invalid. Most commonly, a required parameter was\nmissing, or a provided parameter had an invalid value." }, { "name": "RATE_LIMIT_ERROR", "description": "Your application reached the Square API rate limit. You might receive this error if your application sends a high number of requests\nto Square APIs in a short period of time.\n\nYour application should monitor responses for `429 RATE_LIMITED` errors and use a retry mechanism with an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)\nschedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule." }, { "name": "PAYMENT_METHOD_ERROR", "description": "An error occurred while processing a payment method. Most commonly,\nthe details of the payment method were invalid (such as a card's CVV\nor expiration date)." }, { "name": "REFUND_ERROR", "description": "An error occurred while attempting to process a refund." }, { "name": "MERCHANT_SUBSCRIPTION_ERROR", "description": "An error occurred when checking a merchant subscription status" }, { "name": "EXTERNAL_VENDOR_ERROR", "description": "An error that is returned from an external vendor's API" } ], "description": "Indicates which high-level category of error has occurred during a\nrequest to the Connect API.", "x-release-status": "PUBLIC" }, "ErrorCode": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "UNAUTHORIZED", "ACCESS_TOKEN_EXPIRED", "ACCESS_TOKEN_REVOKED", "CLIENT_DISABLED", "FORBIDDEN", "INSUFFICIENT_SCOPES", "APPLICATION_DISABLED", "V1_APPLICATION", "V1_ACCESS_TOKEN", "CARD_PROCESSING_NOT_ENABLED", "MERCHANT_SUBSCRIPTION_NOT_FOUND", "BAD_REQUEST", "MISSING_REQUIRED_PARAMETER", "INCORRECT_TYPE", "INVALID_TIME", "INVALID_TIME_RANGE", "INVALID_VALUE", "INVALID_CURSOR", "UNKNOWN_QUERY_PARAMETER", "CONFLICTING_PARAMETERS", "EXPECTED_JSON_BODY", "INVALID_SORT_ORDER", "VALUE_REGEX_MISMATCH", "VALUE_TOO_SHORT", "VALUE_TOO_LONG", "VALUE_TOO_LOW", "VALUE_TOO_HIGH", "VALUE_EMPTY", "ARRAY_LENGTH_TOO_LONG", "ARRAY_LENGTH_TOO_SHORT", "ARRAY_EMPTY", "EXPECTED_BOOLEAN", "EXPECTED_INTEGER", "EXPECTED_FLOAT", "EXPECTED_STRING", "EXPECTED_OBJECT", "EXPECTED_ARRAY", "EXPECTED_MAP", "EXPECTED_BASE64_ENCODED_BYTE_ARRAY", "INVALID_ARRAY_VALUE", "INVALID_ENUM_VALUE", "INVALID_CONTENT_TYPE", "INVALID_FORM_VALUE", "CUSTOMER_NOT_FOUND", "ONE_INSTRUMENT_EXPECTED", "NO_FIELDS_SET", "TOO_MANY_MAP_ENTRIES", "MAP_KEY_LENGTH_TOO_SHORT", "MAP_KEY_LENGTH_TOO_LONG", "CUSTOMER_MISSING_NAME", "CUSTOMER_MISSING_EMAIL", "INVALID_PAUSE_LENGTH", "INVALID_DATE", "UNSUPPORTED_COUNTRY", "UNSUPPORTED_CURRENCY", "APPLE_TTP_PIN_TOKEN", "CARD_EXPIRED", "INVALID_EXPIRATION", "INVALID_EXPIRATION_YEAR", "INVALID_EXPIRATION_DATE", "UNSUPPORTED_CARD_BRAND", "UNSUPPORTED_ENTRY_METHOD", "INVALID_ENCRYPTED_CARD", "INVALID_CARD", "PAYMENT_AMOUNT_MISMATCH", "GENERIC_DECLINE", "CVV_FAILURE", "ADDRESS_VERIFICATION_FAILURE", "INVALID_ACCOUNT", "CURRENCY_MISMATCH", "INSUFFICIENT_FUNDS", "INSUFFICIENT_PERMISSIONS", "CARDHOLDER_INSUFFICIENT_PERMISSIONS", "INVALID_LOCATION", "TRANSACTION_LIMIT", "VOICE_FAILURE", "PAN_FAILURE", "EXPIRATION_FAILURE", "CARD_NOT_SUPPORTED", "INVALID_PIN", "MISSING_PIN", "MISSING_ACCOUNT_TYPE", "INVALID_POSTAL_CODE", "INVALID_FEES", "MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED", "PAYMENT_LIMIT_EXCEEDED", "GIFT_CARD_AVAILABLE_AMOUNT", "ACCOUNT_UNUSABLE", "BUYER_REFUSED_PAYMENT", "DELAYED_TRANSACTION_EXPIRED", "DELAYED_TRANSACTION_CANCELED", "DELAYED_TRANSACTION_CAPTURED", "DELAYED_TRANSACTION_FAILED", "CARD_TOKEN_EXPIRED", "CARD_TOKEN_USED", "AMOUNT_TOO_HIGH", "UNSUPPORTED_INSTRUMENT_TYPE", "REFUND_AMOUNT_INVALID", "REFUND_ALREADY_PENDING", "PAYMENT_NOT_REFUNDABLE", "PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE", "REFUND_DECLINED", "INSUFFICIENT_PERMISSIONS_FOR_REFUND", "INVALID_CARD_DATA", "SOURCE_USED", "SOURCE_EXPIRED", "UNSUPPORTED_LOYALTY_REWARD_TIER", "LOCATION_MISMATCH", "IDEMPOTENCY_KEY_REUSED", "UNEXPECTED_VALUE", "SANDBOX_NOT_SUPPORTED", "INVALID_EMAIL_ADDRESS", "INVALID_PHONE_NUMBER", "CHECKOUT_EXPIRED", "BAD_CERTIFICATE", "INVALID_SQUARE_VERSION_FORMAT", "API_VERSION_INCOMPATIBLE", "CARD_PRESENCE_REQUIRED", "UNSUPPORTED_SOURCE_TYPE", "CARD_MISMATCH", "PLAID_ERROR", "PLAID_ERROR_ITEM_LOGIN_REQUIRED", "PLAID_ERROR_RATE_LIMIT", "CARD_DECLINED", "VERIFY_CVV_FAILURE", "VERIFY_AVS_FAILURE", "CARD_DECLINED_CALL_ISSUER", "CARD_DECLINED_VERIFICATION_REQUIRED", "BAD_EXPIRATION", "CHIP_INSERTION_REQUIRED", "ALLOWABLE_PIN_TRIES_EXCEEDED", "RESERVATION_DECLINED", "UNKNOWN_BODY_PARAMETER", "NOT_FOUND", "APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND", "METHOD_NOT_ALLOWED", "NOT_ACCEPTABLE", "REQUEST_TIMEOUT", "CONFLICT", "GONE", "REQUEST_ENTITY_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "UNPROCESSABLE_ENTITY", "RATE_LIMITED", "NOT_IMPLEMENTED", "BAD_GATEWAY", "SERVICE_UNAVAILABLE", "TEMPORARY_ERROR", "GATEWAY_TIMEOUT" ], "x-enum-elements": [ { "name": "INTERNAL_SERVER_ERROR", "description": "A general server error occurred.", "error-category": "API_ERROR" }, { "name": "UNAUTHORIZED", "description": "A general authorization error occurred.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "ACCESS_TOKEN_EXPIRED", "description": "The provided access token has expired.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "ACCESS_TOKEN_REVOKED", "description": "The provided access token has been revoked.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "CLIENT_DISABLED", "description": "The provided client has been disabled.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "FORBIDDEN", "description": "A general access error occurred.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "INSUFFICIENT_SCOPES", "description": "The provided access token does not have permission\nto execute the requested action.", "error-category": "AUTHENTICATION_ERROR" }, { "name": "APPLICATION_DISABLED", "description": "The calling application was disabled.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "V1_APPLICATION", "description": "The calling application was created prior to\n2016-03-30 and is not compatible with v2 Square API calls.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "V1_ACCESS_TOKEN", "description": "The calling application is using an access token\ncreated prior to 2016-03-30 and is not compatible with v2 Square API\ncalls.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_PROCESSING_NOT_ENABLED", "description": "The location provided in the API call is not\nenabled for credit card processing.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MERCHANT_SUBSCRIPTION_NOT_FOUND", "description": "A required subscription was not found for the merchant", "error-category": "MERCHANT_SUBSCRIPTION_ERROR" }, { "name": "BAD_REQUEST", "description": "A general error occurred with the request.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MISSING_REQUIRED_PARAMETER", "description": "The request is missing a required path, query, or\nbody parameter.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INCORRECT_TYPE", "description": "The value provided in the request is the wrong\ntype. For example, a string instead of an integer.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_TIME", "description": "Formatting for the provided time value is\nincorrect.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_TIME_RANGE", "description": "The time range provided in the request is invalid.\nFor example, the end time is before the start time.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_VALUE", "description": "The provided value is invalid. For example,\nincluding `%` in a phone number.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_CURSOR", "description": "The pagination cursor included in the request is\ninvalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNKNOWN_QUERY_PARAMETER", "description": "The query parameters provided is invalid for the\nrequested endpoint.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CONFLICTING_PARAMETERS", "description": "One or more of the request parameters conflict with\neach other.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_JSON_BODY", "description": "The request body is not a JSON object.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_SORT_ORDER", "description": "The provided sort order is not a valid key.\nCurrently, sort order must be `ASC` or `DESC`.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_REGEX_MISMATCH", "description": "The provided value does not match an expected\nregular expression.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_SHORT", "description": "The provided string value is shorter than the\nminimum length allowed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_LONG", "description": "The provided string value is longer than the\nmaximum length allowed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_LOW", "description": "The provided value is less than the supported\nminimum.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_TOO_HIGH", "description": "The provided value is greater than the supported\nmaximum.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "VALUE_EMPTY", "description": "The provided value has a default (empty) value\nsuch as a blank string.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_LENGTH_TOO_LONG", "description": "The provided array has too many elements.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_LENGTH_TOO_SHORT", "description": "The provided array has too few elements.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ARRAY_EMPTY", "description": "The provided array is empty.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_BOOLEAN", "description": "The endpoint expected the provided value to be a\nboolean.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_INTEGER", "description": "The endpoint expected the provided value to be an\ninteger.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_FLOAT", "description": "The endpoint expected the provided value to be a\nfloat.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_STRING", "description": "The endpoint expected the provided value to be a\nstring.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_OBJECT", "description": "The endpoint expected the provided value to be a\nJSON object.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_ARRAY", "description": "The endpoint expected the provided value to be an\narray or list.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_MAP", "description": "The endpoint expected the provided value to be a\nmap or associative array.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "EXPECTED_BASE64_ENCODED_BYTE_ARRAY", "description": "The endpoint expected the provided value to be an\narray encoded in base64.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_ARRAY_VALUE", "description": "One or more objects in the array does not match the\narray type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_ENUM_VALUE", "description": "The provided static string is not valid for the\nfield.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_CONTENT_TYPE", "description": "Invalid content type header.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_FORM_VALUE", "description": "Only relevant for applications created prior to\n2016-03-30. Indicates there was an error while parsing form values.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_NOT_FOUND", "description": "The provided customer id can't be found in the merchant's customers list.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "ONE_INSTRUMENT_EXPECTED", "description": "A general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NO_FIELDS_SET", "description": "A general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "TOO_MANY_MAP_ENTRIES", "description": "Too many entries in the map field.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MAP_KEY_LENGTH_TOO_SHORT", "description": "The length of one of the provided keys in the map is too short.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "MAP_KEY_LENGTH_TOO_LONG", "description": "The length of one of the provided keys in the map is too long.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_MISSING_NAME", "description": "The provided customer does not have a recorded name.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CUSTOMER_MISSING_EMAIL", "description": "The provided customer does not have a recorded email.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_PAUSE_LENGTH", "description": "The subscription cannot be paused longer than the duration of the current phase.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_DATE", "description": "The subscription cannot be paused/resumed on the given date.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_COUNTRY", "description": "The API request references an unsupported country.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_CURRENCY", "description": "The API request references an unsupported currency.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "APPLE_TTP_PIN_TOKEN", "description": "The payment was declined by the card issuer during an Apple Tap to Pay (TTP)\ntransaction with a request for the card's PIN. This code will be returned alongside\n`CARD_DECLINED_VERIFICATION_REQUIRED` as a supplemental error, and will include an\nissuer-provided token in the `details` field that is needed to initiate the PIN\ncollection flow on the iOS device.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_EXPIRED", "description": "The card issuer declined the request because the card is expired.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_EXPIRATION", "description": "The expiration date for the payment card is invalid. For example,\nit indicates a date in the past.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_EXPIRATION_YEAR", "description": "The expiration year for the payment card is invalid. For example,\nit indicates a year in the past or contains invalid characters.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_EXPIRATION_DATE", "description": "The expiration date for the payment card is invalid. For example,\nit contains invalid characters.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_CARD_BRAND", "description": "The credit card provided is not from a supported issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "UNSUPPORTED_ENTRY_METHOD", "description": "The entry method for the credit card (swipe, dip, tap) is not supported.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_ENCRYPTED_CARD", "description": "The encrypted card information is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_CARD", "description": "The credit card cannot be validated based on the provided details.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAYMENT_AMOUNT_MISMATCH", "description": "The payment was declined because there was a payment amount mismatch.\nThe money amount Square was expecting does not match the amount provided.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GENERIC_DECLINE", "description": "Square received a decline without any additional information.\nIf the payment information seems correct, the buyer can contact their\nissuer to ask for more information.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CVV_FAILURE", "description": "The card issuer declined the request because the CVV value is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ADDRESS_VERIFICATION_FAILURE", "description": "The card issuer declined the request because the postal code is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_ACCOUNT", "description": "The issuer was not able to locate the account on record.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CURRENCY_MISMATCH", "description": "The currency associated with the payment is not valid for the provided\nfunding source. For example, a gift card funded in USD cannot be used to process\npayments in GBP.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INSUFFICIENT_FUNDS", "description": "The funding source has insufficient funds to cover the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INSUFFICIENT_PERMISSIONS", "description": "The Square account does not have the permissions to accept\nthis payment. For example, Square may limit which merchants are\nallowed to receive gift card payments.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARDHOLDER_INSUFFICIENT_PERMISSIONS", "description": "The card issuer has declined the transaction due to restrictions on where the card can be used.\nFor example, a gift card is limited to a single merchant.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_LOCATION", "description": "The Square account cannot take payments in the specified region.\nA Square account can take payments only from the region where the account was created.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "TRANSACTION_LIMIT", "description": "The card issuer has determined the payment amount is either too high or too low.\nThe API returns the error code mostly for credit cards (for example, the card reached\nthe credit limit). However, sometimes the issuer bank can indicate the error for debit\nor prepaid cards (for example, card has insufficient funds).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VOICE_FAILURE", "description": "The card issuer declined the request because the issuer requires voice authorization from the cardholder. The seller should ask the customer to contact the card issuing bank to authorize the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAN_FAILURE", "description": "The specified card number is invalid. For example, it is of\nincorrect length or is incorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "EXPIRATION_FAILURE", "description": "The card expiration date is either invalid or indicates that the\ncard is expired.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_NOT_SUPPORTED", "description": "The card is not supported either in the geographic region or by\nthe [merchant category code](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code) (MCC).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_PIN", "description": "The card issuer declined the request because the PIN is invalid.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MISSING_PIN", "description": "The payment is missing a required PIN.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MISSING_ACCOUNT_TYPE", "description": "The payment is missing a required ACCOUNT_TYPE parameter.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_POSTAL_CODE", "description": "The postal code is incorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "INVALID_FEES", "description": "The app_fee_money on a payment is too high.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED", "description": "The card must be swiped, tapped, or dipped. Payments attempted by manually entering the card number are declined.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "PAYMENT_LIMIT_EXCEEDED", "description": "Square declined the request because the payment amount exceeded the processing limit for this merchant.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GIFT_CARD_AVAILABLE_AMOUNT", "description": "When a Gift Card is a payment source, you can allow taking a partial payment\nby adding the `accept_partial_authorization` parameter in the request.\nHowever, taking such a partial payment does not work if your request also includes\n`tip_money`, `app_fee_money`, or both. Square declines such payments and returns\nthe `GIFT_CARD_AVAILABLE_AMOUNT` error.\nFor more information, see\n[CreatePayment errors (additional information)](https://developer.squareup.com/docs/payments-api/error-codes#createpayment-errors-additional-information).", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ACCOUNT_UNUSABLE", "description": "The account provided cannot carry out transactions.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "BUYER_REFUSED_PAYMENT", "description": "Bank account rejected or was not authorized for the payment.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "DELAYED_TRANSACTION_EXPIRED", "description": "The application tried to update a delayed-capture payment that has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_CANCELED", "description": "The application tried to cancel a delayed-capture payment that was already cancelled.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_CAPTURED", "description": "The application tried to capture a delayed-capture payment that was already captured.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "DELAYED_TRANSACTION_FAILED", "description": "The application tried to update a delayed-capture payment that failed.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_TOKEN_EXPIRED", "description": "The provided card token (nonce) has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_TOKEN_USED", "description": "The provided card token (nonce) was already used to process the payment or refund.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "AMOUNT_TOO_HIGH", "description": "The requested payment amount is too high for the provided payment source.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_INSTRUMENT_TYPE", "description": "The API request references an unsupported instrument type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REFUND_AMOUNT_INVALID", "description": "The requested refund amount exceeds the amount available to refund.", "error-category": "REFUND_ERROR" }, { "name": "REFUND_ALREADY_PENDING", "description": "The payment already has a pending refund.", "error-category": "REFUND_ERROR" }, { "name": "PAYMENT_NOT_REFUNDABLE", "description": "The payment is not refundable. For example, the payment is too old to be refunded.", "error-category": "REFUND_ERROR" }, { "name": "PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE", "description": "The payment is not refundable because it has been disputed.", "error-category": "REFUND_ERROR" }, { "name": "REFUND_DECLINED", "description": "Request failed - The card issuer declined the refund.", "error-category": "REFUND_ERROR" }, { "name": "INSUFFICIENT_PERMISSIONS_FOR_REFUND", "description": "The Square account does not have the permissions to process this refund.", "error-category": "REFUND_ERROR" }, { "name": "INVALID_CARD_DATA", "description": "Generic error - the provided card data is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SOURCE_USED", "description": "The provided source id was already used to create a card.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SOURCE_EXPIRED", "description": "The provided source id has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_LOYALTY_REWARD_TIER", "description": "The referenced loyalty program reward tier is not supported.\nThis could happen if the reward tier created in a first party\napplication is incompatible with the Loyalty API.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "LOCATION_MISMATCH", "description": "Generic error - the given location does not matching what is expected.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "IDEMPOTENCY_KEY_REUSED", "description": "The provided idempotency key has already been used.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNEXPECTED_VALUE", "description": "General error - the value provided was unexpected.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "SANDBOX_NOT_SUPPORTED", "description": "The API request is not supported in sandbox.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_EMAIL_ADDRESS", "description": "The provided email address is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_PHONE_NUMBER", "description": "The provided phone number is invalid.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CHECKOUT_EXPIRED", "description": "The provided checkout URL has expired.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "BAD_CERTIFICATE", "description": "Bad certificate.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "INVALID_SQUARE_VERSION_FORMAT", "description": "The provided Square-Version is incorrectly formatted.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "API_VERSION_INCOMPATIBLE", "description": "The provided Square-Version is incompatible with the requested action.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_PRESENCE_REQUIRED", "description": "The transaction requires that a card be present.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_SOURCE_TYPE", "description": "The API request references an unsupported source type.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CARD_MISMATCH", "description": "The provided card does not match what is expected.", "error-category": "REFUND_ERROR" }, { "name": "PLAID_ERROR", "description": "Generic plaid error", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "PLAID_ERROR_ITEM_LOGIN_REQUIRED", "description": "Plaid error - ITEM_LOGIN_REQUIRED", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "PLAID_ERROR_RATE_LIMIT", "description": "Plaid error - RATE_LIMIT", "error-category": "EXTERNAL_VENDOR_ERROR" }, { "name": "CARD_DECLINED", "description": "The card was declined.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VERIFY_CVV_FAILURE", "description": "The CVV could not be verified.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "VERIFY_AVS_FAILURE", "description": "The AVS could not be verified.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_DECLINED_CALL_ISSUER", "description": "The payment card was declined with a request\nfor the card holder to call the issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CARD_DECLINED_VERIFICATION_REQUIRED", "description": "The payment card was declined with a request\nfor additional verification.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "BAD_EXPIRATION", "description": "The card expiration date is either missing or\nincorrectly formatted.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "CHIP_INSERTION_REQUIRED", "description": "The card issuer requires that the card be read\nusing a chip reader.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "ALLOWABLE_PIN_TRIES_EXCEEDED", "description": "The card has exhausted its available pin entry\nretries set by the card issuer. Resolving the error typically requires the\ncard holder to contact the card issuer.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "RESERVATION_DECLINED", "description": "The card issuer declined the refund.", "error-category": "REFUND_ERROR" }, { "name": "UNKNOWN_BODY_PARAMETER", "description": "The body parameter is not recognized by the requested endpoint.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NOT_FOUND", "description": "Not Found - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND", "description": "Square could not find the associated Apple Pay certificate.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "METHOD_NOT_ALLOWED", "description": "Method Not Allowed - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "NOT_ACCEPTABLE", "description": "Not Acceptable - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REQUEST_TIMEOUT", "description": "Request Timeout - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "CONFLICT", "description": "Conflict - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "GONE", "description": "The target resource is no longer available and this\ncondition is likely to be permanent.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "REQUEST_ENTITY_TOO_LARGE", "description": "Request Entity Too Large - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNSUPPORTED_MEDIA_TYPE", "description": "Unsupported Media Type - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "UNPROCESSABLE_ENTITY", "description": "Unprocessable Entity - a general error occurred.", "error-category": "INVALID_REQUEST_ERROR" }, { "name": "RATE_LIMITED", "description": "Rate Limited - a general error occurred.", "error-category": "RATE_LIMIT_ERROR" }, { "name": "NOT_IMPLEMENTED", "description": "Not Implemented - a general error occurred.", "error-category": "API_ERROR" }, { "name": "BAD_GATEWAY", "description": "Bad Gateway - a general error occurred.", "error-category": "API_ERROR" }, { "name": "SERVICE_UNAVAILABLE", "description": "Service Unavailable - a general error occurred.", "error-category": "API_ERROR" }, { "name": "TEMPORARY_ERROR", "description": "A temporary internal error occurred. You can safely retry your call\nusing the same idempotency key.", "error-category": "PAYMENT_METHOD_ERROR" }, { "name": "GATEWAY_TIMEOUT", "description": "Gateway Timeout - a general error occurred.", "error-category": "API_ERROR" } ], "description": "Indicates the specific error that occurred during a request to a\nSquare API.", "x-release-status": "PUBLIC" }, "Money": { "type": "object", "description": "Represents an amount of money. `Money` fields can be signed or unsigned.\nFields that do not explicitly define whether they are signed or unsigned are\nconsidered unsigned and can only hold positive amounts. For signed fields, the\nsign of the value indicates the purpose of the money transfer. See\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)\nfor more information.", "x-release-status": "PUBLIC", "properties": { "amount": { "type": [ "integer", "null" ], "description": "The amount of money, in the smallest denomination of the currency\nindicated by `currency`. For example, when `currency` is `USD`, `amount` is\nin cents. Monetary amounts can be positive or negative. See the specific\nfield description to determine the meaning of the sign in a particular case.", "format": "int64" }, "currency": { "$ref": "#/$defs/Currency", "description": "The type of currency, in __ISO 4217 format__. For example, the currency\ncode for US dollars is `USD`.\n\nSee [Currency](entity:Currency) for possible values.\nSee [Currency](#type-currency) for possible values" } } }, "PaymentBalanceActivityAppFeeRefundDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "refund_id": { "type": [ "string", "null" ], "description": "The ID of the refund associated with this activity." }, "location_id": { "type": [ "string", "null" ], "description": "The ID of the location of the merchant associated with the payment refund activity" } } }, "PaymentBalanceActivityAppFeeRevenueDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "location_id": { "type": [ "string", "null" ], "description": "The ID of the location of the merchant associated with the payment activity" } } }, "PaymentBalanceActivityAutomaticSavingsDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "payout_id": { "type": [ "string", "null" ], "description": "The ID of the payout associated with this activity." } } }, "PaymentBalanceActivityAutomaticSavingsReversedDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "payout_id": { "type": [ "string", "null" ], "description": "The ID of the payout associated with this activity." } } }, "PaymentBalanceActivityChargeDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityDepositFeeDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payout_id": { "type": [ "string", "null" ], "description": "The ID of the payout that triggered this deposit fee activity." } } }, "PaymentBalanceActivityDepositFeeReversedDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payout_id": { "type": [ "string", "null" ], "description": "The ID of the payout that triggered this deposit fee activity." } } }, "PaymentBalanceActivityDisputeDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "dispute_id": { "type": [ "string", "null" ], "description": "The ID of the dispute associated with this activity." } } }, "PaymentBalanceActivityFeeDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity\nThis will only be populated when a principal LedgerEntryToken is also populated.\nIf the fee is independent (there is no principal LedgerEntryToken) then this will likely not\nbe populated." } } }, "PaymentBalanceActivityFreeProcessingDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityHoldAdjustmentDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityOpenDisputeDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "dispute_id": { "type": [ "string", "null" ], "description": "The ID of the dispute associated with this activity." } } }, "PaymentBalanceActivityOtherAdjustmentDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityOtherDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityRefundDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "refund_id": { "type": [ "string", "null" ], "description": "The ID of the refund associated with this activity." } } }, "PaymentBalanceActivityReleaseAdjustmentDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityReserveHoldDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityReserveReleaseDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivitySquareCapitalPaymentDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivitySquareCapitalReversedPaymentDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivitySquarePayrollTransferDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivitySquarePayrollTransferReversedDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityTaxOnFeeDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "tax_rate_description": { "type": [ "string", "null" ], "description": "The description of the tax rate being applied. For example: \"GST\", \"HST\"." } } }, "PaymentBalanceActivityThirdPartyFeeDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." } } }, "PaymentBalanceActivityThirdPartyFeeRefundDetail": { "type": "object", "x-release-status": "PUBLIC", "properties": { "payment_id": { "type": [ "string", "null" ], "description": "The ID of the payment associated with this activity." }, "refund_id": { "type": [ "string", "null" ], "description": "The public refund id associated with this activity." } } }, "PayoutEntry": { "type": "object", "description": "One or more PayoutEntries that make up a Payout. Each one has a date, amount, and type of activity.\nThe total amount of the payout will equal the sum of the payout entries for a batch payout", "x-release-status": "PUBLIC", "required": [ "id", "payout_id" ], "properties": { "id": { "type": "string", "description": "A unique ID for the payout entry.", "minLength": 1 }, "payout_id": { "type": "string", "description": "The ID of the payout entries’ associated payout.", "minLength": 1 }, "effective_at": { "type": [ "string", "null" ], "description": "The timestamp of when the payout entry affected the balance, in RFC 3339 format." }, "type": { "$ref": "#/$defs/ActivityType", "description": "The type of activity associated with this payout entry.\nSee [ActivityType](#type-activitytype) for possible values" }, "gross_amount_money": { "$ref": "#/$defs/Money", "description": "The amount of money involved in this payout entry." }, "fee_amount_money": { "$ref": "#/$defs/Money", "description": "The amount of Square fees associated with this payout entry." }, "net_amount_money": { "$ref": "#/$defs/Money", "description": "The net proceeds from this transaction after any fees." }, "type_app_fee_revenue_details": { "$ref": "#/$defs/PaymentBalanceActivityAppFeeRevenueDetail", "description": "Details of any developer app fee revenue generated on a payment." }, "type_app_fee_refund_details": { "$ref": "#/$defs/PaymentBalanceActivityAppFeeRefundDetail", "description": "Details of a refund for an app fee on a payment." }, "type_automatic_savings_details": { "$ref": "#/$defs/PaymentBalanceActivityAutomaticSavingsDetail", "description": "Details of any automatic transfer from the payment processing balance to the Square Savings account. These are, generally, proportional to the merchant's sales." }, "type_automatic_savings_reversed_details": { "$ref": "#/$defs/PaymentBalanceActivityAutomaticSavingsReversedDetail", "description": "Details of any automatic transfer from the Square Savings account back to the processing balance. These are, generally, proportional to the merchant's refunds." }, "type_charge_details": { "$ref": "#/$defs/PaymentBalanceActivityChargeDetail", "description": "Details of credit card payment captures." }, "type_deposit_fee_details": { "$ref": "#/$defs/PaymentBalanceActivityDepositFeeDetail", "description": "Details of any fees involved with deposits such as for instant deposits." }, "type_deposit_fee_reversed_details": { "$ref": "#/$defs/PaymentBalanceActivityDepositFeeReversedDetail", "description": "Details of any reversal or refund of fees involved with deposits such as for instant deposits." }, "type_dispute_details": { "$ref": "#/$defs/PaymentBalanceActivityDisputeDetail", "description": "Details of any balance change due to a dispute event." }, "type_fee_details": { "$ref": "#/$defs/PaymentBalanceActivityFeeDetail", "description": "Details of adjustments due to the Square processing fee." }, "type_free_processing_details": { "$ref": "#/$defs/PaymentBalanceActivityFreeProcessingDetail", "description": "Square offers Free Payments Processing for a variety of business scenarios including seller referral or when Square wants to apologize for a bug, customer service, repricing complication, and so on. This entry represents details of any credit to the merchant for the purposes of Free Processing." }, "type_hold_adjustment_details": { "$ref": "#/$defs/PaymentBalanceActivityHoldAdjustmentDetail", "description": "Details of any adjustment made by Square related to the holding or releasing of a payment." }, "type_open_dispute_details": { "$ref": "#/$defs/PaymentBalanceActivityOpenDisputeDetail", "description": "Details of any open disputes." }, "type_other_details": { "$ref": "#/$defs/PaymentBalanceActivityOtherDetail", "description": "Details of any other type that does not belong in the rest of the types." }, "type_other_adjustment_details": { "$ref": "#/$defs/PaymentBalanceActivityOtherAdjustmentDetail", "description": "Details of any other type of adjustments that don't fall under existing types." }, "type_refund_details": { "$ref": "#/$defs/PaymentBalanceActivityRefundDetail", "description": "Details of a refund for an existing card payment." }, "type_release_adjustment_details": { "$ref": "#/$defs/PaymentBalanceActivityReleaseAdjustmentDetail", "description": "Details of fees released for adjustments." }, "type_reserve_hold_details": { "$ref": "#/$defs/PaymentBalanceActivityReserveHoldDetail", "description": "Details of fees paid for funding risk reserve." }, "type_reserve_release_details": { "$ref": "#/$defs/PaymentBalanceActivityReserveReleaseDetail", "description": "Details of fees released from risk reserve." }, "type_square_capital_payment_details": { "$ref": "#/$defs/PaymentBalanceActivitySquareCapitalPaymentDetail", "description": "Details of capital merchant cash advance (MCA) assessments. These are, generally, proportional to the merchant's sales but may be issued for other reasons related to the MCA." }, "type_square_capital_reversed_payment_details": { "$ref": "#/$defs/PaymentBalanceActivitySquareCapitalReversedPaymentDetail", "description": "Details of capital merchant cash advance (MCA) assessment refunds. These are, generally, proportional to the merchant's refunds but may be issued for other reasons related to the MCA." }, "type_tax_on_fee_details": { "$ref": "#/$defs/PaymentBalanceActivityTaxOnFeeDetail", "description": "Details of tax paid on fee amounts." }, "type_third_party_fee_details": { "$ref": "#/$defs/PaymentBalanceActivityThirdPartyFeeDetail", "description": "Details of fees collected by a 3rd party platform." }, "type_third_party_fee_refund_details": { "$ref": "#/$defs/PaymentBalanceActivityThirdPartyFeeRefundDetail", "description": "Details of refunded fees from a 3rd party platform." }, "type_square_payroll_transfer_details": { "$ref": "#/$defs/PaymentBalanceActivitySquarePayrollTransferDetail", "description": "Details of a payroll payment that was transferred to a team member’s bank account." }, "type_square_payroll_transfer_reversed_details": { "$ref": "#/$defs/PaymentBalanceActivitySquarePayrollTransferReversedDetail", "description": "Details of a payroll payment to a team member’s bank account that was deposited back to the seller’s account by Square." } } } } }