POST /v2/locations/{location_id}/transactions

Charges a card represented by a card nonce or a customer's card on file.

Your request to this endpoint must include either:

A value for the card_nonce parameter (to charge a card payment token generated with the Web Payments SDK)
Values for the customer_card_id and customer_id parameters (to charge a customer's card on file)

In order for an eCommerce payment to potentially qualify for Square chargeback protection, you must provide values for the following parameters in your request:

buyer_email_address
At least one of billing_address or shipping_address

When this response is returned, the amount of Square's processing fee might not yet be calculated. To obtain the processing fee, wait about ten seconds and call RetrieveTransaction. See the processing_fee_money field of each Tender included in the transaction.

Servers

https://connect.squareup.com

Path parameters

Name	Type	Required	Description
`location_id`	String	Yes	The ID of the location to associate the created transaction with.

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`customer_card_id`	String	No	The ID of the customer card on file to charge. Do not provide a value for this field if you provide a value for `card_nonce`. If you provide this value, you must also provide a value for `customer_id`.
`shipping_address`	Object	No	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.
`shipping_address.address_line_3`	String	No	The third line of the address, if any.
`shipping_address.first_name`	String	No	Optional first name when it's representing recipient.
`shipping_address.postal_code`	String	No	The address's postal code.
`shipping_address.organization`	String	No	Optional organization name when it's representing recipient.
`shipping_address.address_line_2`	String	No	The second line of the address, if any.
`shipping_address.address_line_1`	String	No	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).
`shipping_address.administrative_district_level_3`	String	No	A civil entity within the address's `administrative_district_level_2`, if any.
`shipping_address.sublocality_2`	String	No	A civil region within the address's `sublocality`, if any.
`shipping_address.administrative_district_level_2`	String	No	A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.
`shipping_address.locality`	String	No	The city or town of the address.
`shipping_address.sublocality`	String	No	A civil region within the address's `locality`, if any.
`shipping_address.last_name`	String	No	Optional last name when it's representing recipient.
`shipping_address.administrative_district_level_1`	String	No	A civil entity within the address's country. In the US, this is the state.
`shipping_address.sublocality_3`	String	No	A civil region within the address's `sublocality_2`, if any.
`shipping_address.country`	String	No	The address's country, in ISO 3166-1-alpha-2 format.
`verification_token`	String	No	A token generated by SqPaymentForm's verifyBuyer() that represents customer's device info and 3ds challenge result.
`additional_recipients[]`	Array	No	The basic primitive of multi-party transaction. The value is optional. The transaction facilitated by you can be split from here. If you provide this value, the `amount_money` value in your additional_recipients must not be more than 90% of the `amount_money` value in the charge request. The `location_id` must be the valid location of the app owner merchant. This field requires the `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth permission. This field is currently not supported in sandbox.
`additional_recipients[].location_id`	String	Yes	The location ID for a recipient (other than the merchant) receiving a portion of this tender.
`additional_recipients[].description`	String	No	The description of the additional recipient.
`additional_recipients[].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 for more information.
`additional_recipients[].amount_money.amount`	Integer	No	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.
`additional_recipients[].amount_money.currency`	String	No	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is `USD`. See Currency for possible values.
`additional_recipients[].receivable_id`	String	No	The unique ID for this AdditionalRecipientReceivable, assigned by the server.
`idempotency_key`	String	Yes	A value you specify that uniquely identifies this transaction among transactions you've created. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about double-charging the buyer. See Idempotency keys for more information.
`reference_id`	String	No	An optional ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database). This value cannot exceed 40 characters.
`customer_id`	String	No	The ID of the customer to associate this transaction with. This field is required if you provide a value for `customer_card_id`, and optional otherwise.
`order_id`	String	No	The ID of the order to associate with this transaction. If you provide this value, the `amount_money` value of your request must exactly match the value of the order's `total_money` field.
`delay_capture`	Boolean	No	If `true`, the request will only perform an Auth on the provided card. You can then later perform either a Capture (with the CaptureTransaction endpoint) or a Void (with the VoidTransaction endpoint). Default value: `false`
`note`	String	No	An optional note to associate with the transaction. This value cannot exceed 60 characters.
`buyer_email_address`	String	No	The buyer's email address, if available. This value is optional, but this transaction is ineligible for chargeback protection if it is not provided.
`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 for more information.
`amount_money.amount`	Integer	No	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.
`amount_money.currency`	String	No	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is `USD`. See Currency for possible values.
`card_nonce`	String	No	A payment token generated from the Card.tokenize() that represents the card to charge. The application that provides a payment token to this endpoint must be the same application that generated the payment token with the Web Payments SDK. Otherwise, the nonce is invalid. Do not provide a value for this field if you provide a value for `customer_card_id`.
`billing_address`	Object	No	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.
`billing_address.address_line_3`	String	No	The third line of the address, if any.
`billing_address.first_name`	String	No	Optional first name when it's representing recipient.
`billing_address.postal_code`	String	No	The address's postal code.
`billing_address.organization`	String	No	Optional organization name when it's representing recipient.
`billing_address.address_line_2`	String	No	The second line of the address, if any.
`billing_address.address_line_1`	String	No	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).
`billing_address.administrative_district_level_3`	String	No	A civil entity within the address's `administrative_district_level_2`, if any.
`billing_address.sublocality_2`	String	No	A civil region within the address's `sublocality`, if any.
`billing_address.administrative_district_level_2`	String	No	A civil entity within the address's `administrative_district_level_1`. In the US, this is the county.
`billing_address.locality`	String	No	The city or town of the address.
`billing_address.sublocality`	String	No	A civil region within the address's `locality`, if any.
`billing_address.last_name`	String	No	Optional last name when it's representing recipient.
`billing_address.administrative_district_level_1`	String	No	A civil entity within the address's country. In the US, this is the state.
`billing_address.sublocality_3`	String	No	A civil region within the address's `sublocality_2`, if any.
`billing_address.country`	String	No	The address's country, in ISO 3166-1-alpha-2 format.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.