openapi: 3.0.0 info: version: '2.0' title: Square ApplePay Payments API description: 'Supercharge Square for sellers of every size. Our entire connected commerce platform from elegant hardware to a rich suite of Square APIs is yours to build with. Whether youre developing an app or composing a bespoke solution, this is the place to make it happen. ' termsOfService: https://connect.squareup.com/tos contact: name: Square Developer Platform email: developers@squareup.com url: https://squareup.com/developers license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html externalDocs: description: 'Read the official documentation here:' url: https://docs.connect.squareup.com/ x-server-configuration: default-environment: production default-server: default environments: - name: production servers: - name: default url: https://connect.squareup.com - name: sandbox servers: - name: default url: https://connect.squareupsandbox.com - name: custom servers: - name: default url: '{custom_url}' parameters: - name: custom_url description: Sets the base URL requests are made to. Defaults to `https://connect.squareup.com` type: string example: https://connect.squareup.com x-square-generic-error-codes: - ACCESS_TOKEN_EXPIRED - ACCESS_TOKEN_REVOKED - API_VERSION_INCOMPATIBLE - APPLICATION_DISABLED - ARRAY_EMPTY - ARRAY_LENGTH_TOO_LONG - ARRAY_LENGTH_TOO_SHORT - BAD_CERTIFICATE - BAD_GATEWAY - BAD_REQUEST - CONFLICT - CONFLICTING_PARAMETERS - CURRENCY_MISMATCH - EXPECTED_ARRAY - EXPECTED_BASE64_ENCODED_BYTE_ARRAY - EXPECTED_BOOLEAN - EXPECTED_FLOAT - EXPECTED_INTEGER - EXPECTED_JSON_BODY - EXPECTED_MAP - EXPECTED_OBJECT - EXPECTED_STRING - FORBIDDEN - GATEWAY_TIMEOUT - GONE - IDEMPOTENCY_KEY_REUSED - INCORRECT_TYPE - INSUFFICIENT_SCOPES - INTERNAL_SERVER_ERROR - INVALID_ARRAY_VALUE - INVALID_CONTENT_TYPE - INVALID_CURSOR - INVALID_ENUM_VALUE - INVALID_FORM_VALUE - INVALID_SORT_ORDER - INVALID_SQUARE_VERSION_FORMAT - INVALID_TIME - INVALID_TIME_RANGE - INVALID_VALUE - LOCATION_MISMATCH - MAP_KEY_LENGTH_TOO_LONG - MAP_KEY_LENGTH_TOO_SHORT - MERCHANT_SUBSCRIPTION_NOT_FOUND - METHOD_NOT_ALLOWED - MISSING_REQUIRED_PARAMETER - NOT_ACCEPTABLE - NOT_FOUND - NOT_IMPLEMENTED - NO_FIELDS_SET - RATE_LIMITED - REQUEST_ENTITY_TOO_LARGE - REQUEST_TIMEOUT - SANDBOX_NOT_SUPPORTED - SERVICE_UNAVAILABLE - TOO_MANY_MAP_ENTRIES - UNAUTHORIZED - UNEXPECTED_VALUE - UNKNOWN_BODY_PARAMETER - UNKNOWN_QUERY_PARAMETER - UNPROCESSABLE_ENTITY - UNSUPPORTED_MEDIA_TYPE - V1_ACCESS_TOKEN - V1_APPLICATION - VALUE_EMPTY - VALUE_REGEX_MISMATCH - VALUE_TOO_HIGH - VALUE_TOO_LONG - VALUE_TOO_LOW - VALUE_TOO_SHORT servers: - url: https://connect.squareup.com variables: {} tags: - name: Payments paths: /v2/payments: get: tags: - Payments summary: Square List Payments operationId: ListPayments x-microcks-operation: delay: 0 dispatcher: FALLBACK description: 'Retrieves a list of payments taken by the account making the request. Results are eventually consistent, and new payments or changes to payments might take several seconds to appear. The maximum results per page is 100.' x-release-status: PUBLIC security: - oauth2: - PAYMENTS_READ parameters: - name: begin_time description: "Indicates the start of the time range to retrieve payments for, in RFC 3339 format. \nThe range is determined using the `created_at` field for each Payment.\nInclusive. Default: The current time minus one year." schema: type: string in: query required: false - name: end_time description: "Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The \nrange is determined using the `created_at` field for each Payment.\n\nDefault: The current time." schema: type: string in: query required: false - name: sort_order description: 'The order in which results are listed by `ListPaymentsRequest.sort_field`: - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default).' schema: type: string in: query required: false - name: cursor description: '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](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).' schema: type: string in: query required: false - name: location_id description: 'Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller.' schema: type: string in: query required: false - name: total description: The exact amount in the `total_money` for a payment. schema: type: integer format: int64 in: query required: false - name: last_4 description: The last four digits of a payment card. schema: type: string in: query required: false - name: card_brand description: The brand of the payment card (for example, VISA). schema: type: string in: query required: false - name: limit description: "The maximum number of results to be returned in a single page.\nIt is possible to receive fewer results than the specified limit on a given page.\n\nThe default value of 100 is also the maximum allowed value. If the provided value is \ngreater than 100, it is ignored and the default value is used instead.\n\nDefault: `100`" schema: type: integer in: query required: false - name: is_offline_payment description: Whether the payment was taken offline or not. schema: type: boolean default: false in: query required: false - name: offline_begin_time description: '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.' schema: type: string in: query required: false - name: offline_end_time description: '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.' schema: type: string in: query required: false - name: updated_at_begin_time description: '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.' schema: type: string in: query required: false - name: updated_at_end_time description: '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.' schema: type: string in: query required: false - name: sort_field description: The field used to sort results by. The default is `CREATED_AT`. schema: $ref: '#/components/schemas/PaymentSortField' in: query required: false responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListPaymentsResponse' post: tags: - Payments summary: Square Create Payment operationId: CreatePayment x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Creates a payment using the provided source. You can use this endpoint \nto charge a card (credit/debit card or \nSquare gift card) or record a payment that the seller received outside of Square \n(cash payment from a buyer or a payment that an external entity \nprocessed on behalf of the seller).\n\nThe endpoint creates a \n`Payment` object and returns it in the response." x-release-status: PUBLIC security: - oauth2: - PAYMENTS_WRITE parameters: [] requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/CreatePaymentRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CreatePaymentResponse' x-endpoint-errors: - error-code: ADDRESS_VERIFICATION_FAILURE - error-code: ALLOWABLE_PIN_TRIES_EXCEEDED - error-code: APPLE_TTP_PIN_TOKEN - error-code: BAD_EXPIRATION - error-code: CARDHOLDER_INSUFFICIENT_PERMISSIONS - error-code: CARD_DECLINED_VERIFICATION_REQUIRED - error-code: CARD_EXPIRED - error-code: CARD_NOT_SUPPORTED - error-code: CARD_PROCESSING_NOT_ENABLED - error-code: CARD_TOKEN_EXPIRED - error-code: CARD_TOKEN_USED - error-code: CHIP_INSERTION_REQUIRED - error-code: CVV_FAILURE - error-code: EXPIRATION_FAILURE - error-code: GENERIC_DECLINE - error-code: GIFT_CARD_AVAILABLE_AMOUNT - error-code: INSUFFICIENT_FUNDS - error-code: INSUFFICIENT_PERMISSIONS - error-code: INVALID_ACCOUNT - error-code: INVALID_CARD - error-code: INVALID_CARD_DATA - error-code: INVALID_EMAIL_ADDRESS - error-code: INVALID_EXPIRATION - error-code: INVALID_FEES - error-code: INVALID_LOCATION - error-code: INVALID_PHONE_NUMBER - error-code: INVALID_PIN - error-code: INVALID_POSTAL_CODE - error-code: ISSUER_INSTALLMENT_ERROR - error-code: MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED - error-code: PAN_FAILURE - error-code: PAYMENT_AMOUNT_MISMATCH - error-code: PAYMENT_LIMIT_EXCEEDED - error-code: TEMPORARY_ERROR - error-code: TRANSACTION_LIMIT - error-code: VOICE_FAILURE /v2/payments/cancel: post: tags: - Payments summary: Square Cancel Payment by Idempotency Key operationId: CancelPaymentByIdempotencyKey x-microcks-operation: delay: 0 dispatcher: FALLBACK description: 'Cancels (voids) a payment identified by the idempotency key that is specified in the request. Use this method when the status of a `CreatePayment` request is unknown (for example, after you send a `CreatePayment` request, a network error occurs and you do not get a response). In this case, you can direct Square to cancel the payment using this endpoint. In the request, you provide the same idempotency key that you provided in your `CreatePayment` request that you want to cancel. After canceling the payment, you can submit your `CreatePayment` request again. Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint returns successfully.' x-release-status: PUBLIC security: - oauth2: - PAYMENTS_WRITE parameters: [] requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/CancelPaymentByIdempotencyKeyRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CancelPaymentByIdempotencyKeyResponse' /v2/payments/{payment_id}: get: tags: - Payments summary: Square Get Payment operationId: GetPayment x-microcks-operation: delay: 0 dispatcher: FALLBACK description: Retrieves details for a specific payment. x-release-status: PUBLIC security: - oauth2: - PAYMENTS_READ parameters: - name: payment_id description: A unique ID for the desired payment. schema: type: string in: path required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/GetPaymentResponse' put: tags: - Payments summary: Square Update Payment operationId: UpdatePayment x-microcks-operation: delay: 0 dispatcher: FALLBACK description: 'Updates a payment with the APPROVED status. You can update the `amount_money` and `tip_money` using this endpoint.' x-release-status: PUBLIC security: - oauth2: - PAYMENTS_WRITE parameters: - name: payment_id description: The ID of the payment to update. schema: type: string in: path required: true requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/UpdatePaymentRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UpdatePaymentResponse' x-endpoint-errors: - error-code: AMOUNT_TOO_HIGH - error-code: CARDHOLDER_INSUFFICIENT_PERMISSIONS - error-code: CARD_DECLINED_VERIFICATION_REQUIRED - error-code: CARD_EXPIRED - error-code: CHIP_INSERTION_REQUIRED - error-code: CVV_FAILURE - error-code: GENERIC_DECLINE - error-code: INSUFFICIENT_FUNDS - error-code: INVALID_ACCOUNT - error-code: INVALID_FEES - error-code: PAN_FAILURE - error-code: PAYMENT_LIMIT_EXCEEDED - error-code: TEMPORARY_ERROR - error-code: TRANSACTION_LIMIT - error-code: VOICE_FAILURE /v2/payments/{payment_id}/cancel: post: tags: - Payments summary: Square Cancel Payment operationId: CancelPayment x-microcks-operation: delay: 0 dispatcher: FALLBACK description: "Cancels (voids) a payment. You can use this endpoint to cancel a payment with \nthe APPROVED `status`." x-release-status: PUBLIC security: - oauth2: - PAYMENTS_WRITE parameters: - name: payment_id description: The ID of the payment to cancel. schema: type: string in: path required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CancelPaymentResponse' /v2/payments/{payment_id}/complete: post: tags: - Payments summary: Square Complete Payment operationId: CompletePayment x-microcks-operation: delay: 0 dispatcher: FALLBACK description: 'Completes (captures) a payment. By default, payments are set to complete immediately after they are created. You can use this endpoint to complete a payment with the APPROVED `status`.' x-release-status: PUBLIC security: - oauth2: - PAYMENTS_WRITE parameters: - name: payment_id description: The unique ID identifying the payment to be completed. schema: type: string in: path required: true requestBody: required: true description: 'An object containing the fields to POST for the request. See the corresponding object definition for field details.' content: application/json: schema: $ref: '#/components/schemas/CompletePaymentRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompletePaymentResponse' x-endpoint-errors: - error-code: VERSION_MISMATCH components: schemas: BuyNowPayLaterDetails: type: object description: Additional details about a Buy Now Pay Later payment type. x-release-status: PUBLIC properties: brand: type: string description: 'The brand used for the Buy Now Pay Later payment. The brand can be `AFTERPAY`, `CLEARPAY` or `UNKNOWN`.' maxLength: 50 nullable: true afterpay_details: $ref: '#/components/schemas/AfterpayDetails' description: 'Details about an Afterpay payment. These details are only populated if the `brand` is `AFTERPAY`.' nullable: true clearpay_details: $ref: '#/components/schemas/ClearpayDetails' description: 'Details about a Clearpay payment. These details are only populated if the `brand` is `CLEARPAY`.' nullable: true Address: type: object description: "Represents a postal address in a country. \nFor more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)." x-release-status: PUBLIC properties: address_line_1: type: string description: 'The first line of the address. Fields that start with `address_line` provide the address''s most specific details, like street number, street name, and building name. They do *not* provide less specific details like city, state/province, or country (these details are provided in other fields).' nullable: true address_line_2: type: string description: The second line of the address, if any. nullable: true address_line_3: type: string description: The third line of the address, if any. nullable: true locality: type: string description: The city or town of the address. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). nullable: true sublocality: type: string description: A civil region within the address's `locality`, if any. nullable: true sublocality_2: type: string description: A civil region within the address's `sublocality`, if any. nullable: true sublocality_3: type: string description: A civil region within the address's `sublocality_2`, if any. nullable: true administrative_district_level_1: type: string description: 'A civil entity within the address''s country. In the US, this is the state. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).' nullable: true administrative_district_level_2: type: string description: 'A civil entity within the address''s `administrative_district_level_1`. In the US, this is the county.' nullable: true administrative_district_level_3: type: string description: 'A civil entity within the address''s `administrative_district_level_2`, if any.' nullable: true postal_code: type: string description: The address's postal code. For a full list of field meanings by country, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). nullable: true country: $ref: '#/components/schemas/Country' description: 'The address''s country, in the two-letter format of ISO 3166. For example, `US` or `FR`. See [Country](#type-country) for possible values' nullable: true first_name: type: string description: Optional first name when it's representing recipient. nullable: true last_name: type: string description: Optional last name when it's representing recipient. nullable: true Country: type: string enum: - ZZ - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW x-enum-elements: - name: ZZ description: Unknown - name: AD description: Andorra - name: AE description: United Arab Emirates - name: AF description: Afghanistan - name: AG description: Antigua and Barbuda - name: AI description: Anguilla - name: AL description: Albania - name: AM description: Armenia - name: AO description: Angola - name: AQ description: Antartica - name: AR description: Argentina - name: AS description: American Samoa - name: AT description: Austria - name: AU description: Australia - name: AW description: Aruba - name: AX description: Åland Islands - name: AZ description: Azerbaijan - name: BA description: Bosnia and Herzegovina - name: BB description: Barbados - name: BD description: Bangladesh - name: BE description: Belgium - name: BF description: Burkina Faso - name: BG description: Bulgaria - name: BH description: Bahrain - name: BI description: Burundi - name: BJ description: Benin - name: BL description: Saint Barthélemy - name: BM description: Bermuda - name: BN description: Brunei - name: BO description: Bolivia - name: BQ description: Bonaire - name: BR description: Brazil - name: BS description: Bahamas - name: BT description: Bhutan - name: BV description: Bouvet Island - name: BW description: Botswana - name: BY description: Belarus - name: BZ description: Belize - name: CA description: Canada - name: CC description: Cocos Islands - name: CD description: Democratic Republic of the Congo - name: CF description: Central African Republic - name: CG description: Congo - name: CH description: Switzerland - name: CI description: Ivory Coast - name: CK description: Cook Islands - name: CL description: Chile - name: CM description: Cameroon - name: CN description: China - name: CO description: Colombia - name: CR description: Costa Rica - name: CU description: Cuba - name: CV description: Cabo Verde - name: CW description: Curaçao - name: CX description: Christmas Island - name: CY description: Cyprus - name: CZ description: Czechia - name: DE description: Germany - name: DJ description: Djibouti - name: DK description: Denmark - name: DM description: Dominica - name: DO description: Dominican Republic - name: DZ description: Algeria - name: EC description: Ecuador - name: EE description: Estonia - name: EG description: Egypt - name: EH description: Western Sahara - name: ER description: Eritrea - name: ES description: Spain - name: ET description: Ethiopia - name: FI description: Finland - name: FJ description: Fiji - name: FK description: Falkland Islands - name: FM description: Federated States of Micronesia - name: FO description: Faroe Islands - name: FR description: France - name: GA description: Gabon - name: GB description: United Kingdom - name: GD description: Grenada - name: GE description: Georgia - name: GF description: French Guiana - name: GG description: Guernsey - name: GH description: Ghana - name: GI description: Gibraltar - name: GL description: Greenland - name: GM description: Gambia - name: GN description: Guinea - name: GP description: Guadeloupe - name: GQ description: Equatorial Guinea - name: GR description: Greece - name: GS description: South Georgia and the South Sandwich Islands - name: GT description: Guatemala - name: GU description: Guam - name: GW description: Guinea-Bissau - name: GY description: Guyana - name: HK description: Hong Kong - name: HM description: Heard Island and McDonald Islands - name: HN description: Honduras - name: HR description: Croatia - name: HT description: Haiti - name: HU description: Hungary - name: ID description: Indonesia - name: IE description: Ireland - name: IL description: Israel - name: IM description: Isle of Man - name: IN description: India - name: IO description: British Indian Ocean Territory - name: IQ description: Iraq - name: IR description: Iran - name: IS description: Iceland - name: IT description: Italy - name: JE description: Jersey - name: JM description: Jamaica - name: JO description: Jordan - name: JP description: Japan - name: KE description: Kenya - name: KG description: Kyrgyzstan - name: KH description: Cambodia - name: KI description: Kiribati - name: KM description: Comoros - name: KN description: Saint Kitts and Nevis - name: KP description: Democratic People's Republic of Korea - name: KR description: Republic of Korea - name: KW description: Kuwait - name: KY description: Cayman Islands - name: KZ description: Kazakhstan - name: LA description: Lao People's Democratic Republic - name: LB description: Lebanon - name: LC description: Saint Lucia - name: LI description: Liechtenstein - name: LK description: Sri Lanka - name: LR description: Liberia - name: LS description: Lesotho - name: LT description: Lithuania - name: LU description: Luxembourg - name: LV description: Latvia - name: LY description: Libya - name: MA description: Morocco - name: MC description: Monaco - name: MD description: Moldova - name: ME description: Montenegro - name: MF description: Saint Martin - name: MG description: Madagascar - name: MH description: Marshall Islands - name: MK description: North Macedonia - name: ML description: Mali - name: MM description: Myanmar - name: MN description: Mongolia - name: MO description: Macao - name: MP description: Northern Mariana Islands - name: MQ description: Martinique - name: MR description: Mauritania - name: MS description: Montserrat - name: MT description: Malta - name: MU description: Mauritius - name: MV description: Maldives - name: MW description: Malawi - name: MX description: Mexico - name: MY description: Malaysia - name: MZ description: Mozambique - name: NA description: Namibia - name: NC description: New Caledonia - name: NE description: Niger - name: NF description: Norfolk Island - name: NG description: Nigeria - name: NI description: Nicaragua - name: NL description: Netherlands - name: 'NO' description: Norway - name: NP description: Nepal - name: NR description: Nauru - name: NU description: Niue - name: NZ description: New Zealand - name: OM description: Oman - name: PA description: Panama - name: PE description: Peru - name: PF description: French Polynesia - name: PG description: Papua New Guinea - name: PH description: Philippines - name: PK description: Pakistan - name: PL description: Poland - name: PM description: Saint Pierre and Miquelon - name: PN description: Pitcairn - name: PR description: Puerto Rico - name: PS description: Palestine - name: PT description: Portugal - name: PW description: Palau - name: PY description: Paraguay - name: QA description: Qatar - name: RE description: Réunion - name: RO description: Romania - name: RS description: Serbia - name: RU description: Russia - name: RW description: Rwanda - name: SA description: Saudi Arabia - name: SB description: Solomon Islands - name: SC description: Seychelles - name: SD description: Sudan - name: SE description: Sweden - name: SG description: Singapore - name: SH description: Saint Helena, Ascension and Tristan da Cunha - name: SI description: Slovenia - name: SJ description: Svalbard and Jan Mayen - name: SK description: Slovakia - name: SL description: Sierra Leone - name: SM description: San Marino - name: SN description: Senegal - name: SO description: Somalia - name: SR description: Suriname - name: SS description: South Sudan - name: ST description: Sao Tome and Principe - name: SV description: El Salvador - name: SX description: Sint Maarten - name: SY description: Syrian Arab Republic - name: SZ description: Eswatini - name: TC description: Turks and Caicos Islands - name: TD description: Chad - name: TF description: French Southern Territories - name: TG description: Togo - name: TH description: Thailand - name: TJ description: Tajikistan - name: TK description: Tokelau - name: TL description: Timor-Leste - name: TM description: Turkmenistan - name: TN description: Tunisia - name: TO description: Tonga - name: TR description: Turkey - name: TT description: Trinidad and Tobago - name: TV description: Tuvalu - name: TW description: Taiwan - name: TZ description: Tanzania - name: UA description: Ukraine - name: UG description: Uganda - name: UM description: United States Minor Outlying Islands - name: US description: United States of America - name: UY description: Uruguay - name: UZ description: Uzbekistan - name: VA description: Vatican City - name: VC description: Saint Vincent and the Grenadines - name: VE description: Venezuela - name: VG description: British Virgin Islands - name: VI description: U.S. Virgin Islands - name: VN description: Vietnam - name: VU description: Vanuatu - name: WF description: Wallis and Futuna - name: WS description: Samoa - name: YE description: Yemen - name: YT description: Mayotte - name: ZA description: South Africa - name: ZM description: Zambia - name: ZW description: Zimbabwe description: 'Indicates the country associated with another entity, such as a business. Values are in [ISO 3166-1-alpha-2 format](http://www.iso.org/iso/home/standards/country_codes.htm).' x-release-status: PUBLIC CompletePaymentResponse: type: object description: Defines the response returned by[CompletePayment](api-endpoint:Payments-CompletePayment). x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. payment: $ref: '#/components/schemas/Payment' description: The successfully completed payment. example: payment: amount_money: amount: 555 currency: USD application_details: application_id: sq0ids-Pw67AZAlLVB7hsRmwlJPuA square_product: VIRTUAL_TERMINAL approved_money: amount: 555 currency: USD card_details: auth_result_code: 2Nkw7q avs_status: AVS_ACCEPTED card: bin: '411111' card_brand: VISA card_type: DEBIT exp_month: 11 exp_year: 2022 fingerprint: sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ last_4: '1111' prepaid_type: NOT_PREPAID card_payment_timeline: authorized_at: '2021-10-13T19:34:33.680Z' captured_at: '2021-10-13T19:34:34.340Z' cvv_status: CVV_ACCEPTED entry_method: KEYED statement_description: SQ *EXAMPLE TEST GOSQ.C status: CAPTURED created_at: '2021-10-13T19:34:33.524Z' delay_action: CANCEL delay_duration: PT168H delayed_until: '2021-10-20T19:34:33.524Z' employee_id: TMoK_ogh6rH1o4dV id: bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY location_id: L88917AVBK2S5 note: Test Note order_id: d7eKah653Z579f3gVtjlxpSlmUcZY processing_fee: - amount_money: amount: 34 currency: USD effective_at: '2021-10-13T21:34:35.000Z' type: INITIAL receipt_number: bP9m receipt_url: https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY source_type: CARD status: COMPLETED team_member_id: TMoK_ogh6rH1o4dV total_money: amount: 555 currency: USD updated_at: '2021-10-13T19:34:34.339Z' version_token: 56pRkL3slrzet2iQrTp9n0bdJVYTB9YEWdTNjQfZOPV6o 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 a missing, malformed, or otherwise invalid `Authorization` header.' - name: INVALID_REQUEST_ERROR description: 'The request was invalid. Most commonly, a required parameter was missing, 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 to Square APIs in a short period of time. Your 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) schedule 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, the details of the payment method were invalid (such as a card''s CVV or 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 request 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 to 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 2016-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 created prior to 2016-03-30 and is not compatible with v2 Square API calls.' error-category: INVALID_REQUEST_ERROR - name: CARD_PROCESSING_NOT_ENABLED description: 'The location provided in the API call is not enabled 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 body parameter.' error-category: INVALID_REQUEST_ERROR - name: INCORRECT_TYPE description: 'The value provided in the request is the wrong type. For example, a string instead of an integer.' error-category: INVALID_REQUEST_ERROR - name: INVALID_TIME description: 'Formatting for the provided time value is incorrect.' error-category: INVALID_REQUEST_ERROR - name: INVALID_TIME_RANGE description: 'The time range provided in the request is invalid. For 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, including `%` in a phone number.' error-category: INVALID_REQUEST_ERROR - name: INVALID_CURSOR description: 'The pagination cursor included in the request is invalid.' error-category: INVALID_REQUEST_ERROR - name: UNKNOWN_QUERY_PARAMETER description: 'The query parameters provided is invalid for the requested endpoint.' error-category: INVALID_REQUEST_ERROR - name: CONFLICTING_PARAMETERS description: 'One or more of the request parameters conflict with each 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. Currently, 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 regular expression.' error-category: INVALID_REQUEST_ERROR - name: VALUE_TOO_SHORT description: 'The provided string value is shorter than the minimum length allowed.' error-category: INVALID_REQUEST_ERROR - name: VALUE_TOO_LONG description: 'The provided string value is longer than the maximum length allowed.' error-category: INVALID_REQUEST_ERROR - name: VALUE_TOO_LOW description: 'The provided value is less than the supported minimum.' error-category: INVALID_REQUEST_ERROR - name: VALUE_TOO_HIGH description: 'The provided value is greater than the supported maximum.' error-category: INVALID_REQUEST_ERROR - name: VALUE_EMPTY description: 'The provided value has a default (empty) value such 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 boolean.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_INTEGER description: 'The endpoint expected the provided value to be an integer.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_FLOAT description: 'The endpoint expected the provided value to be a float.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_STRING description: 'The endpoint expected the provided value to be a string.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_OBJECT description: 'The endpoint expected the provided value to be a JSON object.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_ARRAY description: 'The endpoint expected the provided value to be an array or list.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_MAP description: 'The endpoint expected the provided value to be a map or associative array.' error-category: INVALID_REQUEST_ERROR - name: EXPECTED_BASE64_ENCODED_BYTE_ARRAY description: 'The endpoint expected the provided value to be an array encoded in base64.' error-category: INVALID_REQUEST_ERROR - name: INVALID_ARRAY_VALUE description: 'One or more objects in the array does not match the array type.' error-category: INVALID_REQUEST_ERROR - name: INVALID_ENUM_VALUE description: 'The provided static string is not valid for the field.' 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 2016-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) transaction with a request for the card''s PIN. This code will be returned alongside `CARD_DECLINED_VERIFICATION_REQUIRED` as a supplemental error, and will include an issuer-provided token in the `details` field that is needed to initiate the PIN collection 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, it 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, it 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, it 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. The 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. If the payment information seems correct, the buyer can contact their issuer 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 funding source. For example, a gift card funded in USD cannot be used to process payments 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 this payment. For example, Square may limit which merchants are allowed 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. For 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. A 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. The API returns the error code mostly for credit cards (for example, the card reached the credit limit). However, sometimes the issuer bank can indicate the error for debit or 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 incorrect 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 card is expired.' error-category: PAYMENT_METHOD_ERROR - name: CARD_NOT_SUPPORTED description: 'The card is not supported either in the geographic region or by the [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 by adding the `accept_partial_authorization` parameter in the request. However, taking such a partial payment does not work if your request also includes `tip_money`, `app_fee_money`, or both. Square declines such payments and returns the `GIFT_CARD_AVAILABLE_AMOUNT` error. For more information, see [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. This could happen if the reward tier created in a first party application 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 for 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 for additional verification.' error-category: PAYMENT_METHOD_ERROR - name: BAD_EXPIRATION description: 'The card expiration date is either missing or incorrectly formatted.' error-category: PAYMENT_METHOD_ERROR - name: CHIP_INSERTION_REQUIRED description: 'The card issuer requires that the card be read using a chip reader.' error-category: PAYMENT_METHOD_ERROR - name: ALLOWABLE_PIN_TRIES_EXCEEDED description: 'The card has exhausted its available pin entry retries set by the card issuer. Resolving the error typically requires the card 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 condition 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 using 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 Square API.' 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 to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).' x-release-status: PUBLIC RiskEvaluation: type: object description: 'Represents fraud risk information for the associated payment. When you take a payment through Square''s Payments API (using the `CreatePayment` endpoint), Square evaluates it and assigns a risk level to the payment. Sellers can use this information to determine the course of action (for example, provide the goods/services or refund the payment).' x-release-status: BETA required: - status properties: created_at: type: string description: The timestamp when payment risk was evaluated, in RFC 3339 format. readOnly: true risk_level: $ref: '#/components/schemas/RiskEvaluationRiskLevel' description: 'The risk level associated with the payment See [RiskEvaluationRiskLevel](#type-riskevaluationrisklevel) for possible values' nullable: true Payment: type: object description: Represents a payment processed by the Square API. x-release-status: PUBLIC properties: id: type: string description: A unique ID for the payment. maxLength: 192 readOnly: true created_at: type: string description: The timestamp of when the payment was created, in RFC 3339 format. maxLength: 32 readOnly: true updated_at: type: string description: The timestamp of when the payment was last updated, in RFC 3339 format. maxLength: 32 readOnly: true amount_money: $ref: '#/components/schemas/Money' description: 'The amount processed for this payment, not including `tip_money`. The amount is specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).' nullable: true tip_money: $ref: '#/components/schemas/Money' description: "The amount designated as a tip. \n\nThis amount is specified in the smallest denomination of the applicable currency (for example,\nUS dollar amounts are specified in cents). For more information, see\n[Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)." nullable: true total_money: $ref: '#/components/schemas/Money' description: 'The total amount for the payment, including `amount_money` and `tip_money`. This amount is specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).' readOnly: true app_fee_money: $ref: '#/components/schemas/Money' description: 'The amount the developer is taking as a fee for facilitating the payment on behalf of the seller. This amount is specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees). The amount cannot be more than 90% of the `total_money` value. To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required. For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).' nullable: true approved_money: $ref: '#/components/schemas/Money' description: 'The amount of money approved for this payment. This value may change if Square chooses to obtain reauthorization as part of a call to [UpdatePayment](api-endpoint:Payments-UpdatePayment).' nullable: true processing_fee: type: array items: $ref: '#/components/schemas/ProcessingFee' description: The processing fees and fee adjustments assessed by Square for this payment. readOnly: true refunded_money: $ref: '#/components/schemas/Money' description: "The total amount of the payment refunded to date. \n\nThis amount is specified in the smallest denomination of the applicable currency (for example,\nUS dollar amounts are specified in cents)." readOnly: true status: type: string description: Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED. maxLength: 50 readOnly: true delay_duration: type: string description: 'The duration of time after the payment''s creation when Square automatically applies the `delay_action` to the payment. This automatic `delay_action` applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the `delay_duration` time period. This field is specified as a time duration, in RFC 3339 format. Notes: This feature is only supported for card payments. Default: - Card-present payments: "PT36H" (36 hours) from the creation time. - Card-not-present payments: "P7D" (7 days) from the creation time.' readOnly: true delay_action: type: string description: 'The action to be applied to the payment when the `delay_duration` has elapsed. Current values include `CANCEL` and `COMPLETE`.' nullable: true delayed_until: type: string description: 'The read-only timestamp of when the `delay_action` is automatically applied, in RFC 3339 format. Note that this field is calculated by summing the payment''s `delay_duration` and `created_at` fields. The `created_at` field is generated by Square and might not exactly match the time on your local machine.' readOnly: true source_type: type: string description: 'The source type for this payment. Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `BUY_NOW_PAY_LATER`, `SQUARE_ACCOUNT`, `CASH` and `EXTERNAL`. For information about these payment source types, see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments).' maxLength: 50 readOnly: true card_details: $ref: '#/components/schemas/CardPaymentDetails' description: Details about a card payment. These details are only populated if the source_type is `CARD`. readOnly: true cash_details: $ref: '#/components/schemas/CashPaymentDetails' description: Details about a cash payment. These details are only populated if the source_type is `CASH`. nullable: true bank_account_details: $ref: '#/components/schemas/BankAccountPaymentDetails' description: Details about a bank account payment. These details are only populated if the source_type is `BANK_ACCOUNT`. readOnly: true external_details: $ref: '#/components/schemas/ExternalPaymentDetails' description: "Details about an external payment. The details are only populated \nif the `source_type` is `EXTERNAL`." readOnly: true wallet_details: $ref: '#/components/schemas/DigitalWalletDetails' description: "Details about an wallet payment. The details are only populated \nif the `source_type` is `WALLET`." readOnly: true buy_now_pay_later_details: $ref: '#/components/schemas/BuyNowPayLaterDetails' description: "Details about a Buy Now Pay Later payment. The details are only populated\nif the `source_type` is `BUY_NOW_PAY_LATER`. For more information, see \n[Afterpay Payments](https://developer.squareup.com/docs/payments-api/take-payments/afterpay-payments)." readOnly: true square_account_details: $ref: '#/components/schemas/SquareAccountDetails' description: 'Details about a Square Account payment. The details are only populated if the `source_type` is `SQUARE_ACCOUNT`.' readOnly: true location_id: type: string description: The ID of the location associated with the payment. maxLength: 50 readOnly: true order_id: type: string description: The ID of the order associated with the payment. maxLength: 192 readOnly: true reference_id: type: string description: 'An optional ID that associates the payment with an entity in another system.' maxLength: 40 readOnly: true customer_id: type: string description: "The ID of the customer associated with the payment. If the ID is \nnot provided in the `CreatePayment` request that was used to create the `Payment`, \nSquare may use information in the request \n(such as the billing and shipping address, email address, and payment source) \nto identify a matching customer profile in the Customer Directory. \nIf found, the profile ID is used. If a profile is not found, the \nAPI attempts to create an \n[instant profile](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles). \nIf the API cannot create an \ninstant profile (either because the seller has disabled it or the \nseller's region prevents creating it), this field remains unset. Note that \nthis process is asynchronous and it may take some time before a \ncustomer ID is added to the payment." maxLength: 191 readOnly: true employee_id: type: string description: '__Deprecated__: Use `Payment.team_member_id` instead. An optional ID of the employee associated with taking the payment.' maxLength: 192 readOnly: true x-release-status: DEPRECATED team_member_id: type: string description: An optional ID of the [TeamMember](entity:TeamMember) associated with taking the payment. maxLength: 192 nullable: true refund_ids: type: array items: type: string description: A list of `refund_id`s identifying refunds for the payment. readOnly: true risk_evaluation: $ref: '#/components/schemas/RiskEvaluation' description: 'Provides information about the risk associated with the payment, as determined by Square. This field is present for payments to sellers that have opted in to receive risk evaluations.' readOnly: true x-release-status: BETA terminal_checkout_id: type: string description: An optional ID for a Terminal checkout that is associated with the payment. readOnly: true x-release-status: BETA buyer_email_address: type: string description: The buyer's email address. maxLength: 255 readOnly: true billing_address: $ref: '#/components/schemas/Address' description: The buyer's billing address. readOnly: true shipping_address: $ref: '#/components/schemas/Address' description: The buyer's shipping address. readOnly: true note: type: string description: An optional note to include when creating a payment. maxLength: 500 readOnly: true statement_description_identifier: type: string description: 'Additional payment information that gets added to the customer''s card statement as part of the statement description. Note that the `statement_description_identifier` might get truncated on the statement description to fit the required information including the Square identifier (SQ *) and the name of the seller taking the payment.' readOnly: true capabilities: type: array items: type: string description: 'Actions that can be performed on this payment: - `EDIT_AMOUNT_UP` - The payment amount can be edited up. - `EDIT_AMOUNT_DOWN` - The payment amount can be edited down. - `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up. - `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down. - `EDIT_DELAY_ACTION` - The delay_action can be edited.' readOnly: true receipt_number: type: string description: 'The payment''s receipt number. The field is missing if a payment is canceled.' maxLength: 4 readOnly: true receipt_url: type: string description: 'The URL for the payment''s receipt. The field is only populated for COMPLETED payments.' maxLength: 255 readOnly: true device_details: $ref: '#/components/schemas/DeviceDetails' description: Details about the device that took the payment. readOnly: true application_details: $ref: '#/components/schemas/ApplicationDetails' description: Details about the application that took the payment. readOnly: true is_offline_payment: type: boolean description: Whether or not this payment was taken offline. readOnly: true offline_payment_details: $ref: '#/components/schemas/OfflinePaymentDetails' description: Additional information about the payment if it was taken offline. readOnly: true version_token: type: string description: 'Used for optimistic concurrency. This opaque token identifies a specific version of the `Payment` object.' nullable: true Money: type: object description: '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](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information.' x-release-status: PUBLIC properties: amount: type: integer description: 'The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.' format: int64 nullable: true currency: $ref: '#/components/schemas/Currency' description: 'The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](entity:Currency) for possible values. See [Currency](#type-currency) for possible values' nullable: true CardPrepaidType: type: string enum: - UNKNOWN_PREPAID_TYPE - NOT_PREPAID - PREPAID x-enum-elements: - name: UNKNOWN_PREPAID_TYPE description: '' - name: NOT_PREPAID description: '' - name: PREPAID description: '' description: Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`. x-release-status: PUBLIC CancelPaymentByIdempotencyKeyResponse: type: object description: "Defines the response returned by \n[CancelPaymentByIdempotencyKey](api-endpoint:Payments-CancelPaymentByIdempotencyKey).\nOn success, `errors` is empty." x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred during the request. example: {} ClearpayDetails: type: object description: Additional details about Clearpay payments. x-release-status: PUBLIC properties: email_address: type: string description: Email address on the buyer's Clearpay account. maxLength: 255 nullable: true ProcessingFee: type: object description: Represents the Square processing fee. x-release-status: PUBLIC properties: effective_at: type: string description: The timestamp of when the fee takes effect, in RFC 3339 format. nullable: true type: type: string description: The type of fee assessed or adjusted. The fee type can be `INITIAL` or `ADJUSTMENT`. nullable: true amount_money: $ref: '#/components/schemas/Money' description: 'The fee amount, which might be negative, that is assessed or adjusted by Square. Positive values represent funds being assessed, while negative values represent funds being returned.' nullable: true ListPaymentsResponse: type: object description: Defines the response returned by [ListPayments](api-endpoint:Payments-ListPayments). x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. payments: type: array items: $ref: '#/components/schemas/Payment' description: The requested list of payments. cursor: type: string description: 'The pagination cursor to be used in a subsequent request. If empty, this is the final response. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).' example: payments: - amount_money: amount: 555 currency: USD application_details: application_id: sq0ids-Pw67AZAlLVB7hsRmwlJPuA square_product: VIRTUAL_TERMINAL approved_money: amount: 555 currency: USD card_details: auth_result_code: 2Nkw7q avs_status: AVS_ACCEPTED card: bin: '411111' card_brand: VISA card_type: DEBIT exp_month: 11 exp_year: 2022 fingerprint: sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ last_4: '1111' prepaid_type: NOT_PREPAID card_payment_timeline: authorized_at: '2021-10-13T19:34:33.680Z' captured_at: '2021-10-13T19:34:34.340Z' cvv_status: CVV_ACCEPTED entry_method: KEYED statement_description: SQ *EXAMPLE TEST GOSQ.C status: CAPTURED created_at: '2021-10-13T19:34:33.524Z' delay_action: CANCEL delay_duration: PT168H delayed_until: '2021-10-20T19:34:33.524Z' employee_id: TMoK_ogh6rH1o4dV id: bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY location_id: L88917AVBK2S5 note: Test Note order_id: d7eKah653Z579f3gVtjlxpSlmUcZY processing_fee: - amount_money: amount: 34 currency: USD effective_at: '2021-10-13T21:34:35.000Z' type: INITIAL receipt_number: bP9m receipt_url: https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY source_type: CARD status: COMPLETED team_member_id: TMoK_ogh6rH1o4dV total_money: amount: 555 currency: USD updated_at: '2021-10-13T19:34:37.261Z' version_token: vguW2km0KpVCdAXZcNTZ438qg5LlVPTP4HO5OpiHNfa6o CreatePaymentResponse: type: object description: 'Defines the response returned by [CreatePayment](api-endpoint:Payments-CreatePayment). If there are errors processing the request, the `payment` field might not be present, or it might be present with a status of `FAILED`.' x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. payment: $ref: '#/components/schemas/Payment' description: The newly created payment. example: payment: amount_money: amount: 1000 currency: USD app_fee_money: amount: 10 currency: USD application_details: application_id: sq0ids-TcgftTEtKxJTRF1lCFJ9TA square_product: ECOMMERCE_API approved_money: amount: 1000 currency: USD card_details: auth_result_code: vNEn2f avs_status: AVS_ACCEPTED card: bin: '411111' card_brand: VISA card_type: DEBIT exp_month: 11 exp_year: 2022 fingerprint: sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ last_4: '1111' prepaid_type: NOT_PREPAID card_payment_timeline: authorized_at: '2021-10-13T21:14:29.732Z' captured_at: '2021-10-13T21:14:30.504Z' cvv_status: CVV_ACCEPTED entry_method: ON_FILE statement_description: SQ *EXAMPLE TEST GOSQ.C status: CAPTURED created_at: '2021-10-13T21:14:29.577Z' customer_id: W92WH6P11H4Z77CTET0RNTGFW8 delay_action: CANCEL delay_duration: PT168H delayed_until: '2021-10-20T21:14:29.577Z' id: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY location_id: L88917AVBK2S5 note: Brief Description order_id: pRsjRTgFWATl7so6DxdKBJa7ssbZY receipt_number: R2B3 receipt_url: https://squareup.com/receipt/preview/EXAMPLE_RECEIPT_ID reference_id: '123456' risk_evaluation: created_at: '2021-10-13T21:14:30.423Z' risk_level: NORMAL source_type: CARD status: COMPLETED total_money: amount: 1000 currency: USD updated_at: '2021-10-13T21:14:30.504Z' version_token: TPtNEOBOa6Qq6E3C3IjckSVOM6b3hMbfhjvTxHBQUsB6o CashAppDetails: type: object description: Additional details about `WALLET` type payments with the `brand` of `CASH_APP`. x-release-status: PUBLIC properties: buyer_full_name: type: string description: The name of the Cash App account holder. maxLength: 255 nullable: true buyer_country_code: type: string description: 'The country of the Cash App account holder, in ISO 3166-1-alpha-2 format. For possible values, see [Country](entity:Country).' minLength: 2 maxLength: 2 nullable: true buyer_cashtag: type: string description: $Cashtag of the Cash App account holder. minLength: 1 maxLength: 21 readOnly: true UpdatePaymentResponse: type: object description: 'Defines the response returned by [UpdatePayment](api-endpoint:Payments-UpdatePayment).' x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Any errors that occurred during the request. payment: $ref: '#/components/schemas/Payment' description: The updated payment. example: payment: amount_money: amount: 1000 currency: USD application_details: application_id: sq0ids-TcgftTEtKxJTRF1lCFJ9TA square_product: ECOMMERCE_API approved_money: amount: 1000 currency: USD capabilities: - EDIT_AMOUNT_UP - EDIT_AMOUNT_DOWN - EDIT_TIP_AMOUNT_UP - EDIT_TIP_AMOUNT_DOWN card_details: auth_result_code: 68aLBM avs_status: AVS_ACCEPTED card: bin: '411111' card_brand: VISA card_type: DEBIT exp_month: 11 exp_year: 2022 fingerprint: sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ last_4: '1111' prepaid_type: NOT_PREPAID card_payment_timeline: authorized_at: '2021-10-13T20:26:44.364Z' cvv_status: CVV_ACCEPTED entry_method: ON_FILE statement_description: SQ *EXAMPLE TEST GOSQ.C status: AUTHORIZED created_at: '2021-10-13T20:26:44.191Z' customer_id: W92WH6P11H4Z77CTET0RNTGFW8 delay_action: CANCEL delay_duration: PT168H delayed_until: '2021-10-20T20:26:44.191Z' id: 1QjqpBVyrI9S4H9sTGDWU9JeiWdZY location_id: L88917AVBK2S5 note: Example Note order_id: nUSN9TdxpiK3SrQg3wzmf6r8LP9YY receipt_number: 1Qjq risk_evaluation: created_at: '2021-10-13T20:26:45.271Z' risk_level: NORMAL source_type: CARD status: APPROVED tip_money: amount: 100 currency: USD total_money: amount: 1100 currency: USD updated_at: '2021-10-13T20:26:44.364Z' version_token: rDrXnqiS7fJgexccgdpzmwqTiXui1aIKCp9EchZ7trE6o DigitalWalletDetails: type: object description: Additional details about `WALLET` type payments. Contains only non-confidential information. x-release-status: PUBLIC properties: status: type: string description: 'The status of the `WALLET` payment. The status can be `AUTHORIZED`, `CAPTURED`, `VOIDED`, or `FAILED`.' maxLength: 50 nullable: true brand: type: string description: 'The brand used for the `WALLET` payment. The brand can be `CASH_APP`, `PAYPAY`, `ALIPAY`, `RAKUTEN_PAY`, `AU_PAY`, `D_BARAI`, `MERPAY`, `WECHAT_PAY` or `UNKNOWN`.' maxLength: 50 nullable: true cash_app_details: $ref: '#/components/schemas/CashAppDetails' description: Brand-specific details for payments with the `brand` of `CASH_APP`. nullable: true CardCoBrand: type: string enum: - UNKNOWN - AFTERPAY - CLEARPAY x-enum-elements: - name: UNKNOWN description: '' - name: AFTERPAY description: '' - name: CLEARPAY description: '' description: Indicates the brand for a co-branded card. x-release-status: PUBLIC ApplicationDetails: type: object description: Details about the application that took the payment. x-release-status: PUBLIC properties: square_product: $ref: '#/components/schemas/ApplicationDetailsExternalSquareProduct' description: "The Square product, such as Square Point of Sale (POS), \nSquare Invoices, or Square Virtual Terminal.\nSee [ExternalSquareProduct](#type-externalsquareproduct) for possible values" nullable: true application_id: type: string description: "The Square ID assigned to the application used to take the payment. \nApplication developers can use this information to identify payments that \ntheir application processed. \nFor example, if a developer uses a custom application to process payments, \nthis field contains the application ID from the Developer Dashboard. \nIf a seller uses a [Square App Marketplace](https://developer.squareup.com/docs/app-marketplace) \napplication to process payments, the field contains the corresponding application ID." nullable: true CustomerDetails: type: object description: Details about the customer making the payment. x-release-status: PUBLIC properties: customer_initiated: type: boolean description: Indicates whether the customer initiated the payment. nullable: true seller_keyed_in: type: boolean description: 'Indicates that the seller keyed in payment details on behalf of the customer. This is used to flag a payment as Mail Order / Telephone Order (MOTO).' nullable: true UpdatePaymentRequest: type: object description: 'Describes a request to update a payment using [UpdatePayment](api-endpoint:Payments-UpdatePayment).' x-release-status: PUBLIC required: - idempotency_key properties: payment: $ref: '#/components/schemas/Payment' description: The updated `Payment` object. nullable: true idempotency_key: type: string description: '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](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).' minLength: 1 maxLength: 45 example: idempotency_key: 956f8b13-e4ec-45d6-85e8-d1d95ef0c5de payment: amount_money: amount: 1000 currency: USD tip_money: amount: 100 currency: USD version_token: ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o Card: type: object description: '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.' x-release-status: PUBLIC properties: id: type: string description: Unique ID for this card. Generated by Square. maxLength: 64 readOnly: true card_brand: $ref: '#/components/schemas/CardBrand' description: 'The card''s brand. See [CardBrand](#type-cardbrand) for possible values' readOnly: true last_4: type: string description: The last 4 digits of the card number. maxLength: 4 readOnly: true exp_month: type: integer description: The expiration month of the associated card as an integer between 1 and 12. format: int64 nullable: true exp_year: type: integer description: The four-digit year of the card's expiration date. format: int64 nullable: true cardholder_name: type: string description: The name of the cardholder. maxLength: 96 nullable: true billing_address: $ref: '#/components/schemas/Address' description: The billing address for this card. nullable: true fingerprint: type: string description: 'Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.' maxLength: 255 readOnly: true customer_id: type: string description: '**Required** The ID of a customer created using the Customers API to be associated with the card.' nullable: true merchant_id: type: string description: The ID of the merchant associated with the card. readOnly: true reference_id: type: string description: 'An optional user-defined reference ID that associates this card with another entity in an external system. For example, a customer ID from an external customer management system.' maxLength: 128 nullable: true enabled: type: boolean description: Indicates whether or not a card can be used for payments. readOnly: true card_type: $ref: '#/components/schemas/CardType' description: 'The type of the card. The Card object includes this field only in response to Payments API calls. See [CardType](#type-cardtype) for possible values' readOnly: true prepaid_type: $ref: '#/components/schemas/CardPrepaidType' description: 'Indicates whether the Card is prepaid or not. The Card object includes this field only in response to Payments API calls. See [CardPrepaidType](#type-cardprepaidtype) for possible values' readOnly: true bin: type: string description: 'The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API returns this field.' maxLength: 6 readOnly: true version: type: integer description: 'Current version number of the card. Increments with each card update. Requests to update an existing Card object will be rejected unless the version in the request matches the current version for the Card.' format: int64 card_co_brand: $ref: '#/components/schemas/CardCoBrand' description: 'The card''s co-brand if available. For example, an Afterpay virtual card would have a co-brand of AFTERPAY. See [CardCoBrand](#type-cardcobrand) for possible values' readOnly: true Error: type: object description: 'Represents an error encountered during a request to the Connect API. See [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.' x-release-status: PUBLIC required: - category - code properties: category: $ref: '#/components/schemas/ErrorCategory' description: 'The high-level category for the error. See [ErrorCategory](#type-errorcategory) for possible values' code: $ref: '#/components/schemas/ErrorCode' description: 'The specific code of the error. See [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 the error pertains to.' CancelPaymentResponse: type: object description: Defines the response returned by [CancelPayment](api-endpoint:Payments-CancelPayment). x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. payment: $ref: '#/components/schemas/Payment' description: The successfully canceled `Payment` object. example: payment: amount_money: amount: 1000 currency: USD application_details: application_id: sq0ids-TcgftTEtKxJTRF1lCFJ9TA square_product: ECOMMERCE_API approved_money: amount: 1000 currency: USD card_details: auth_result_code: 68aLBM avs_status: AVS_ACCEPTED card: bin: '411111' card_brand: VISA card_type: DEBIT exp_month: 11 exp_year: 2022 fingerprint: sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ last_4: '1111' prepaid_type: NOT_PREPAID card_payment_timeline: authorized_at: '2021-10-13T20:26:44.364Z' voided_at: '2021-10-13T20:31:21.597Z' cvv_status: CVV_ACCEPTED entry_method: ON_FILE statement_description: SQ *EXAMPLE TEST GOSQ.C status: VOIDED created_at: '2021-10-13T20:26:44.191Z' customer_id: W92WH6P11H4Z77CTET0RNTGFW8 delay_action: CANCEL delay_duration: PT168H delayed_until: '2021-10-20T20:26:44.191Z' id: 1QjqpBVyrI9S4H9sTGDWU9JeiWdZY location_id: L88917AVBK2S5 note: Example Note order_id: nUSN9TdxpiK3SrQg3wzmf6r8LP9YY risk_evaluation: created_at: '2021-10-13T20:26:45.271Z' risk_level: NORMAL source_type: CARD status: CANCELED tip_money: amount: 100 currency: USD total_money: amount: 1100 currency: USD updated_at: '2021-10-13T20:31:21.597Z' version_token: N8AGYgEjCiY9Q57Jw7aVHEpBq8bzGCDCQMRX8Vs56N06o ApplicationDetailsExternalSquareProduct: type: string enum: - APPOINTMENTS - ECOMMERCE_API - INVOICES - ONLINE_STORE - OTHER - RESTAURANTS - RETAIL - SQUARE_POS - TERMINAL_API - VIRTUAL_TERMINAL x-enum-elements: - name: APPOINTMENTS description: '' - name: ECOMMERCE_API description: '' - name: INVOICES description: '' - name: ONLINE_STORE description: '' - name: OTHER description: '' - name: RESTAURANTS description: '' - name: RETAIL description: '' - name: SQUARE_POS description: '' - name: TERMINAL_API description: '' - name: VIRTUAL_TERMINAL description: '' description: A list of products to return to external callers. x-release-status: PUBLIC CardPaymentDetails: type: object description: Reflects the current status of a card payment. Contains only non-confidential information. x-release-status: PUBLIC properties: status: type: string description: 'The card payment''s current state. The state can be AUTHORIZED, CAPTURED, VOIDED, or FAILED.' maxLength: 50 nullable: true card: $ref: '#/components/schemas/Card' description: The credit card's non-confidential details. nullable: true entry_method: type: string description: 'The method used to enter the card''s details for the payment. The method can be `KEYED`, `SWIPED`, `EMV`, `ON_FILE`, or `CONTACTLESS`.' maxLength: 50 nullable: true cvv_status: type: string description: 'The status code returned from the Card Verification Value (CVV) check. The code can be `CVV_ACCEPTED`, `CVV_REJECTED`, or `CVV_NOT_CHECKED`.' maxLength: 50 nullable: true avs_status: type: string description: 'The status code returned from the Address Verification System (AVS) check. The code can be `AVS_ACCEPTED`, `AVS_REJECTED`, or `AVS_NOT_CHECKED`.' maxLength: 50 nullable: true auth_result_code: type: string description: 'The status code returned by the card issuer that describes the payment''s authorization status.' maxLength: 10 nullable: true application_identifier: type: string description: For EMV payments, the application ID identifies the EMV application used for the payment. maxLength: 32 nullable: true application_name: type: string description: For EMV payments, the human-readable name of the EMV application used for the payment. maxLength: 16 nullable: true application_cryptogram: type: string description: For EMV payments, the cryptogram generated for the payment. maxLength: 16 nullable: true verification_method: type: string description: 'For EMV payments, the method used to verify the cardholder''s identity. The method can be `PIN`, `SIGNATURE`, `PIN_AND_SIGNATURE`, `ON_DEVICE`, or `NONE`.' maxLength: 50 nullable: true verification_results: type: string description: 'For EMV payments, the results of the cardholder verification. The result can be `SUCCESS`, `FAILURE`, or `UNKNOWN`.' maxLength: 50 nullable: true statement_description: type: string description: 'The statement description sent to the card networks. Note: The actual statement description varies and is likely to be truncated and appended with additional information on a per issuer basis.' maxLength: 50 nullable: true device_details: $ref: '#/components/schemas/DeviceDetails' description: '__Deprecated__: Use `Payment.device_details` instead. Details about the device that took the payment.' x-release-status: DEPRECATED nullable: true card_payment_timeline: $ref: '#/components/schemas/CardPaymentTimeline' description: The timeline for card payments. nullable: true refund_requires_card_presence: type: boolean description: 'Whether the card must be physically present for the payment to be refunded. If set to `true`, the card must be present.' x-release-status: BETA nullable: true errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. nullable: true CardType: type: string enum: - UNKNOWN_CARD_TYPE - CREDIT - DEBIT x-enum-elements: - name: UNKNOWN_CARD_TYPE description: '' - name: CREDIT description: '' - name: DEBIT description: '' description: Indicates a card's type, such as `CREDIT` or `DEBIT`. x-release-status: PUBLIC CardBrand: type: string enum: - OTHER_BRAND - VISA - MASTERCARD - AMERICAN_EXPRESS - DISCOVER - DISCOVER_DINERS - JCB - CHINA_UNIONPAY - SQUARE_GIFT_CARD - SQUARE_CAPITAL_CARD - INTERAC - EFTPOS - FELICA - EBT x-enum-elements: - name: OTHER_BRAND description: '' - name: VISA description: '' - name: MASTERCARD description: '' - name: AMERICAN_EXPRESS description: '' - name: DISCOVER description: '' - name: DISCOVER_DINERS description: '' - name: JCB description: '' - name: CHINA_UNIONPAY description: '' - name: SQUARE_GIFT_CARD description: '' - name: SQUARE_CAPITAL_CARD description: '' - name: INTERAC description: '' - name: EFTPOS description: '' - name: FELICA description: '' - name: EBT description: '' description: Indicates a card's brand, such as `VISA` or `MASTERCARD`. x-release-status: PUBLIC OfflinePaymentDetails: type: object description: Details specific to offline payments. x-release-status: PUBLIC properties: client_created_at: type: string description: The client-side timestamp of when the offline payment was created, in RFC 3339 format. maxLength: 32 readOnly: true ACHDetails: type: object description: ACH-specific details about `BANK_ACCOUNT` type payments with the `transfer_type` of `ACH`. x-release-status: PUBLIC properties: routing_number: type: string description: The routing number for the bank account. maxLength: 50 nullable: true account_number_suffix: type: string description: The last few digits of the bank account number. minLength: 1 maxLength: 4 nullable: true account_type: type: string description: 'The type of the bank account performing the transfer. The account type can be `CHECKING`, `SAVINGS`, or `UNKNOWN`.' maxLength: 50 nullable: true CreatePaymentRequest: type: object description: "Describes a request to create a payment using \n[CreatePayment](api-endpoint:Payments-CreatePayment)." x-release-status: PUBLIC required: - source_id - idempotency_key properties: source_id: type: string description: "The ID for the source of funds for this payment.\nThis could be a payment token generated by the Web Payments SDK for any of its\n[supported methods](https://developer.squareup.com/docs/web-payments/overview#explore-payment-methods),\nincluding cards, bank transfers, Afterpay or Cash App Pay. If recording a payment\nthat the seller received outside of Square, specify either \"CASH\" or \"EXTERNAL\".\nFor more information, see \n[Take Payments](https://developer.squareup.com/docs/payments-api/take-payments)." minLength: 1 idempotency_key: type: string description: '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](https://developer.squareup.com/docs/working-with-apis/idempotency).' minLength: 1 maxLength: 45 amount_money: $ref: '#/components/schemas/Money' description: 'The amount of money to accept for this payment, not including `tip_money`. The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts). The currency code must match the currency associated with the business that is accepting the payment.' tip_money: $ref: '#/components/schemas/Money' description: 'The amount designated as a tip, in addition to `amount_money`. The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts). The currency code must match the currency associated with the business that is accepting the payment.' app_fee_money: $ref: '#/components/schemas/Money' description: 'The amount of money that the developer is taking as a fee for facilitating the payment on behalf of the seller. The amount cannot be more than 90% of the total amount of the payment. The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see [Working with Monetary Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts). The fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller. For more information about the application fee scenario, see [Take Payments and Collect Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees). To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission is required. For more information, see [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).' delay_duration: type: string description: "The duration of time after the payment's creation when Square automatically \neither completes or cancels the payment depending on the `delay_action` field value. \nFor more information, see \n[Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). \n\nThis parameter should be specified as a time duration, in RFC 3339 format.\n\nNote: This feature is only supported for card payments. This parameter can only be set for a delayed\ncapture payment (`autocomplete=false`).\n\nDefault:\n\n- Card-present payments: \"PT36H\" (36 hours) from the creation time.\n- Card-not-present payments: \"P7D\" (7 days) from the creation time." delay_action: type: string description: "The action to be applied to the payment when the `delay_duration` has elapsed. The action must be\nCANCEL or COMPLETE. For more information, see \n[Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). \n\nDefault: CANCEL" autocomplete: type: boolean description: '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](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment). Default: true' order_id: type: string description: Associates a previously created order with this payment. customer_id: type: string description: 'The [Customer](entity: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.' location_id: type: string description: 'The location ID to associate with the payment. If not specified, the [main location](https://developer.squareup.com/docs/locations-api#about-the-main-location) is used.' team_member_id: type: string description: "An optional [TeamMember](entity:TeamMember) ID to associate with \nthis payment." reference_id: type: string description: "A user-defined ID to associate with the payment.\n\nYou can use this field to associate the payment to an entity in an external system \n(for example, you might specify an order ID that is generated by a third-party shopping cart)." maxLength: 40 verification_token: type: string description: 'An identifying token generated by [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#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](https://developer.squareup.com/docs/sca-overview).' accept_partial_authorization: type: boolean description: '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 $20 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](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card). Default: false' buyer_email_address: type: string description: The buyer's email address. maxLength: 255 buyer_phone_number: type: string description: '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.' billing_address: $ref: '#/components/schemas/Address' description: The buyer's billing address. shipping_address: $ref: '#/components/schemas/Address' description: The buyer's shipping address. note: type: string description: An optional note to be entered by the developer when creating a payment. maxLength: 500 statement_description_identifier: type: string description: '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.' maxLength: 20 cash_details: $ref: '#/components/schemas/CashPaymentDetails' description: Additional details required when recording a cash payment (`source_id` is CASH). external_details: $ref: '#/components/schemas/ExternalPaymentDetails' description: Additional details required when recording an external payment (`source_id` is EXTERNAL). customer_details: $ref: '#/components/schemas/CustomerDetails' description: Details about the customer making the payment. offline_payment_details: $ref: '#/components/schemas/OfflinePaymentDetails' description: 'An optional field for specifying the offline payment details. This is intended for internal 1st-party callers only.' example: amount_money: amount: 1000 currency: USD app_fee_money: amount: 10 currency: USD autocomplete: true customer_id: W92WH6P11H4Z77CTET0RNTGFW8 idempotency_key: 7b0f3ec5-086a-4871-8f13-3c81b3875218 location_id: L88917AVBK2S5 note: Brief description reference_id: '123456' source_id: ccof:GaJGNaZa8x4OgDJn4GB DeviceDetails: type: object description: Details about the device that took the payment. x-release-status: PUBLIC properties: device_id: type: string description: The Square-issued ID of the device. maxLength: 255 nullable: true device_installation_id: type: string description: The Square-issued installation ID for the device. maxLength: 255 nullable: true device_name: type: string description: The name of the device set by the seller. maxLength: 255 nullable: true CancelPaymentByIdempotencyKeyRequest: type: object description: "Describes a request to cancel a payment using \n[CancelPaymentByIdempotencyKey](api-endpoint:Payments-CancelPaymentByIdempotencyKey)." x-release-status: PUBLIC required: - idempotency_key properties: idempotency_key: type: string description: The `idempotency_key` identifying the payment to be canceled. minLength: 1 maxLength: 45 example: idempotency_key: a7e36d40-d24b-11e8-b568-0800200c9a66 SquareAccountDetails: type: object description: Additional details about Square Account payments. x-release-status: PUBLIC properties: payment_source_token: type: string description: Unique identifier for the payment source used for this payment. maxLength: 255 nullable: true errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. nullable: true PaymentSortField: type: string enum: - CREATED_AT - OFFLINE_CREATED_AT - UPDATED_AT x-enum-elements: - name: CREATED_AT description: '' - name: OFFLINE_CREATED_AT description: '' - name: UPDATED_AT description: '' x-release-status: PUBLIC CashPaymentDetails: type: object description: "Stores details about a cash payment. Contains only non-confidential information. For more information, see \n[Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments)." x-release-status: PUBLIC required: - buyer_supplied_money properties: buyer_supplied_money: $ref: '#/components/schemas/Money' description: The amount and currency of the money supplied by the buyer. change_back_money: $ref: '#/components/schemas/Money' description: "The amount of change due back to the buyer. \nThis read-only field is calculated\nfrom the `amount_money` and `buyer_supplied_money` fields." nullable: true CardPaymentTimeline: type: object description: The timeline for card payments. x-release-status: PUBLIC properties: authorized_at: type: string description: The timestamp when the payment was authorized, in RFC 3339 format. nullable: true captured_at: type: string description: The timestamp when the payment was captured, in RFC 3339 format. nullable: true voided_at: type: string description: The timestamp when the payment was voided, in RFC 3339 format. nullable: true GetPaymentResponse: type: object description: Defines the response returned by [GetPayment](api-endpoint:Payments-GetPayment). x-release-status: PUBLIC properties: errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. payment: $ref: '#/components/schemas/Payment' description: The requested `Payment`. example: payment: amount_money: amount: 555 currency: USD application_details: application_id: sq0ids-Pw67AZAlLVB7hsRmwlJPuA square_product: VIRTUAL_TERMINAL approved_money: amount: 555 currency: USD card_details: auth_result_code: 2Nkw7q avs_status: AVS_ACCEPTED card: bin: '411111' card_brand: VISA card_type: DEBIT exp_month: 11 exp_year: 2022 fingerprint: sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ last_4: '1111' prepaid_type: NOT_PREPAID card_payment_timeline: authorized_at: '2021-10-13T19:34:33.680Z' captured_at: '2021-10-13T19:34:34.340Z' cvv_status: CVV_ACCEPTED entry_method: KEYED statement_description: SQ *EXAMPLE TEST GOSQ.C status: CAPTURED created_at: '2021-10-13T19:34:33.524Z' delay_action: CANCEL delay_duration: PT168H delayed_until: '2021-10-20T19:34:33.524Z' employee_id: TMoK_ogh6rH1o4dV id: bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY location_id: L88917AVBK2S5 note: Test Note order_id: d7eKah653Z579f3gVtjlxpSlmUcZY processing_fee: - amount_money: amount: 34 currency: USD effective_at: '2021-10-13T21:34:35.000Z' type: INITIAL receipt_number: bP9m receipt_url: https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY source_type: CARD status: COMPLETED team_member_id: TMoK_ogh6rH1o4dV total_money: amount: 555 currency: USD updated_at: '2021-10-13T19:34:34.339Z' version_token: 56pRkL3slrzet2iQrTp9n0bdJVYTB9YEWdTNjQfZOPV6o AfterpayDetails: type: object description: Additional details about Afterpay payments. x-release-status: PUBLIC properties: email_address: type: string description: Email address on the buyer's Afterpay account. maxLength: 255 nullable: true CompletePaymentRequest: type: object description: "Describes a request to complete (capture) a payment using \n[CompletePayment](api-endpoint:Payments-CompletePayment).\n\nBy default, payments are set to `autocomplete` immediately after they are created.\nTo complete payments manually, set `autocomplete` to `false`." x-release-status: PUBLIC properties: version_token: type: string description: "Used for optimistic concurrency. This opaque token identifies the current `Payment` \nversion that the caller expects. If the server has a different version of the Payment, \nthe update fails and a response with a VERSION_MISMATCH error is returned." x-release-status: BETA nullable: true example: {} RiskEvaluationRiskLevel: type: string enum: - PENDING - NORMAL - MODERATE - HIGH x-enum-elements: - name: PENDING description: Indicates Square is still evaluating the payment. - name: NORMAL description: Indicates payment risk is within the normal range. - name: MODERATE description: Indicates elevated risk level associated with the payment. - name: HIGH description: Indicates significantly elevated risk level with the payment. x-release-status: BETA ExternalPaymentDetails: type: object description: "Stores details about an external payment. Contains only non-confidential information.\nFor more information, see \n[Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments)." x-release-status: PUBLIC required: - type - source properties: type: type: string description: 'The type of external payment the seller received. It can be one of the following: - CHECK - Paid using a physical check. - BANK_TRANSFER - Paid using external bank transfer. - OTHER\_GIFT\_CARD - Paid using a non-Square gift card. - CRYPTO - Paid using a crypto currency. - SQUARE_CASH - Paid using Square Cash App. - SOCIAL - Paid using peer-to-peer payment applications. - EXTERNAL - A third-party application gathered this payment outside of Square. - EMONEY - Paid using an E-money provider. - CARD - A credit or debit card that Square does not support. - STORED_BALANCE - Use for house accounts, store credit, and so forth. - FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals - OTHER - A type not listed here.' maxLength: 50 source: type: string description: "A description of the external payment source. For example, \n\"Food Delivery Service\"." maxLength: 255 source_id: type: string description: An ID to associate the payment to its originating source. maxLength: 255 nullable: true source_fee_money: $ref: '#/components/schemas/Money' description: "The fees paid to the source. The `amount_money` minus this field is \nthe net amount seller receives." nullable: true BankAccountPaymentDetails: type: object description: Additional details about BANK_ACCOUNT type payments. x-release-status: PUBLIC properties: bank_name: type: string description: The name of the bank associated with the bank account. maxLength: 100 nullable: true transfer_type: type: string description: The type of the bank transfer. The type can be `ACH` or `UNKNOWN`. maxLength: 50 nullable: true account_ownership_type: type: string description: 'The ownership type of the bank account performing the transfer. The type can be `INDIVIDUAL`, `COMPANY`, or `ACCOUNT_TYPE_UNKNOWN`.' maxLength: 50 nullable: true fingerprint: type: string description: 'Uniquely identifies the bank account for this seller and can be used to determine if payments are from the same bank account.' maxLength: 255 nullable: true country: type: string description: The two-letter ISO code representing the country the bank account is located in. minLength: 2 maxLength: 2 nullable: true statement_description: type: string description: The statement description as sent to the bank. maxLength: 1000 nullable: true ach_details: $ref: '#/components/schemas/ACHDetails' description: 'ACH-specific information about the transfer. The information is only populated if the `transfer_type` is `ACH`.' nullable: true errors: type: array items: $ref: '#/components/schemas/Error' description: Information about errors encountered during the request. nullable: true securitySchemes: oauth2: type: oauth2 x-additional-headers: - name: Square-Version description: Square Connect API versions schema: default: '2025-01-23' flows: authorizationCode: authorizationUrl: https://connect.squareup.com/oauth2/authorize tokenUrl: https://connect.squareup.com/oauth2/token scopes: ADDON_CONFIGURATIONS_READ: '__HTTP Method__: `GET` Grants write access for third-party Add-ons to read configurations of their Add-ons, for example, when calling `RetrieveConfiguration` endpoint.' ADDON_CONFIGURATIONS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access for third-party Add-ons to store configurations of their Add-ons, for example, when calling `CreateConfiguration` endpoint.' APPOINTMENTS_ALL_READ: '__HTTP Method__: `GET`, `POST` Grants read access to all of a seller''s booking information, calendar, and business details. This permission must be accompanied by the `APPOINTMENTS_READ` permission.' APPOINTMENTS_ALL_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to all booking details, including double-booking a seller. This permission must be accompanied by the `APPOINTMENTS_WRITE` permission.' APPOINTMENTS_BUSINESS_SETTINGS_READ: '__HTTP Method__: `GET` Grants read access to booking business settings. For example, to call the ListTeamMemberBookingProfiles endpoint.' APPOINTMENTS_READ: '__HTTP Method__: `GET`, `POST` Grants read access to booking information. For example, to call the RetrieveBooking endpoint.' APPOINTMENTS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to booking information. For example, to call the CreateBooking endpoint.' BANK_ACCOUNTS_READ: '__HTTP Method__: `GET` Grants read access to bank account information associated with the targeted Square account. For example, to call the Connect v1 ListBankAccounts endpoint.' CASH_DRAWER_READ: '__HTTP Method__: `GET` Grants read access to cash drawer shift information. For example, to call the ListCashDrawerShifts endpoint.' CHANNELS_CREATE: '__HTTP Method__: `POST` Grants write access to create channels, for example, when calling the `CreateChannel` endpoint.' CHANNELS_READ: '__HTTP Method__: `GET` Grants read access to view channels, for example, when calling the `RetrieveChannel` endpoint.' CHANNELS_UPDATE: '__HTTP Method__: `PUT` Grants write access to update channels, for example, when calling the `UpdateChannel` endpoint.' CUSTOMERS_READ: '__HTTP Method__: `GET` Grants read access to customer information. For example, to call the ListCustomers endpoint.' CUSTOMERS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to customer information. For example, to create and update customer profiles.' DEVICES_READ: '__HTTP Method__: `GET` Grants read access to device information. For example, to call the `GetDevice` and `ListDevices` endpoints.' DEVICE_CREDENTIAL_MANAGEMENT: '__HTTP Method__: `POST`, `GET` Grants read/write access to device credentials information. For example, to call the CreateDeviceCode endpoint.' DISPUTES_READ: '__HTTP Method__: `GET` Grants read access to dispute information. For example, to call the RetrieveDispute endpoint.' DISPUTES_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to dispute information. For example, to call the SubmitEvidence endpoint.' EMPLOYEES_READ: '__HTTP Method__: `GET` Grants read access to employee profile information. For example, to call the Connect v1 Employees API.' EMPLOYEES_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to employee profile information. For example, to create and modify employee profiles.' GIFTCARDS_READ: '__HTTP Method__: `GET`, `POST` Grants read access to gift card information. For example, to call the RetrieveGiftCard endpoint.' GIFTCARDS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to gift card information. For example, to call the CreateGiftCard endpoint.' INVENTORY_READ: '__HTTP Method__: `GET` Grants read access to inventory information. For example, to call the RetrieveInventoryCount endpoint.' INVENTORY_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to inventory information. For example, to call the BatchChangeInventory endpoint.' INVOICES_READ: '__HTTP Method__: `GET`, `POST` Grants read access to invoice information. For example, to call the ListInvoices endpoint.' INVOICES_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to invoice information. For example, to call the CreateInvoice endpoint.' ITEMS_READ: '__HTTP Method__: `GET` Grants read access to product catalog information. For example, to obtain objects in a product catalog.' ITEMS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to product catalog information. For example, to modify or add to a product catalog.' LOYALTY_READ: '__HTTP Method__: `GET` Grants read access to loyalty information. For example, to call the ListLoyaltyPrograms endpoint.' LOYALTY_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to loyalty information. For example, to call the CreateLoyaltyAccount endpoint.' MERCHANT_PROFILE_READ: '__HTTP Method__: `GET` Grants read access to business and location information. For example, to obtain a location ID for subsequent activity.' MERCHANT_PROFILE_WRITE: '__HTTP Method__: `POST`, `PUT` Grants write access to business and location information. For example, to create a new location or update the business hours at an existing location.' ONLINE_STORE_SITE_READ: '__HTTP Method__: `GET`, `POST` Read access to ECOM online store site details.' ONLINE_STORE_SNIPPETS_READ: '__HTTP Method__: `GET`, `POST` Read access to ECOM online store snippets on published websites.' ONLINE_STORE_SNIPPETS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Write access to ECOM online store snippets on published websites.' ORDERS_READ: '__HTTP Method__: `GET` Grants read access to order information. For example, to call the BatchRetrieveOrders endpoint.' ORDERS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to order information. For example, to call the CreateCheckout endpoint.' PAYMENTS_READ: '__HTTP Method__: `GET` Grants read access to transaction and refund information. For example, to call the RetrieveTransaction endpoint.' PAYMENTS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to transaction and refunds information. For example, to process payments with the Payments or Checkout API.' PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: '__HTTP Method__: `POST`, `PUT`, `DELETE` Allow third party applications to deduct a portion of each transaction amount. __Required__ to use multiparty transaction functionality with the Payments API.' PAYMENTS_WRITE_IN_PERSON: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to payments and refunds information. For example, to process in-person payments.' PAYMENTS_WRITE_SHARED_ONFILE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Allows the developer to process payments on behalf of a seller using a shared on file payment method.' PAYOUTS_READ: '__HTTP Method__: `GET` Grants read access to payouts and payout entries information. For example, to call the Connect v2 `ListPayouts` endpoint.' PERMISSION_SETS_READ: '__HTTP Method__: `GET` Grants read access to Permission Sets. For example, to call the `ListPermissionSets` and `RetrievePermissionSet` endpoints.' PERMISSION_SETS_WRITE: '__HTTP Method__: `PUT` Grants write access to Permission Sets.' RESERVATIONS_READ: '__HTTP Method__: `GET` Grants read access to reservation information, for example, when calling the `RetrieveReservation` endpoint.' RESERVATIONS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to reservation information, for example, when calling the `CreateReservation` endpoint.' RESTAURANT_CHECKS_READ: '__HTTP Method__: `GET` Grants read access to check information, for example, when calling the `RetrieveCheck` endpoint.' SETTLEMENTS_READ: '__HTTP Method__: `GET` Grants read access to settlement (deposit) information. For example, to call the Connect v1 ListSettlements endpoint.' SUBSCRIPTIONS_READ: '__HTTP Method__: `GET`, `POST` Grants read access to subscription information. For example, to call the RetrieveSubscription endpoint.' SUBSCRIPTIONS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to subscription information. For example, to call the CreateSubscription endpoint.' TIMECARDS_READ: '__HTTP Method__: `GET` Grants read access to employee timecard information. For example, to call the Connect v2 SearchShifts endpoint.' TIMECARDS_SETTINGS_READ: '__HTTP Method__: `GET` Grants read access to employee timecard settings information. For example, to call the GetBreakType endpoint.' TIMECARDS_SETTINGS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to employee timecard settings information. For example, to call the UpdateBreakType endpoint.' TIMECARDS_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to employee shift information. For example, to create and modify employee shifts.' VENDOR_READ: '__HTTP Method__: `GET`, `POST` Grants read access to vendor information, for example, when calling the `RetrieveVendor` endpoint.' VENDOR_WRITE: '__HTTP Method__: `POST`, `PUT`, `DELETE` Grants write access to vendor information, for example, when calling the `BulkUpdateVendors` endpoint.' oauth2ClientSecret: type: apiKey in: header name: Authorization x-fern-global-headers: - header: Square-Version name: version optional: true env: VERSION type: literal<"2025-01-23">