> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# square-payments
> Square Payments & Checkout
**Server path:** `/square-payments` | **Type:** Application | **PCID required:** Yes
## Tools
| Tool | Description |
| --------------------------------------------------------------------------------------------------------- | ----------------------------- |
| [`square_payments_cancel_payment`](#square_payments_cancel_payment) | CancelPayment |
| [`square_payments_cancel_payment_by_idempotency_key`](#square_payments_cancel_payment_by_idempotency_key) | CancelPaymentByIdempotencyKey |
| [`square_payments_complete_payment`](#square_payments_complete_payment) | CompletePayment |
| [`square_payments_create_bank_account`](#square_payments_create_bank_account) | CreateBankAccount |
| [`square_payments_create_card`](#square_payments_create_card) | CreateCard |
| [`square_payments_create_gift_card`](#square_payments_create_gift_card) | CreateGiftCard |
| [`square_payments_create_gift_card_activity`](#square_payments_create_gift_card_activity) | CreateGiftCardActivity |
| [`square_payments_create_payment`](#square_payments_create_payment) | CreatePayment |
| [`square_payments_create_payment_link`](#square_payments_create_payment_link) | CreatePaymentLink |
| [`square_payments_delete_payment_link`](#square_payments_delete_payment_link) | DeletePaymentLink |
| [`square_payments_disable_bank_account`](#square_payments_disable_bank_account) | DisableBankAccount |
| [`square_payments_disable_card`](#square_payments_disable_card) | DisableCard |
| [`square_payments_get_bank_account`](#square_payments_get_bank_account) | GetBankAccount |
| [`square_payments_get_bank_account_by_v1id`](#square_payments_get_bank_account_by_v1id) | GetBankAccountByV1Id |
| [`square_payments_get_payment`](#square_payments_get_payment) | GetPayment |
| [`square_payments_get_payment_refund`](#square_payments_get_payment_refund) | GetPaymentRefund |
| [`square_payments_get_payout`](#square_payments_get_payout) | GetPayout |
| [`square_payments_link_customer_to_gift_card`](#square_payments_link_customer_to_gift_card) | LinkCustomerToGiftCard |
| [`square_payments_list_bank_accounts`](#square_payments_list_bank_accounts) | ListBankAccounts |
| [`square_payments_list_cards`](#square_payments_list_cards) | ListCards |
| [`square_payments_list_cash_drawer_shift_events`](#square_payments_list_cash_drawer_shift_events) | ListCashDrawerShiftEvents |
| [`square_payments_list_cash_drawer_shifts`](#square_payments_list_cash_drawer_shifts) | ListCashDrawerShifts |
| [`square_payments_list_gift_card_activities`](#square_payments_list_gift_card_activities) | ListGiftCardActivities |
| [`square_payments_list_gift_cards`](#square_payments_list_gift_cards) | ListGiftCards |
| [`square_payments_list_payment_links`](#square_payments_list_payment_links) | ListPaymentLinks |
| [`square_payments_list_payment_refunds`](#square_payments_list_payment_refunds) | ListPaymentRefunds |
| [`square_payments_list_payments`](#square_payments_list_payments) | ListPayments |
| [`square_payments_list_payout_entries`](#square_payments_list_payout_entries) | ListPayoutEntries |
| [`square_payments_list_payouts`](#square_payments_list_payouts) | ListPayouts |
| [`square_payments_refund_payment`](#square_payments_refund_payment) | RefundPayment |
| [`square_payments_register_domain`](#square_payments_register_domain) | RegisterDomain |
| [`square_payments_retrieve_card`](#square_payments_retrieve_card) | RetrieveCard |
| [`square_payments_retrieve_cash_drawer_shift`](#square_payments_retrieve_cash_drawer_shift) | RetrieveCashDrawerShift |
| [`square_payments_retrieve_gift_card`](#square_payments_retrieve_gift_card) | RetrieveGiftCard |
| [`square_payments_retrieve_gift_card_from_gan`](#square_payments_retrieve_gift_card_from_gan) | RetrieveGiftCardFromGAN |
| [`square_payments_retrieve_gift_card_from_nonce`](#square_payments_retrieve_gift_card_from_nonce) | RetrieveGiftCardFromNonce |
| [`square_payments_retrieve_location_settings`](#square_payments_retrieve_location_settings) | RetrieveLocationSettings |
| [`square_payments_retrieve_merchant_settings`](#square_payments_retrieve_merchant_settings) | RetrieveMerchantSettings |
| [`square_payments_retrieve_payment_link`](#square_payments_retrieve_payment_link) | RetrievePaymentLink |
| [`square_payments_unlink_customer_from_gift_card`](#square_payments_unlink_customer_from_gift_card) | UnlinkCustomerFromGiftCard |
| [`square_payments_update_location_settings`](#square_payments_update_location_settings) | UpdateLocationSettings |
| [`square_payments_update_merchant_settings`](#square_payments_update_merchant_settings) | UpdateMerchantSettings |
| [`square_payments_update_payment`](#square_payments_update_payment) | UpdatePayment |
| [`square_payments_update_payment_link`](#square_payments_update_payment_link) | UpdatePaymentLink |
***
## square\_payments\_cancel\_payment
CancelPayment
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | -------------------------------- |
| `payment_id` | string | Yes | — | The ID of the payment to cancel. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"payment_id": {
"type": "string",
"description": "The ID of the payment to cancel."
}
},
"required": [
"PCID",
"payment_id"
]
}
```
***
## square\_payments\_cancel\_payment\_by\_idempotency\_key
CancelPaymentByIdempotencyKey
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ------------------------------------------------------------- |
| `idempotency_key` | string | Yes | — | The `idempotency_key` identifying the payment to be canceled. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"idempotency_key": {
"type": "string",
"description": "The `idempotency_key` identifying the payment to be canceled."
}
},
"required": [
"PCID",
"idempotency_key"
]
}
```
***
## square\_payments\_complete\_payment
CompletePayment
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| --------------- | ------ | -------- | ------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `payment_id` | string | Yes | — | The unique ID identifying the payment to be completed. | |
| `version_token` | string | null | No | — | Used for optimistic concurrency. This opaque token identifies the current `Payment` version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION\_MISMATCH error is returned. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"payment_id": {
"type": "string",
"description": "The unique ID identifying the payment to be completed."
},
"version_token": {
"type": [
"string",
"null"
],
"description": "Used for optimistic concurrency. This opaque token identifies the current `Payment` version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION_MISMATCH error is returned."
}
},
"required": [
"PCID",
"payment_id"
]
}
```
***
## square\_payments\_create\_bank\_account
CreateBankAccount
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `customer_id` | string | No | — | The ID of the customer associated with the bank account to be stored. |
| `idempotency_key` | string | Yes | — | Unique ID. For more information, see the [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency). |
| `source_id` | string | Yes | — | The ID of the source that represents the bank account information to be stored. This field accepts the payment token created by WebSDK |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"customer_id": {
"type": "string",
"description": "The ID of the customer associated with the bank account to be stored."
},
"idempotency_key": {
"type": "string",
"description": "Unique ID. For more information, see the [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)."
},
"source_id": {
"type": "string",
"description": "The ID of the source that represents the bank account information to be stored. This field accepts the payment token created by WebSDK"
}
},
"required": [
"PCID",
"idempotency_key",
"source_id"
]
}
```
***
## square\_payments\_create\_card
CreateCard
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `card` | object | Yes | — | Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK. |
| `idempotency_key` | string | Yes | — | A unique string that identifies this CreateCard request. Keys can be any valid string and must be unique for every request. Max: 45 characters See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information. |
| `source_id` | string | Yes | — | The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id. |
| `verification_token` | string | No | — | 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. See the [SCA Overview](https://developer.squareup.com/docs/sca-overview). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"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.",
"properties": {
"id": {
"type": "string",
"description": "Unique ID for this card. Generated by Square."
},
"card_brand": {
"type": "string",
"description": "Indicates a card's brand, such as `VISA` or `MASTERCARD`.",
"enum": [
"OTHER_BRAND",
"VISA",
"MASTERCARD",
"AMERICAN_EXPRESS",
"DISCOVER",
"DISCOVER_DINERS",
"JCB",
"CHINA_UNIONPAY",
"SQUARE_GIFT_CARD",
"SQUARE_CAPITAL_CARD",
"INTERAC",
"EFTPOS",
"FELICA",
"EBT"
]
},
"last_4": {
"type": "string",
"description": "The last 4 digits of the card number."
},
"exp_month": {
"type": "integer",
"description": "The expiration month of the associated card as an integer between 1 and 12."
},
"exp_year": {
"type": "integer",
"description": "The four-digit year of the card's expiration date."
},
"cardholder_name": {
"type": "string",
"description": "The name of the cardholder."
},
"billing_address": {
"type": "object",
"description": "Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)."
},
"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."
},
"customer_id": {
"type": "string",
"description": "**Required** The ID of a [customer](entity:Customer) to be associated with the card."
},
"merchant_id": {
"type": "string",
"description": "The ID of the merchant associated with the card."
},
"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."
},
"enabled": {
"type": "boolean",
"description": "Indicates whether or not a card can be used for payments."
},
"card_type": {
"type": "string",
"description": "Indicates a card's type, such as `CREDIT` or `DEBIT`.",
"enum": [
"UNKNOWN_CARD_TYPE",
"CREDIT",
"DEBIT"
]
},
"prepaid_type": {
"type": "string",
"description": "Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`.",
"enum": [
"UNKNOWN_PREPAID_TYPE",
"NOT_PREPAID",
"PREPAID"
]
},
"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."
},
"created_at": {
"type": "string",
"description": "Timestamp for when the card object was created on Square’s servers. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\"."
},
"disabled_at": {
"type": "string",
"description": "Timestamp for when the card object was disabled on Square’s servers. In RFC 3339 format, e.g., \"2016-09-04T23:59:33.123Z\"."
},
"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."
},
"card_co_brand": {
"type": "string",
"description": "Indicates the brand for a co-branded card.",
"enum": [
"UNKNOWN",
"AFTERPAY",
"CLEARPAY"
]
},
"issuer_alert": {
"type": "string",
"description": "Indicates the type of issuer alert for a [card on file](entity:Card).",
"enum": [
"ISSUER_ALERT_CARD_CLOSED"
]
},
"issuer_alert_at": {
"type": "string",
"description": "The timestamp of when the current issuer alert was received and processed, in RFC 3339 format. This field is present only if there's an active issuer alert."
},
"hsa_fsa": {
"type": "boolean",
"description": "Indicates whether the card is linked to a Health Savings Account (HSA) or Flexible Spending Account (FSA), based on the card BIN."
}
}
},
"idempotency_key": {
"type": "string",
"description": "A unique string that identifies this CreateCard request. Keys can be any valid string and must be unique for every request. Max: 45 characters See [Idempotency keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) for more information."
},
"source_id": {
"type": "string",
"description": "The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id."
},
"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. See the [SCA Overview](https://developer.squareup.com/docs/sca-overview)."
}
},
"required": [
"PCID",
"card",
"idempotency_key",
"source_id"
]
}
```
***
## square\_payments\_create\_gift\_card
CreateGiftCard
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gift_card` | object | Yes | — | Represents a Square gift card. |
| `idempotency_key` | string | Yes | — | A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency). |
| `location_id` | string | Yes | — | The ID of the location where the gift card should be registered for reporting purposes. Gift cards can be redeemed at any of the seller's locations. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"gift_card": {
"type": "object",
"description": "Represents a Square gift card.",
"properties": {
"id": {
"type": "string",
"description": "The Square-assigned ID of the gift card."
},
"type": {
"type": "string",
"description": "Indicates the gift card type.",
"enum": [
"PHYSICAL",
"DIGITAL"
]
},
"gan_source": {
"type": "string",
"description": "Indicates the source that generated the gift card account number (GAN).",
"enum": [
"SQUARE",
"OTHER"
]
},
"state": {
"type": "string",
"description": "Indicates the gift card state.",
"enum": [
"ACTIVE",
"DEACTIVATED",
"BLOCKED",
"PENDING"
]
},
"balance_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."
},
"gan": {
"type": "string",
"description": "The gift card account number (GAN). Buyers can use the GAN to make purchases or check the gift card balance."
},
"created_at": {
"type": "string",
"description": "The timestamp when the gift card was created, in RFC 3339 format. In the case of a digital gift card, it is the time when you create a card (using the Square Point of Sale application, Seller Dashboard, or Gift Cards API). In the case of a plastic gift card, it is the time when Square associates the card with the seller at the time of activation."
},
"customer_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The IDs of the [customer profiles](entity:Customer) to whom this gift card is linked."
}
},
"required": [
"type"
]
},
"idempotency_key": {
"type": "string",
"description": "A unique identifier for this request, used to ensure idempotency. For more information, see [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
},
"location_id": {
"type": "string",
"description": "The ID of the [location](entity:Location) where the gift card should be registered for reporting purposes. Gift cards can be redeemed at any of the seller's locations."
}
},
"required": [
"PCID",
"gift_card",
"idempotency_key",
"location_id"
]
}
```
***
## square\_payments\_create\_gift\_card\_activity
CreateGiftCardActivity
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gift_card_activity` | object | Yes | — | Represents an action performed on a gift card that affects its state or balance. A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity includes a `redeem_activity_details` field that contains information about the redemption. |
| `idempotency_key` | string | Yes | — | A unique string that identifies the `CreateGiftCardActivity` request. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"gift_card_activity": {
"type": "object",
"description": "Represents an action performed on a [gift card](entity:GiftCard) that affects its state or balance. A gift card activity contains information about a specific activity type. For example, a `REDEEM` activity includes a `redeem_activity_details` field that contains information about the redemption.",
"properties": {
"id": {
"type": "string",
"description": "The Square-assigned ID of the gift card activity."
},
"type": {
"type": "string",
"description": "Indicates the type of [gift card activity](entity:GiftCardActivity).",
"enum": [
"ACTIVATE",
"LOAD",
"REDEEM",
"CLEAR_BALANCE",
"DEACTIVATE",
"ADJUST_INCREMENT",
"ADJUST_DECREMENT",
"REFUND",
"UNLINKED_ACTIVITY_REFUND",
"IMPORT",
"BLOCK",
"UNBLOCK",
"IMPORT_REVERSAL",
"TRANSFER_BALANCE_FROM",
"TRANSFER_BALANCE_TO"
]
},
"location_id": {
"type": "string",
"description": "The ID of the [business location](entity:Location) where the activity occurred."
},
"created_at": {
"type": "string",
"description": "The timestamp when the gift card activity was created, in RFC 3339 format."
},
"gift_card_id": {
"type": "string",
"description": "The gift card ID. When creating a gift card activity, `gift_card_id` is not required if `gift_card_gan` is specified."
},
"gift_card_gan": {
"type": "string",
"description": "The gift card account number (GAN). When creating a gift card activity, `gift_card_gan` is not required if `gift_card_id` is specified."
},
"gift_card_balance_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."
},
"load_activity_details": {
"type": "object",
"description": "Represents details about a `LOAD` [gift card activity type](entity:GiftCardActivityType)."
},
"activate_activity_details": {
"type": "object",
"description": "Represents details about an `ACTIVATE` [gift card activity type](entity:GiftCardActivityType)."
},
"redeem_activity_details": {
"type": "object",
"description": "Represents details about a `REDEEM` [gift card activity type](entity:GiftCardActivityType)."
},
"clear_balance_activity_details": {
"type": "object",
"description": "Represents details about a `CLEAR_BALANCE` [gift card activity type](entity:GiftCardActivityType)."
},
"deactivate_activity_details": {
"type": "object",
"description": "Represents details about a `DEACTIVATE` [gift card activity type](entity:GiftCardActivityType)."
},
"adjust_increment_activity_details": {
"type": "object",
"description": "Represents details about an `ADJUST_INCREMENT` [gift card activity type](entity:GiftCardActivityType)."
},
"adjust_decrement_activity_details": {
"type": "object",
"description": "Represents details about an `ADJUST_DECREMENT` [gift card activity type](entity:GiftCardActivityType)."
},
"refund_activity_details": {
"type": "object",
"description": "Represents details about a `REFUND` [gift card activity type](entity:GiftCardActivityType)."
},
"unlinked_activity_refund_activity_details": {
"type": "object",
"description": "Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card activity type](entity:GiftCardActivityType)."
},
"import_activity_details": {
"type": "object",
"description": "Represents details about an `IMPORT` [gift card activity type](entity:GiftCardActivityType). This activity type is used when Square imports a third-party gift card, in which case the `gan_source` of the gift card is set to `OTHER`."
},
"block_activity_details": {
"type": "object",
"description": "Represents details about a `BLOCK` [gift card activity type](entity:GiftCardActivityType)."
},
"unblock_activity_details": {
"type": "object",
"description": "Represents details about an `UNBLOCK` [gift card activity type](entity:GiftCardActivityType)."
},
"import_reversal_activity_details": {
"type": "object",
"description": "Represents details about an `IMPORT_REVERSAL` [gift card activity type](entity:GiftCardActivityType)."
},
"transfer_balance_to_activity_details": {
"type": "object",
"description": "Represents details about a `TRANSFER_BALANCE_TO` [gift card activity type](entity:GiftCardActivityType)."
},
"transfer_balance_from_activity_details": {
"type": "object",
"description": "Represents details about a `TRANSFER_BALANCE_FROM` [gift card activity type](entity:GiftCardActivityType)."
}
},
"required": [
"type",
"location_id"
]
},
"idempotency_key": {
"type": "string",
"description": "A unique string that identifies the `CreateGiftCardActivity` request."
}
},
"required": [
"PCID",
"gift_card_activity",
"idempotency_key"
]
}
```
***
## square\_payments\_create\_payment
CreatePayment
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------------------------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accept_partial_authorization` | boolean | No | — | 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 |
| `amount_money` | object | No | — | 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. |
| `app_fee_allocations` | object\[] | No | — | Details pertaining to recipients of the application fee. The sum of the amounts in the app\_fee\_allocations must equal the app\_fee\_money amount, if present. If populated, an allocation must be present for every party that expects to receive a portion of the application fee, including the application developer. |
| `app_fee_money` | object | No | — | 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. |
| `autocomplete` | boolean | No | — | 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 |
| `billing_address` | object | No | — | Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). |
| `buyer_email_address` | string | No | — | The buyer's email address. |
| `buyer_phone_number` | string | No | — | The buyer's phone number. Must follow the following format: 1. A leading + symbol (followed by a country code) 2. The phone number can contain spaces and the special characters `(` , `)` , `-` , and `.`. Alphabetical characters aren't allowed. 3. The phone number must contain between 9 and 16 digits. |
| `cash_details` | object | No | — | Stores details about a cash payment. Contains only non-confidential information. For more information, see [Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments). |
| `customer_details` | object | No | — | Details about the customer making the payment. |
| `customer_id` | string | No | — | The Customer ID of the customer associated with the payment. This is required if the `source_id` refers to a card on file created using the Cards API. |
| `delay_action` | string | No | — | The action to be applied to the payment when the `delay_duration` has elapsed. The action must be CANCEL or COMPLETE. For more information, see [Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). Default: CANCEL |
| `delay_duration` | string | No | — | The duration of time after the payment's creation when Square automatically either completes or cancels the payment depending on the `delay_action` field value. For more information, see [Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). This parameter should be specified as a time duration, in RFC 3339 format. Note: This feature is only supported for card payments. This parameter can only be set for a delayed capture payment (`autocomplete=false`). Default: - Card-present payments: "PT36H" (36 hours) from the creation time. - Card-not-present payments: "P7D" (7 days) from the creation time. |
| `external_details` | object | No | — | Stores details about an external payment. Contains only non-confidential information. For more information, see [Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments). |
| `idempotency_key` | string | Yes | — | 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). |
| `location_id` | string | No | — | 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. |
| `note` | string | No | — | An optional note to be entered by the developer when creating a payment. |
| `offline_payment_details` | object | No | — | Details specific to offline payments. |
| `order_id` | string | No | — | Associates a previously created order with this payment. |
| `reference_id` | string | No | — | A user-defined ID to associate with the payment. You can use this field to associate the payment to an entity in an external system (for example, you might specify an order ID that is generated by a third-party shopping cart). |
| `shipping_address` | object | No | — | Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses). |
| `source_id` | string | Yes | — | The ID for the source of funds for this payment. This could be a payment token generated by the Web Payments SDK for any of its [supported methods](https://developer.squareup.com/docs/web-payments/overview#explore-payment-methods), including cards, bank transfers, Afterpay or Cash App Pay. If recording a payment that the seller received outside of Square, specify either "CASH" or "EXTERNAL". For more information, see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments). |
| `statement_description_identifier` | string | No | — | Optional additional payment information to include on the customer's card statement as part of the statement description. This can be, for example, an invoice number, ticket number, or short description that uniquely identifies the purchase. Note that the `statement_description_identifier` might get truncated on the statement description to fit the required information including the Square identifier (SQ \*) and name of the seller taking the payment. |
| `team_member_id` | string | No | — | An optional TeamMember ID to associate with this payment. |
| `tip_money` | object | No | — | 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. |
| `verification_token` | string | No | — | 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). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"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"
},
"amount_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.",
"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."
},
"currency": {
"type": "string",
"description": "Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).",
"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"
]
}
}
},
"app_fee_allocations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"charge_id": {
"type": "string",
"description": "The ID of the app fee charge."
},
"amount_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."
}
}
},
"description": "Details pertaining to recipients of the application fee. The sum of the amounts in the app_fee_allocations must equal the app_fee_money amount, if present. If populated, an allocation must be present for every party that expects to receive a portion of the application fee, including the application developer."
},
"app_fee_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.",
"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."
},
"currency": {
"type": "string",
"description": "Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).",
"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"
]
}
}
},
"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"
},
"billing_address": {
"type": "object",
"description": "Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).",
"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)."
},
"address_line_2": {
"type": "string",
"description": "The second line of the address, if any."
},
"address_line_3": {
"type": "string",
"description": "The third line of the address, if any."
},
"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)."
},
"sublocality": {
"type": "string",
"description": "A civil region within the address's `locality`, if any."
},
"sublocality_2": {
"type": "string",
"description": "A civil region within the address's `sublocality`, if any."
},
"sublocality_3": {
"type": "string",
"description": "A civil region within the address's `sublocality_2`, if any."
},
"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)."
},
"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."
},
"administrative_district_level_3": {
"type": "string",
"description": "A civil entity within the address's `administrative_district_level_2`, if any."
},
"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)."
},
"country": {
"type": "string",
"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).",
"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"
]
},
"first_name": {
"type": "string",
"description": "Optional first name when it's representing recipient."
},
"last_name": {
"type": "string",
"description": "Optional last name when it's representing recipient."
}
}
},
"buyer_email_address": {
"type": "string",
"description": "The buyer's email address."
},
"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."
},
"cash_details": {
"type": "object",
"description": "Stores details about a cash payment. Contains only non-confidential information. For more information, see [Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments).",
"properties": {
"buyer_supplied_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."
},
"change_back_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."
}
},
"required": [
"buyer_supplied_money"
]
},
"customer_details": {
"type": "object",
"description": "Details about the customer making the payment.",
"properties": {
"customer_initiated": {
"type": "boolean",
"description": "Indicates whether the customer initiated the payment."
},
"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)."
}
}
},
"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."
},
"delay_action": {
"type": "string",
"description": "The action to be applied to the payment when the `delay_duration` has elapsed. The action must be CANCEL or COMPLETE. For more information, see [Time Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). Default: CANCEL"
},
"delay_duration": {
"type": "string",
"description": "The duration of time after the payment's creation when Square automatically either completes or cancels the payment depending on the `delay_action` field value. For more information, see [Time threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). This parameter should be specified as a time duration, in RFC 3339 format. Note: This feature is only supported for card payments. This parameter can only be set for a delayed capture payment (`autocomplete=false`). Default: - Card-present payments: \"PT36H\" (36 hours) from the creation time. - Card-not-present payments: \"P7D\" (7 days) from the creation time."
},
"external_details": {
"type": "object",
"description": "Stores details about an external payment. Contains only non-confidential information. For more information, see [Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments).",
"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."
},
"source": {
"type": "string",
"description": "A description of the external payment source. For example, \"Food Delivery Service\"."
},
"source_id": {
"type": "string",
"description": "An ID to associate the payment to its originating source."
},
"source_fee_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."
}
},
"required": [
"type",
"source"
]
},
"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)."
},
"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."
},
"note": {
"type": "string",
"description": "An optional note to be entered by the developer when creating a payment."
},
"offline_payment_details": {
"type": "object",
"description": "Details specific to offline payments.",
"properties": {
"client_created_at": {
"type": "string",
"description": "The client-side timestamp of when the offline payment was created, in RFC 3339 format."
}
}
},
"order_id": {
"type": "string",
"description": "Associates a previously created order with this payment."
},
"reference_id": {
"type": "string",
"description": "A user-defined ID to associate with the payment. You can use this field to associate the payment to an entity in an external system (for example, you might specify an order ID that is generated by a third-party shopping cart)."
},
"shipping_address": {
"type": "object",
"description": "Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).",
"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)."
},
"address_line_2": {
"type": "string",
"description": "The second line of the address, if any."
},
"address_line_3": {
"type": "string",
"description": "The third line of the address, if any."
},
"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)."
},
"sublocality": {
"type": "string",
"description": "A civil region within the address's `locality`, if any."
},
"sublocality_2": {
"type": "string",
"description": "A civil region within the address's `sublocality`, if any."
},
"sublocality_3": {
"type": "string",
"description": "A civil region within the address's `sublocality_2`, if any."
},
"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)."
},
"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."
},
"administrative_district_level_3": {
"type": "string",
"description": "A civil entity within the address's `administrative_district_level_2`, if any."
},
"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)."
},
"country": {
"type": "string",
"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).",
"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"
]
},
"first_name": {
"type": "string",
"description": "Optional first name when it's representing recipient."
},
"last_name": {
"type": "string",
"description": "Optional last name when it's representing recipient."
}
}
},
"source_id": {
"type": "string",
"description": "The ID for the source of funds for this payment. This could be a payment token generated by the Web Payments SDK for any of its [supported methods](https://developer.squareup.com/docs/web-payments/overview#explore-payment-methods), including cards, bank transfers, Afterpay or Cash App Pay. If recording a payment that the seller received outside of Square, specify either \"CASH\" or \"EXTERNAL\". For more information, see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments)."
},
"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."
},
"team_member_id": {
"type": "string",
"description": "An optional [TeamMember](entity:TeamMember) ID to associate with this payment."
},
"tip_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.",
"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."
},
"currency": {
"type": "string",
"description": "Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).",
"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"
]
}
}
},
"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)."
}
},
"required": [
"PCID",
"idempotency_key",
"source_id"
]
}
```
***
## square\_payments\_create\_payment\_link
CreatePaymentLink
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checkout_options` | object | No | — | Checkout Options |
| `description` | string | No | — | A description of the payment link. You provide this optional description that is useful in your application context. It is not used anywhere. |
| `idempotency_key` | string | No | — | A unique string that identifies this `CreatePaymentLinkRequest` request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency). |
| `order` | object | No | — | Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data. |
| `payment_note` | string | No | — | A note for the payment. After processing the payment, Square adds this note to the resulting `Payment`. |
| `pre_populated_data` | object | No | — | Describes buyer data to prepopulate in the payment form. For more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations). |
| `quick_pay` | object | No | — | Describes an ad hoc item and price to generate a quick pay checkout link. For more information, see [Quick Pay Checkout](https://developer.squareup.com/docs/checkout-api/quick-pay-checkout). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"checkout_options": {
"type": "object",
"description": "Checkout Options",
"properties": {
"allow_tipping": {
"type": "boolean",
"description": "Indicates whether the payment allows tipping."
},
"custom_fields": {
"type": "array",
"items": {
"type": "object"
},
"description": "The custom fields requesting information from the buyer."
},
"subscription_plan_id": {
"type": "string",
"description": "The ID of the subscription plan for the buyer to pay and subscribe. For more information, see [Subscription Plan Checkout](https://developer.squareup.com/docs/checkout-api/subscription-plan-checkout)."
},
"redirect_url": {
"type": "string",
"description": "The confirmation page URL to redirect the buyer to after Square processes the payment."
},
"merchant_support_email": {
"type": "string",
"description": "The email address that buyers can use to contact the seller."
},
"ask_for_shipping_address": {
"type": "boolean",
"description": "Indicates whether to include the address fields in the payment form."
},
"accepted_payment_methods": {
"type": "object",
"description": "Accepted Payment Methods"
},
"app_fee_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."
},
"shipping_fee": {
"type": "object",
"description": "Shipping Fee"
},
"enable_coupon": {
"type": "boolean",
"description": "Indicates whether to include the `Add coupon` section for the buyer to provide a Square marketing coupon in the payment form."
},
"enable_loyalty": {
"type": "boolean",
"description": "Indicates whether to include the `REWARDS` section for the buyer to opt in to loyalty, redeem rewards in the payment form, or both."
}
}
},
"description": {
"type": "string",
"description": "A description of the payment link. You provide this optional description that is useful in your application context. It is not used anywhere."
},
"idempotency_key": {
"type": "string",
"description": "A unique string that identifies this `CreatePaymentLinkRequest` request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)."
},
"order": {
"type": "object",
"description": "Contains all information related to a single order to process with Square, including line items that specify the products to purchase. `Order` objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.",
"properties": {
"id": {
"type": "string",
"description": "The order's unique ID."
},
"location_id": {
"type": "string",
"description": "The ID of the seller location that this order is associated with."
},
"reference_id": {
"type": "string",
"description": "A client-specified ID to associate an entity in another system with this order."
},
"source": {
"type": "object",
"description": "Represents the origination details of an order."
},
"customer_id": {
"type": "string",
"description": "The ID of the [customer](entity:Customer) associated with the order. You should specify a `customer_id` on the order (or the payment) to ensure that transactions are reliably linked to customers. Omitting this field might result in the creation of new [instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles)."
},
"line_items": {
"type": "array",
"items": {
"type": "object"
},
"description": "The line items included in the order."
},
"taxes": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of all taxes associated with the order. Taxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an `OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes with `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item. On reads, each tax in the list includes the total amount of that tax applied to the order. __IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated `line_items.taxes` field results in an error. Use `line_items.applied_taxes` instead."
},
"discounts": {
"type": "array",
"items": {
"type": "object"
},
"description": "The list of all discounts associated with the order. Discounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`, an `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to. For discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount` for every line item. __IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated `line_items.discounts` field results in an error. Use `line_items.applied_discounts` instead."
},
"service_charges": {
"type": "array",
"items": {
"type": "object"
},
"description": "A list of service charges applied to the order."
},
"fulfillments": {
"type": "array",
"items": {
"type": "object"
},
"description": "Details about order fulfillment. Orders can only be created with at most one fulfillment. However, orders returned by the API might contain multiple fulfillments."
},
"returns": {
"type": "array",
"items": {
"type": "object"
},
"description": "A collection of items from sale orders being returned in this one. Normally part of an itemized return or exchange. There is exactly one `Return` object per sale `Order` being referenced."
},
"return_amounts": {
"type": "object",
"description": "A collection of various money amounts."
},
"net_amounts": {
"type": "object",
"description": "A collection of various money amounts."
},
"rounding_adjustment": {
"type": "object",
"description": "A rounding adjustment of the money being returned. Commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency."
},
"tenders": {
"type": "array",
"items": {
"type": "object"
},
"description": "The tenders that were used to pay for the order."
},
"refunds": {
"type": "array",
"items": {
"type": "object"
},
"description": "The refunds that are part of this order."
},
"metadata": {
"type": "object",
"description": "Application-defined data attached to this order. Metadata fields are intended to store descriptive references or associations with an entity in another system or store brief information about the object. Square does not process this field; it only stores and returns it in relevant API calls. Do not use metadata to store any sensitive information (such as personally identifiable information or card details). Keys written by applications must be 60 characters or less and must be in the character set `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see [Metadata](https://developer.squareup.com/docs/build-basics/metadata)."
},
"created_at": {
"type": "string",
"description": "The timestamp for when the order was created, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")."
},
"updated_at": {
"type": "string",
"description": "The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, \"2016-09-04T23:59:33.123Z\")."
},
"closed_at": {
"type": "string",
"description": "The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example \"2016-09-04T23:59:33.123Z\")."
},
"state": {
"type": "string",
"description": "The state of the order.",
"enum": [
"OPEN",
"COMPLETED",
"CANCELED",
"DRAFT"
]
},
"version": {
"type": "integer",
"description": "The version number, which is incremented each time an update is committed to the order. Orders not created through the API do not include a version number and therefore cannot be updated. [Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders)."
},
"total_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."
},
"total_tax_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."
},
"total_discount_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."
},
"total_tip_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."
},
"total_service_charge_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."
},
"ticket_name": {
"type": "string",
"description": "A short-term identifier for the order (such as a customer first name, table number, or auto-generated order number that resets daily)."
},
"pricing_options": {
"type": "object",
"description": "Pricing options for an order. The options affect how the order's price is calculated. They can be used, for example, to apply automatic price adjustments that are based on preconfigured [pricing rules](entity:CatalogPricingRule)."
},
"rewards": {
"type": "array",
"items": {
"type": "object"
},
"description": "A set-like list of Rewards that have been added to the Order."
},
"net_amount_due_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."
}
},
"required": [
"location_id"
]
},
"payment_note": {
"type": "string",
"description": "A note for the payment. After processing the payment, Square adds this note to the resulting `Payment`."
},
"pre_populated_data": {
"type": "object",
"description": "Describes buyer data to prepopulate in the payment form. For more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).",
"properties": {
"buyer_email": {
"type": "string",
"description": "The buyer email to prepopulate in the payment form."
},
"buyer_phone_number": {
"type": "string",
"description": "The buyer phone number to prepopulate in the payment form."
},
"buyer_address": {
"type": "object",
"description": "Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)."
}
}
},
"quick_pay": {
"type": "object",
"description": "Describes an ad hoc item and price to generate a quick pay checkout link. For more information, see [Quick Pay Checkout](https://developer.squareup.com/docs/checkout-api/quick-pay-checkout).",
"properties": {
"name": {
"type": "string",
"description": "The ad hoc item name. In the resulting `Order`, this name appears as the line item name."
},
"price_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."
},
"location_id": {
"type": "string",
"description": "The ID of the business location the checkout is associated with."
}
},
"required": [
"name",
"price_money",
"location_id"
]
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_delete\_payment\_link
DeletePaymentLink
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------------- |
| `id` | string | Yes | — | The ID of the payment link to delete. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The ID of the payment link to delete."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## square\_payments\_disable\_bank\_account
DisableBankAccount
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | -------------------------------------- |
| `bank_account_id` | string | Yes | — | The ID of the bank account to disable. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"bank_account_id": {
"type": "string",
"description": "The ID of the bank account to disable."
}
},
"required": [
"PCID",
"bank_account_id"
]
}
```
***
## square\_payments\_disable\_card
DisableCard
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------- |
| `card_id` | string | Yes | — | Unique ID for the desired Card. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"card_id": {
"type": "string",
"description": "Unique ID for the desired Card."
}
},
"required": [
"PCID",
"card_id"
]
}
```
***
## square\_payments\_get\_bank\_account
GetBankAccount
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ---------------------------------------------- |
| `bank_account_id` | string | Yes | — | Square-issued ID of the desired `BankAccount`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"bank_account_id": {
"type": "string",
"description": "Square-issued ID of the desired `BankAccount`."
}
},
"required": [
"PCID",
"bank_account_id"
]
}
```
***
## square\_payments\_get\_bank\_account\_by\_v1id
GetBankAccountByV1Id
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v1_bank_account_id` | string | Yes | — | Connect V1 ID of the desired `BankAccount`. For more information, see [Retrieve a bank account by using an ID issued by V1 Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api#retrieve-a-bank-account-by-using-an-id-issued-by-v1-bank-accounts-api). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"v1_bank_account_id": {
"type": "string",
"description": "Connect V1 ID of the desired `BankAccount`. For more information, see [Retrieve a bank account by using an ID issued by V1 Bank Accounts API](https://developer.squareup.com/docs/bank-accounts-api#retrieve-a-bank-account-by-using-an-id-issued-by-v1-bank-accounts-api)."
}
},
"required": [
"PCID",
"v1_bank_account_id"
]
}
```
***
## square\_payments\_get\_payment
GetPayment
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | ------------------------------------ |
| `payment_id` | string | Yes | — | A unique ID for the desired payment. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"payment_id": {
"type": "string",
"description": "A unique ID for the desired payment."
}
},
"required": [
"PCID",
"payment_id"
]
}
```
***
## square\_payments\_get\_payment\_refund
GetPaymentRefund
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------- | ------ | -------- | ------- | ---------------------------------------------- |
| `refund_id` | string | Yes | — | The unique ID for the desired `PaymentRefund`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"refund_id": {
"type": "string",
"description": "The unique ID for the desired `PaymentRefund`."
}
},
"required": [
"PCID",
"refund_id"
]
}
```
***
## square\_payments\_get\_payout
GetPayout
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------- | ------ | -------- | ------- | ----------------------------------------------------- |
| `payout_id` | string | Yes | — | The ID of the payout to retrieve the information for. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"payout_id": {
"type": "string",
"description": "The ID of the payout to retrieve the information for."
}
},
"required": [
"PCID",
"payout_id"
]
}
```
***
## square\_payments\_link\_customer\_to\_gift\_card
LinkCustomerToGiftCard
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------ | -------- | ------- | ------------------------------------------------ |
| `gift_card_id` | string | Yes | — | The ID of the gift card to be linked. |
| `customer_id` | string | Yes | — | The ID of the customer to link to the gift card. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"gift_card_id": {
"type": "string",
"description": "The ID of the gift card to be linked."
},
"customer_id": {
"type": "string",
"description": "The ID of the customer to link to the gift card."
}
},
"required": [
"PCID",
"gift_card_id",
"customer_id"
]
}
```
***
## square\_payments\_list\_bank\_accounts
ListBankAccounts
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` | string | No | — | The pagination cursor returned by a previous call to this endpoint. Use it in the next `ListBankAccounts` request to retrieve the next set of results. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information. |
| `limit` | integer | No | — | Upper limit on the number of bank accounts to return in the response. Currently, 1000 is the largest supported limit. You can specify a limit of up to 1000 bank accounts. This is also the default limit. |
| `location_id` | string | No | — | Location ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific location. |
| `customer_id` | string | No | — | Customer ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific customer. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"cursor": {
"type": "string",
"description": "The pagination cursor returned by a previous call to this endpoint. Use it in the next `ListBankAccounts` request to retrieve the next set of results. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information."
},
"limit": {
"type": "integer",
"description": "Upper limit on the number of bank accounts to return in the response. Currently, 1000 is the largest supported limit. You can specify a limit of up to 1000 bank accounts. This is also the default limit."
},
"location_id": {
"type": "string",
"description": "Location ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific location."
},
"customer_id": {
"type": "string",
"description": "Customer ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific customer."
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_list\_cards
ListCards
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------ | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` | string | No | — | A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information. |
| `customer_id` | string | No | — | Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned. |
| `include_disabled` | boolean | No | — | Includes disabled cards. By default, all enabled cards owned by the merchant are returned. |
| `reference_id` | string | No | — | Limit results to cards associated with the reference\_id supplied. |
| `sort_order` | string | No | — | Sorts the returned list by when the card was created with the specified order. This field defaults to ASC. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"cursor": {
"type": "string",
"description": "A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination) for more information."
},
"customer_id": {
"type": "string",
"description": "Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned."
},
"include_disabled": {
"type": "boolean",
"description": "Includes disabled cards. By default, all enabled cards owned by the merchant are returned."
},
"reference_id": {
"type": "string",
"description": "Limit results to cards associated with the reference_id supplied."
},
"sort_order": {
"type": "string",
"description": "Sorts the returned list by when the card was created with the specified order. This field defaults to ASC.",
"enum": [
"DESC",
"ASC"
]
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_list\_cash\_drawer\_shift\_events
ListCashDrawerShiftEvents
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------- |
| `location_id` | string | Yes | — | The ID of the location to list cash drawer shifts for. |
| `shift_id` | string | Yes | — | The shift ID. |
| `limit` | integer | No | — | Number of resources to be returned in a page of results (200 by default, 1000 max). |
| `cursor` | string | No | — | Opaque cursor for fetching the next page of results. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location to list cash drawer shifts for."
},
"shift_id": {
"type": "string",
"description": "The shift ID."
},
"limit": {
"type": "integer",
"description": "Number of resources to be returned in a page of results (200 by default, 1000 max)."
},
"cursor": {
"type": "string",
"description": "Opaque cursor for fetching the next page of results."
}
},
"required": [
"PCID",
"location_id",
"shift_id"
]
}
```
***
## square\_payments\_list\_cash\_drawer\_shifts
ListCashDrawerShifts
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `location_id` | string | Yes | — | The ID of the location to query for a list of cash drawer shifts. |
| `sort_order` | string | No | — | The order in which cash drawer shifts are listed in the response, based on their opened\_at field. Default value: ASC |
| `begin_time` | string | No | — | The inclusive start time of the query on opened\_at, in ISO 8601 format. |
| `end_time` | string | No | — | The exclusive end date of the query on opened\_at, in ISO 8601 format. |
| `limit` | integer | No | — | Number of cash drawer shift events in a page of results (200 by default, 1000 max). |
| `cursor` | string | No | — | Opaque cursor for fetching the next page of results. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location to query for a list of cash drawer shifts."
},
"sort_order": {
"type": "string",
"description": "The order in which cash drawer shifts are listed in the response, based on their opened_at field. Default value: ASC",
"enum": [
"DESC",
"ASC"
]
},
"begin_time": {
"type": "string",
"description": "The inclusive start time of the query on opened_at, in ISO 8601 format."
},
"end_time": {
"type": "string",
"description": "The exclusive end date of the query on opened_at, in ISO 8601 format."
},
"limit": {
"type": "integer",
"description": "Number of cash drawer shift events in a page of results (200 by default, 1000 max)."
},
"cursor": {
"type": "string",
"description": "Opaque cursor for fetching the next page of results."
}
},
"required": [
"PCID",
"location_id"
]
}
```
***
## square\_payments\_list\_gift\_card\_activities
ListGiftCardActivities
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gift_card_id` | string | No | — | If a gift card ID is provided, the endpoint returns activities related to the specified gift card. Otherwise, the endpoint returns all gift card activities for the seller. |
| `type` | string | No | — | If a type is provided, the endpoint returns gift card activities of the specified type. Otherwise, the endpoint returns all types of gift card activities. |
| `location_id` | string | No | — | If a location ID is provided, the endpoint returns gift card activities for the specified location. Otherwise, the endpoint returns gift card activities for all locations. |
| `begin_time` | string | No | — | The timestamp for the beginning of the reporting period, in RFC 3339 format. This start time is inclusive. The default value is the current time minus one year. |
| `end_time` | string | No | — | The timestamp for the end of the reporting period, in RFC 3339 format. This end time is inclusive. The default value is the current time. |
| `limit` | integer | No | — | If a limit is provided, the endpoint returns the specified number of results (or fewer) per page. The maximum value is 100. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
| `cursor` | string | No | — | A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
| `sort_order` | string | No | — | The order in which the endpoint returns the activities, based on `created_at`. - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default). |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"gift_card_id": {
"type": "string",
"description": "If a gift card ID is provided, the endpoint returns activities related to the specified gift card. Otherwise, the endpoint returns all gift card activities for the seller."
},
"type": {
"type": "string",
"description": "If a [type](entity:GiftCardActivityType) is provided, the endpoint returns gift card activities of the specified type. Otherwise, the endpoint returns all types of gift card activities."
},
"location_id": {
"type": "string",
"description": "If a location ID is provided, the endpoint returns gift card activities for the specified location. Otherwise, the endpoint returns gift card activities for all locations."
},
"begin_time": {
"type": "string",
"description": "The timestamp for the beginning of the reporting period, in RFC 3339 format. This start time is inclusive. The default value is the current time minus one year."
},
"end_time": {
"type": "string",
"description": "The timestamp for the end of the reporting period, in RFC 3339 format. This end time is inclusive. The default value is the current time."
},
"limit": {
"type": "integer",
"description": "If a limit is provided, the endpoint returns the specified number of results (or fewer) per page. The maximum value is 100. The default value is 50. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
},
"cursor": {
"type": "string",
"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. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
},
"sort_order": {
"type": "string",
"description": "The order in which the endpoint returns the activities, based on `created_at`. - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default)."
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_list\_gift\_cards
ListGiftCards
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | No | — | If a type is provided, the endpoint returns gift cards of the specified type. Otherwise, the endpoint returns gift cards of all types. |
| `state` | string | No | — | If a state is provided, the endpoint returns the gift cards in the specified state. Otherwise, the endpoint returns the gift cards of all states. |
| `limit` | integer | No | — | If a limit is provided, the endpoint returns only the specified number of results per page. The maximum value is 200. The default value is 30. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
| `cursor` | string | No | — | A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination). |
| `customer_id` | string | No | — | If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"type": {
"type": "string",
"description": "If a [type](entity:GiftCardType) is provided, the endpoint returns gift cards of the specified type. Otherwise, the endpoint returns gift cards of all types."
},
"state": {
"type": "string",
"description": "If a [state](entity:GiftCardStatus) is provided, the endpoint returns the gift cards in the specified state. Otherwise, the endpoint returns the gift cards of all states."
},
"limit": {
"type": "integer",
"description": "If a limit is provided, the endpoint returns only the specified number of results per page. The maximum value is 200. The default value is 30. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
},
"cursor": {
"type": "string",
"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. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)."
},
"customer_id": {
"type": "string",
"description": "If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer."
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_list\_payment\_links
ListPaymentLinks
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cursor` | string | No | — | A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination). |
| `limit` | integer | No | — | A limit on the number of results to return per page. The limit is advisory and the implementation might return more or less results. If the supplied limit is negative, zero, or greater than the maximum limit of 1000, it is ignored. Default value: `100` |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"cursor": {
"type": "string",
"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. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
},
"limit": {
"type": "integer",
"description": "A limit on the number of results to return per page. The limit is advisory and the implementation might return more or less results. If the supplied limit is negative, zero, or greater than the maximum limit of 1000, it is ignored. Default value: `100`"
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_list\_payment\_refunds
ListPaymentRefunds
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `begin_time` | string | No | — | Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `created_at` field for each `PaymentRefund`. Default: The current time minus one year. |
| `end_time` | string | No | — | Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `created_at` field for each `PaymentRefund`. Default: The current time. |
| `sort_order` | string | No | — | The order in which results are listed by `PaymentRefund.created_at`: - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default). |
| `cursor` | string | No | — | 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). |
| `location_id` | string | No | — | Limit results to the location supplied. By default, results are returned for all locations associated with the seller. |
| `status` | string | No | — | If provided, only refunds with the given status are returned. For a list of refund status values, see PaymentRefund. Default: If omitted, refunds are returned regardless of their status. |
| `source_type` | string | No | — | If provided, only returns refunds whose payments have the indicated source type. Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`. For information about these payment source types, see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments). Default: If omitted, refunds are returned regardless of the source type. |
| `limit` | integer | No | — | The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. If the supplied value is greater than 100, no more than 100 results are returned. Default: 100 |
| `updated_at_begin_time` | string | No | — | Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `updated_at` field for each `PaymentRefund`. Default: If omitted, the time range starts at `begin_time`. |
| `updated_at_end_time` | string | No | — | Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `updated_at` field for each `PaymentRefund`. Default: The current time. |
| `sort_field` | string | No | — | The field used to sort results by. The default is `CREATED_AT`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"begin_time": {
"type": "string",
"description": "Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `created_at` field for each `PaymentRefund`. Default: The current time minus one year."
},
"end_time": {
"type": "string",
"description": "Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `created_at` field for each `PaymentRefund`. Default: The current time."
},
"sort_order": {
"type": "string",
"description": "The order in which results are listed by `PaymentRefund.created_at`: - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default)."
},
"cursor": {
"type": "string",
"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)."
},
"location_id": {
"type": "string",
"description": "Limit results to the location supplied. By default, results are returned for all locations associated with the seller."
},
"status": {
"type": "string",
"description": "If provided, only refunds with the given status are returned. For a list of refund status values, see [PaymentRefund](entity:PaymentRefund). Default: If omitted, refunds are returned regardless of their status."
},
"source_type": {
"type": "string",
"description": "If provided, only returns refunds whose payments have the indicated source type. Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and `EXTERNAL`. For information about these payment source types, see [Take Payments](https://developer.squareup.com/docs/payments-api/take-payments). Default: If omitted, refunds are returned regardless of the source type."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. If the supplied value is greater than 100, no more than 100 results are returned. Default: 100"
},
"updated_at_begin_time": {
"type": "string",
"description": "Indicates the start of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `updated_at` field for each `PaymentRefund`. Default: If omitted, the time range starts at `begin_time`."
},
"updated_at_end_time": {
"type": "string",
"description": "Indicates the end of the time range to retrieve each `PaymentRefund` for, in RFC 3339 format. The range is determined using the `updated_at` field for each `PaymentRefund`. Default: The current time."
},
"sort_field": {
"type": "string",
"description": "The field used to sort results by. The default is `CREATED_AT`.",
"enum": [
"CREATED_AT",
"UPDATED_AT"
]
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_list\_payments
ListPayments
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `begin_time` | string | No | — | Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `created_at` field for each Payment. Inclusive. Default: The current time minus one year. |
| `end_time` | string | No | — | Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `created_at` field for each Payment. Default: The current time. |
| `sort_order` | string | No | — | The order in which results are listed by `ListPaymentsRequest.sort_field`: - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default). |
| `cursor` | string | No | — | 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). |
| `location_id` | string | No | — | Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller. |
| `total` | integer | No | — | The exact amount in the `total_money` for a payment. |
| `last_4` | string | No | — | The last four digits of a payment card. |
| `card_brand` | string | No | — | The brand of the payment card (for example, VISA). |
| `limit` | integer | No | — | The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100` |
| `is_offline_payment` | boolean | No | — | Whether the payment was taken offline or not. |
| `offline_begin_time` | string | No | — | Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the `offline_payment_details.client_created_at` field for each Payment. If set, payments without a value set in `offline_payment_details.client_created_at` will not be returned. Default: The current time. |
| `offline_end_time` | string | No | — | Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the `offline_payment_details.client_created_at` field for each Payment. If set, payments without a value set in `offline_payment_details.client_created_at` will not be returned. Default: The current time. |
| `updated_at_begin_time` | string | No | — | Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `updated_at` field for each Payment. |
| `updated_at_end_time` | string | No | — | Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `updated_at` field for each Payment. |
| `sort_field` | string | No | — | The field used to sort results by. The default is `CREATED_AT`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"begin_time": {
"type": "string",
"description": "Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `created_at` field for each Payment. Inclusive. Default: The current time minus one year."
},
"end_time": {
"type": "string",
"description": "Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the `created_at` field for each Payment. Default: The current time."
},
"sort_order": {
"type": "string",
"description": "The order in which results are listed by `ListPaymentsRequest.sort_field`: - `ASC` - Oldest to newest. - `DESC` - Newest to oldest (default)."
},
"cursor": {
"type": "string",
"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)."
},
"location_id": {
"type": "string",
"description": "Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller."
},
"total": {
"type": "integer",
"description": "The exact amount in the `total_money` for a payment."
},
"last_4": {
"type": "string",
"description": "The last four digits of a payment card."
},
"card_brand": {
"type": "string",
"description": "The brand of the payment card (for example, VISA)."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100`"
},
"is_offline_payment": {
"type": "boolean",
"description": "Whether the payment was taken offline or not."
},
"offline_begin_time": {
"type": "string",
"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."
},
"offline_end_time": {
"type": "string",
"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."
},
"updated_at_begin_time": {
"type": "string",
"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."
},
"updated_at_end_time": {
"type": "string",
"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."
},
"sort_field": {
"type": "string",
"description": "The field used to sort results by. The default is `CREATED_AT`.",
"enum": [
"CREATED_AT",
"OFFLINE_CREATED_AT",
"UPDATED_AT"
]
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_list\_payout\_entries
ListPayoutEntries
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------ | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payout_id` | string | Yes | — | The ID of the payout to retrieve the information for. |
| `sort_order` | string | No | — | The order in which payout entries are listed. |
| `cursor` | string | No | — | 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). If request parameters change between requests, subsequent results may contain duplicates or missing records. |
| `limit` | integer | No | — | The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100` |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"payout_id": {
"type": "string",
"description": "The ID of the payout to retrieve the information for."
},
"sort_order": {
"type": "string",
"description": "The order in which payout entries are listed.",
"enum": [
"DESC",
"ASC"
]
},
"cursor": {
"type": "string",
"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). If request parameters change between requests, subsequent results may contain duplicates or missing records."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100`"
}
},
"required": [
"PCID",
"payout_id"
]
}
```
***
## square\_payments\_list\_payouts
ListPayouts
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `location_id` | string | No | — | The ID of the location for which to list the payouts. By default, payouts are returned for the default (main) location associated with the seller. |
| `status` | string | No | — | If provided, only payouts with the given status are returned. |
| `begin_time` | string | No | — | The timestamp for the beginning of the payout creation time, in RFC 3339 format. Inclusive. Default: The current time minus one year. |
| `end_time` | string | No | — | The timestamp for the end of the payout creation time, in RFC 3339 format. Default: The current time. |
| `sort_order` | string | No | — | The order in which payouts are listed. |
| `cursor` | string | No | — | 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). If request parameters change between requests, subsequent results may contain duplicates or missing records. |
| `limit` | integer | No | — | The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100` |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location for which to list the payouts. By default, payouts are returned for the default (main) location associated with the seller."
},
"status": {
"type": "string",
"description": "If provided, only payouts with the given status are returned.",
"enum": [
"SENT",
"FAILED",
"PAID"
]
},
"begin_time": {
"type": "string",
"description": "The timestamp for the beginning of the payout creation time, in RFC 3339 format. Inclusive. Default: The current time minus one year."
},
"end_time": {
"type": "string",
"description": "The timestamp for the end of the payout creation time, in RFC 3339 format. Default: The current time."
},
"sort_order": {
"type": "string",
"description": "The order in which payouts are listed.",
"enum": [
"DESC",
"ASC"
]
},
"cursor": {
"type": "string",
"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). If request parameters change between requests, subsequent results may contain duplicates or missing records."
},
"limit": {
"type": "integer",
"description": "The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: `100`"
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_refund\_payment
RefundPayment
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount_money` | object | Yes | — | 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. | |
| `app_fee_allocations` | object\[] | No | — | Details pertaining to contributors to the refund of the application fee. The sum of the amounts in the app\_fee\_allocations must equal the app\_fee\_money amount, if present. If populated, an allocation must be present for every party that expects to contribute a portion of the refunded application fee, including the application developer. | |
| `app_fee_money` | object | No | — | 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. | |
| `cash_details` | object | No | — | Stores details about a cash refund. Contains only non-confidential information. | |
| `customer_id` | string | null | No | — | The Customer ID of the customer associated with the refund. This is required if the `destination_id` refers to a card on file created using the Cards API. Only allowed when `unlinked=true`. |
| `destination_id` | string | null | No | — | The ID indicating where funds will be refunded to. Required for unlinked refunds. For more information, see [Process an Unlinked Refund](https://developer.squareup.com/docs/refunds-api/unlinked-refunds). For refunds linked to Square payments, `destination_id` is usually omitted; in this case, funds will be returned to the original payment source. The field may be specified in order to request a cross-method refund to a gift card. For more information, see [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund-payments#cross-method-refunds-to-gift-cards). |
| `external_details` | object | No | — | Stores details about an external refund. Contains only non-confidential information. | |
| `idempotency_key` | string | Yes | — | A unique string that identifies this `RefundPayment` request. The key can be any valid string but must be unique for every `RefundPayment` request. Keys are limited to a max of 45 characters - however, the number of allowed characters might be less than 45, if multi-byte characters are used. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency). | |
| `location_id` | string | null | No | — | The location ID associated with the unlinked refund. Required for requests specifying `unlinked=true`. Otherwise, if included when `unlinked=false`, will throw an error. |
| `payment_id` | string | null | No | — | The unique ID of the payment being refunded. Required when unlinked=false, otherwise must not be set. |
| `payment_version_token` | string | null | No | — | Used for optimistic concurrency. This opaque token identifies the current `Payment` version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION\_MISMATCH error is returned. If the versions match, or the field is not provided, the refund proceeds as normal. |
| `reason` | string | null | No | — | A description of the reason for the refund. |
| `team_member_id` | string | null | No | — | An optional TeamMember ID to associate with this refund. |
| `unlinked` | boolean | null | No | — | Indicates that the refund is not linked to a Square payment. If set to true, `destination_id` and `location_id` must be supplied while `payment_id` must not be provided. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"amount_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.",
"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."
},
"currency": {
"type": "string",
"description": "Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).",
"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"
]
}
}
},
"app_fee_allocations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"charge_id": {
"type": "string",
"description": "The ID of the app fee charge."
},
"amount_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."
}
}
},
"description": "Details pertaining to contributors to the refund of the application fee. The sum of the amounts in the app_fee_allocations must equal the app_fee_money amount, if present. If populated, an allocation must be present for every party that expects to contribute a portion of the refunded application fee, including the application developer."
},
"app_fee_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.",
"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."
},
"currency": {
"type": "string",
"description": "Indicates the associated currency for an amount of money. Values correspond to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).",
"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"
]
}
}
},
"cash_details": {
"type": "object",
"description": "Stores details about a cash refund. Contains only non-confidential information.",
"properties": {
"seller_supplied_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."
},
"change_back_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."
}
},
"required": [
"seller_supplied_money"
]
},
"customer_id": {
"type": [
"string",
"null"
],
"description": "The [Customer](entity:Customer) ID of the customer associated with the refund. This is required if the `destination_id` refers to a card on file created using the Cards API. Only allowed when `unlinked=true`."
},
"destination_id": {
"type": [
"string",
"null"
],
"description": "The ID indicating where funds will be refunded to. Required for unlinked refunds. For more information, see [Process an Unlinked Refund](https://developer.squareup.com/docs/refunds-api/unlinked-refunds). For refunds linked to Square payments, `destination_id` is usually omitted; in this case, funds will be returned to the original payment source. The field may be specified in order to request a cross-method refund to a gift card. For more information, see [Cross-method refunds to gift cards](https://developer.squareup.com/docs/payments-api/refund-payments#cross-method-refunds-to-gift-cards)."
},
"external_details": {
"type": "object",
"description": "Stores details about an external refund. Contains only non-confidential information.",
"properties": {
"type": {
"type": "string",
"description": "The type of external refund the seller paid to the buyer. It can be one of the following: - CHECK - Refunded using a physical check. - BANK_TRANSFER - Refunded using external bank transfer. - OTHER\\_GIFT\\_CARD - Refunded using a non-Square gift card. - CRYPTO - Refunded using a crypto currency. - SQUARE_CASH - Refunded using Square Cash App. - SOCIAL - Refunded using peer-to-peer payment applications. - EXTERNAL - A third-party application gathered this refund outside of Square. - EMONEY - Refunded 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."
},
"source": {
"type": "string",
"description": "A description of the external refund source. For example, \"Food Delivery Service\"."
},
"source_id": {
"type": "string",
"description": "An ID to associate the refund to its originating source."
}
},
"required": [
"type",
"source"
]
},
"idempotency_key": {
"type": "string",
"description": "A unique string that identifies this `RefundPayment` request. The key can be any valid string but must be unique for every `RefundPayment` request. Keys are limited to a max of 45 characters - however, the number of allowed characters might be less than 45, if multi-byte characters are used. For more information, see [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency)."
},
"location_id": {
"type": [
"string",
"null"
],
"description": "The location ID associated with the unlinked refund. Required for requests specifying `unlinked=true`. Otherwise, if included when `unlinked=false`, will throw an error."
},
"payment_id": {
"type": [
"string",
"null"
],
"description": "The unique ID of the payment being refunded. Required when unlinked=false, otherwise must not be set."
},
"payment_version_token": {
"type": [
"string",
"null"
],
"description": "Used for optimistic concurrency. This opaque token identifies the current `Payment` version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION_MISMATCH error is returned. If the versions match, or the field is not provided, the refund proceeds as normal."
},
"reason": {
"type": [
"string",
"null"
],
"description": "A description of the reason for the refund."
},
"team_member_id": {
"type": [
"string",
"null"
],
"description": "An optional [TeamMember](entity:TeamMember) ID to associate with this refund."
},
"unlinked": {
"type": [
"boolean",
"null"
],
"description": "Indicates that the refund is not linked to a Square payment. If set to true, `destination_id` and `location_id` must be supplied while `payment_id` must not be provided."
}
},
"required": [
"PCID",
"amount_money",
"idempotency_key"
]
}
```
***
## square\_payments\_register\_domain
RegisterDomain
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------- |
| `domain_name` | string | Yes | — | A domain name as described in RFC-1034 that will be registered with ApplePay. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"domain_name": {
"type": "string",
"description": "A domain name as described in RFC-1034 that will be registered with ApplePay."
}
},
"required": [
"PCID",
"domain_name"
]
}
```
***
## square\_payments\_retrieve\_card
RetrieveCard
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------- |
| `card_id` | string | Yes | — | Unique ID for the desired Card. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"card_id": {
"type": "string",
"description": "Unique ID for the desired Card."
}
},
"required": [
"PCID",
"card_id"
]
}
```
***
## square\_payments\_retrieve\_cash\_drawer\_shift
RetrieveCashDrawerShift
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | ----------------------------------------------------------- |
| `location_id` | string | Yes | — | The ID of the location to retrieve cash drawer shifts from. |
| `shift_id` | string | Yes | — | The shift ID. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location to retrieve cash drawer shifts from."
},
"shift_id": {
"type": "string",
"description": "The shift ID."
}
},
"required": [
"PCID",
"location_id",
"shift_id"
]
}
```
***
## square\_payments\_retrieve\_gift\_card
RetrieveGiftCard
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------------ |
| `id` | string | Yes | — | The ID of the gift card to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The ID of the gift card to retrieve."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## square\_payments\_retrieve\_gift\_card\_from\_gan
RetrieveGiftCardFromGAN
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gan` | string | Yes | — | The gift card account number (GAN) of the gift card to retrieve. The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported. Square-issued gift cards have 16-digit GANs. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"gan": {
"type": "string",
"description": "The gift card account number (GAN) of the gift card to retrieve. The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported. Square-issued gift cards have 16-digit GANs."
}
},
"required": [
"PCID",
"gan"
]
}
```
***
## square\_payments\_retrieve\_gift\_card\_from\_nonce
RetrieveGiftCardFromNonce
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `nonce` | string | Yes | — | The payment token of the gift card to retrieve. Payment tokens are generated by the Web Payments SDK or In-App Payments SDK. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"nonce": {
"type": "string",
"description": "The payment token of the gift card to retrieve. Payment tokens are generated by the Web Payments SDK or In-App Payments SDK."
}
},
"required": [
"PCID",
"nonce"
]
}
```
***
## square\_payments\_retrieve\_location\_settings
RetrieveLocationSettings
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | ------------------------------------------------------ |
| `location_id` | string | Yes | — | The ID of the location for which to retrieve settings. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location for which to retrieve settings."
}
},
"required": [
"PCID",
"location_id"
]
}
```
***
## square\_payments\_retrieve\_merchant\_settings
RetrieveMerchantSettings
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
}
},
"required": [
"PCID"
]
}
```
***
## square\_payments\_retrieve\_payment\_link
RetrievePaymentLink
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | --------------------------- |
| `id` | string | Yes | — | The ID of link to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The ID of link to retrieve."
}
},
"required": [
"PCID",
"id"
]
}
```
***
## square\_payments\_unlink\_customer\_from\_gift\_card
UnlinkCustomerFromGiftCard
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------ | -------- | ------- | ---------------------------------------------------- |
| `gift_card_id` | string | Yes | — | The ID of the gift card to be unlinked. |
| `customer_id` | string | Yes | — | The ID of the customer to unlink from the gift card. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"gift_card_id": {
"type": "string",
"description": "The ID of the gift card to be unlinked."
},
"customer_id": {
"type": "string",
"description": "The ID of the customer to unlink from the gift card."
}
},
"required": [
"PCID",
"gift_card_id",
"customer_id"
]
}
```
***
## square\_payments\_update\_location\_settings
UpdateLocationSettings
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------ | -------- | ------- | ------------------------------------------------------ |
| `location_id` | string | Yes | — | The ID of the location for which to retrieve settings. |
| `location_settings` | object | Yes | — | Location Settings |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"location_id": {
"type": "string",
"description": "The ID of the location for which to retrieve settings."
},
"location_settings": {
"type": "object",
"description": "Location Settings",
"properties": {
"location_id": {
"type": "string",
"description": "The ID of the location that these settings apply to."
},
"customer_notes_enabled": {
"type": "boolean",
"description": "Indicates whether customers are allowed to leave notes at checkout."
},
"policies": {
"type": "array",
"items": {
"type": "object"
},
"description": "Policy information is displayed at the bottom of the checkout pages. You can set a maximum of two policies."
},
"branding": {
"type": "object",
"description": "The branding value"
},
"tipping": {
"type": "object",
"description": "The tipping value"
},
"coupons": {
"type": "object",
"description": "The coupons value"
},
"updated_at": {
"type": "string",
"description": "The timestamp when the settings were last updated, in RFC 3339 format. Examples for January 25th, 2020 6:25:34pm Pacific Standard Time: UTC: 2020-01-26T02:25:34Z Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00"
}
}
}
},
"required": [
"PCID",
"location_id",
"location_settings"
]
}
```
***
## square\_payments\_update\_merchant\_settings
UpdateMerchantSettings
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------ | -------- | ------- | ----------------- |
| `merchant_settings` | object | Yes | — | Merchant Settings |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"merchant_settings": {
"type": "object",
"description": "Merchant Settings",
"properties": {
"payment_methods": {
"type": "object",
"description": "Payment Methods"
},
"updated_at": {
"type": "string",
"description": "The timestamp when the settings were last updated, in RFC 3339 format. Examples for January 25th, 2020 6:25:34pm Pacific Standard Time: UTC: 2020-01-26T02:25:34Z Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00"
}
}
}
},
"required": [
"PCID",
"merchant_settings"
]
}
```
***
## square\_payments\_update\_payment
UpdatePayment
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_id` | string | Yes | — | The ID of the payment to update. |
| `idempotency_key` | string | Yes | — | 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). |
| `payment` | object | No | — | Represents a payment processed by the Square API. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"payment_id": {
"type": "string",
"description": "The ID of the payment to update."
},
"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)."
},
"payment": {
"type": "object",
"description": "Represents a payment processed by the Square API.",
"properties": {
"id": {
"type": "string",
"description": "A unique ID for the payment."
},
"created_at": {
"type": "string",
"description": "The timestamp of when the payment was created, in RFC 3339 format."
},
"updated_at": {
"type": "string",
"description": "The timestamp of when the payment was last updated, in RFC 3339 format."
},
"amount_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."
},
"tip_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."
},
"total_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."
},
"app_fee_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."
},
"app_fee_allocations": {
"type": "array",
"items": {
"type": "object"
},
"description": "Details pertaining to recipients of the application fee."
},
"approved_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."
},
"processing_fee": {
"type": "array",
"items": {
"type": "object"
},
"description": "The processing fees and fee adjustments assessed by Square for this payment."
},
"refunded_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."
},
"status": {
"type": "string",
"description": "Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED."
},
"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."
},
"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`."
},
"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."
},
"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)."
},
"card_details": {
"type": "object",
"description": "Reflects the current status of a card payment. Contains only non-confidential information."
},
"cash_details": {
"type": "object",
"description": "Stores details about a cash payment. Contains only non-confidential information. For more information, see [Take Cash Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments)."
},
"bank_account_details": {
"type": "object",
"description": "Additional details about BANK_ACCOUNT type payments."
},
"electronic_money_details": {
"type": "object",
"description": "Details specific to electronic money payments."
},
"external_details": {
"type": "object",
"description": "Stores details about an external payment. Contains only non-confidential information. For more information, see [Take External Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments)."
},
"wallet_details": {
"type": "object",
"description": "Additional details about `WALLET` type payments. Contains only non-confidential information."
},
"buy_now_pay_later_details": {
"type": "object",
"description": "Additional details about a Buy Now Pay Later payment type."
},
"square_account_details": {
"type": "object",
"description": "Additional details about Square Account payments."
},
"location_id": {
"type": "string",
"description": "The ID of the location associated with the payment."
},
"order_id": {
"type": "string",
"description": "The ID of the order associated with the payment."
},
"reference_id": {
"type": "string",
"description": "An optional ID that associates the payment with an entity in another system."
},
"customer_id": {
"type": "string",
"description": "The ID of the customer associated with the payment. If the ID is not provided in the `CreatePayment` request that was used to create the `Payment`, Square may use information in the request (such as the billing and shipping address, email address, and payment source) to identify a matching customer profile in the Customer Directory. If found, the profile ID is used. If a profile is not found, the API attempts to create an [instant profile](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles). If the API cannot create an instant profile (either because the seller has disabled it or the seller's region prevents creating it), this field remains unset. Note that this process is asynchronous and it may take some time before a customer ID is added to the payment."
},
"employee_id": {
"type": "string",
"description": "__Deprecated__: Use `Payment.team_member_id` instead. An optional ID of the employee associated with taking the payment."
},
"team_member_id": {
"type": "string",
"description": "An optional ID of the [TeamMember](entity:TeamMember) associated with taking the payment."
},
"refund_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of `refund_id`s identifying refunds for the payment."
},
"risk_evaluation": {
"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)."
},
"terminal_checkout_id": {
"type": "string",
"description": "An optional ID for a Terminal checkout that is associated with the payment."
},
"buyer_email_address": {
"type": "string",
"description": "The buyer's email address."
},
"billing_address": {
"type": "object",
"description": "Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)."
},
"shipping_address": {
"type": "object",
"description": "Represents a postal address in a country. For more information, see [Working with Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses)."
},
"note": {
"type": "string",
"description": "An optional note to include when creating a payment."
},
"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."
},
"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."
},
"receipt_number": {
"type": "string",
"description": "The payment's receipt number. The field is missing if a payment is canceled."
},
"receipt_url": {
"type": "string",
"description": "The URL for the payment's receipt. The field is only populated for COMPLETED payments."
},
"device_details": {
"type": "object",
"description": "Details about the device that took the payment."
},
"application_details": {
"type": "object",
"description": "Details about the application that took the payment."
},
"buyer_currency_exchange": {
"type": "object",
"description": "Currency exchange rate information."
},
"is_offline_payment": {
"type": "boolean",
"description": "Whether or not this payment was taken offline."
},
"offline_payment_details": {
"type": "object",
"description": "Details specific to offline payments."
},
"version_token": {
"type": "string",
"description": "Used for optimistic concurrency. This opaque token identifies a specific version of the `Payment` object."
}
}
}
},
"required": [
"PCID",
"payment_id",
"idempotency_key"
]
}
```
***
## square\_payments\_update\_payment\_link
UpdatePaymentLink
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------ | -------- | ------- | ------------------------------------- |
| `id` | string | Yes | — | The ID of the payment link to update. |
| `payment_link` | object | Yes | — | Payment Link |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"id": {
"type": "string",
"description": "The ID of the payment link to update."
},
"payment_link": {
"type": "object",
"description": "Payment Link",
"properties": {
"id": {
"type": "string",
"description": "The Square-assigned ID of the payment link."
},
"version": {
"type": "integer",
"description": "The Square-assigned version number, which is incremented each time an update is committed to the payment link."
},
"description": {
"type": "string",
"description": "The optional description of the `payment_link` object. It is primarily for use by your application and is not used anywhere."
},
"order_id": {
"type": "string",
"description": "The ID of the order associated with the payment link."
},
"checkout_options": {
"type": "object",
"description": "Checkout Options"
},
"pre_populated_data": {
"type": "object",
"description": "Describes buyer data to prepopulate in the payment form. For more information, see [Optional Checkout Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations)."
},
"url": {
"type": "string",
"description": "The shortened URL of the payment link."
},
"long_url": {
"type": "string",
"description": "The long URL of the payment link."
},
"created_at": {
"type": "string",
"description": "The timestamp when the payment link was created, in RFC 3339 format."
},
"updated_at": {
"type": "string",
"description": "The timestamp when the payment link was last updated, in RFC 3339 format."
},
"payment_note": {
"type": "string",
"description": "An optional note. After Square processes the payment, this note is added to the resulting `Payment`."
}
},
"required": [
"version"
]
}
},
"required": [
"PCID",
"id",
"payment_link"
]
}
```