POST /v2/payments

Default value: "application/json"

Represents a postal address in a country. The address format is based on an open-source library from Google. For more information, see AddressValidationMetadata. This format has dedicated fields for four address components: postal code, locality (city), administrative district (state, prefecture, or province), and sublocality (town or village). These components have dedicated fields in the Address object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons.

For the remaining address components, the Address type provides the address_line_1 and address_line_2 fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other Address type fields are blank. These include address_line_3, sublocality_2, sublocality_3, administrative_district_level_2, administrative_district_level_3, first_name, last_name, and organization.

When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.

The third line of the address, if any.

Optional first name when it's representing recipient.

The address's postal code.

Optional organization name when it's representing recipient.

The second line of the address, if any.

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).

A civil entity within the address's administrative_district_level_2, if any.

A civil region within the address's sublocality, if any.

A civil entity within the address's administrative_district_level_1. In the US, this is the county.

The city or town of the address.

A civil region within the address's locality, if any.

Optional last name when it's representing recipient.

A civil entity within the address's country. In the US, this is the state.

A civil region within the address's sublocality_2, if any.

The address's country, in ISO 3166-1-alpha-2 format.

An identifying token generated by payments.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.

For more information, see SCA Overview.

Stores details about a cash payment. Contains only non-confidential information. For more information, see Take Cash Payments.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

The duration of time after the payment's creation when Square automatically cancels the payment. This automatic cancellation applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the delay_duration time period.

This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value of 1 minute.

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.

A unique string that identifies this CreatePayment request. Keys can be any valid string but must be unique for every CreatePayment request.

Max: 45 characters

Note: The number of allowed characters might be less than the stated maximum, if multi-byte characters are used.

For more information, see Idempotency.

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).

Limit 40 characters.

If set to true, this payment will be completed when possible. If set to false, this payment is held in an approved state until either explicitly completed (captured) or canceled (voided). For more information, see Delayed capture.

Default: true

Stores details about an external payment. Contains only non-confidential information. For more information, see Take External Payments.

A description of the external payment source. For example, "Food Delivery Service".

An ID to associate the payment to its originating source.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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.

The ID for the source of funds for this payment. This can be a payment token (card nonce) generated by the Square payment form or a card on file made with the Customers API. If recording a payment that the seller received outside of Square, specify either "CASH" or "EXTERNAL". For more information, see Take Payments.

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 Customers API.

The location ID to associate with the payment. If not specified, the default location is used.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

Associates a previously created order with this payment.

An optional note to be entered by the developer when creating a payment.

Limit 500 characters.

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.

Default: false

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

The buyer's email address.

Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.

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.

The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.

See Currency for possible values.

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.

Represents a postal address in a country. The address format is based on an open-source library from Google. For more information, see AddressValidationMetadata. This format has dedicated fields for four address components: postal code, locality (city), administrative district (state, prefecture, or province), and sublocality (town or village). These components have dedicated fields in the Address object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons.

For the remaining address components, the Address type provides the address_line_1 and address_line_2 fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want.

Note that, in the current implementation, all other Address type fields are blank. These include address_line_3, sublocality_2, sublocality_3, administrative_district_level_2, administrative_district_level_3, first_name, last_name, and organization.

When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.

The third line of the address, if any.

Optional first name when it's representing recipient.

The address's postal code.

Optional organization name when it's representing recipient.

The second line of the address, if any.

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).

A civil entity within the address's administrative_district_level_2, if any.

A civil region within the address's sublocality, if any.

A civil entity within the address's administrative_district_level_1. In the US, this is the county.

The city or town of the address.

A civil region within the address's locality, if any.

Optional last name when it's representing recipient.

A civil entity within the address's country. In the US, this is the state.

A civil region within the address's sublocality_2, if any.

The address's country, in ISO 3166-1-alpha-2 format.