Charge
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 nonce generated with theSqPaymentForm
) - Values for the
customer_card_id
andcustomer_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
orshipping_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.
Name | Description |
---|---|
location_
Required
Deprecated
|
The ID of the location to associate the created transaction with. |
Name | Description |
---|---|
idempotency_
Required
|
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. |
amount_
Required
|
The amount of money to charge. Note that you specify the amount in the smallest denomination of the applicable currency. For example, US dollar amounts are specified in cents. See Working with monetary amounts for details. The value of |
card_
|
A nonce generated from the The application that provides a nonce to this endpoint must be the
same application that generated the nonce with the Do not provide a value for this field if you provide a value for
|
customer_
|
The ID of the customer card on file to charge. Do
not provide a value for this field if you provide a value for If you provide this value, you must also provide a value for
|
delay_
|
If Default value: |
reference_
|
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. |
note
|
An optional note to associate with the transaction. This value cannot exceed 60 characters. |
customer_
|
The ID of the customer to associate this transaction with. This field
is required if you provide a value for |
billing_
|
The buyer's billing address. This value is optional, but this transaction
is ineligible for chargeback protection if neither this parameter nor
|
shipping_
|
The buyer's shipping address, if available. This value is optional,
but this transaction is ineligible for chargeback protection if neither this
parameter nor |
buyer_
|
The buyer's email address, if available. This value is optional, but this transaction is ineligible for chargeback protection if it is not provided. |
order_
|
The ID of the order to associate with this transaction. If you provide this value, the |
additional_
|
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 This field requires the This field is currently not supported in sandbox. |
verification_
|
A token generated by SqPaymentForm's verifyBuyer() that represents customer's device info and 3ds challenge result. |
Response Fields
Name | Description |
---|---|
errors
|
Any errors that occurred during the request. |
transaction
|
The created transaction. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/locations/18YC4JDH91E1H/transactions \
-X POST \
-H 'Square-Version: 2021-03-17' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
"shipping_address": {
"address_line_1": "123 Main St",
"locality": "San Francisco",
"administrative_district_level_1": "CA",
"postal_code": "94114",
"country": "US"
},
"billing_address": {
"address_line_1": "500 Electric Ave",
"address_line_2": "Suite 600",
"administrative_district_level_1": "NY",
"locality": "New York",
"postal_code": "10003",
"country": "US"
},
"amount_money": {
"amount": 200,
"currency": "USD"
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 20,
"currency": "USD"
}
}
],
"card_nonce": "card_nonce_from_square_123",
"reference_id": "some optional reference id",
"note": "some optional note",
"delay_capture": false
}'
{
"transaction": {
"id": "KnL67ZIwXCPtzOrqj0HrkxMF",
"location_id": "18YC4JDH91E1H",
"created_at": "2016-03-10T22:57:56Z",
"tenders": [
{
"id": "MtZRYYdDrYNQbOvV7nbuBvMF",
"location_id": "18YC4JDH91E1H",
"transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
"created_at": "2016-03-10T22:57:56Z",
"note": "some optional note",
"amount_money": {
"amount": 200,
"currency": "USD"
},
"additional_recipients": [
{
"location_id": "057P5VYJ4A5X1",
"description": "Application fees",
"amount_money": {
"amount": 20,
"currency": "USD"
},
"receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF"
}
],
"type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "VISA",
"last_4": "1111"
},
"entry_method": "KEYED"
}
}
],
"reference_id": "some optional reference id",
"product": "EXTERNAL_API"
}
}
Error Descriptions
400 Bad request |
AMOUNT_ The requested payment amount is too high for the provided payment source. |
> |
400 Bad request |
CARD_ The card issuer declined the request because the card is expired. |
> |
400 Bad request |
CARD_ The provided card token (nonce) has expired. |
> |
400 Bad request |
CARD_ The provided card token (nonce) was already used to process payment. |
> |
400 Bad request |
INVALID_ The credit card cannot be validated based on the provided details. |
> |
400 Bad request |
INVALID_ Generic error - the provided card data is invalid. |
> |
400 Bad request |
INVALID_ The expiration date for the payment card is invalid. For example, it indicates a date in the past. |
> |
400 Bad request |
ONE_ A general error occurred. |
> |
402 Payment required |
CARD_ The card was declined. |
> |
402 Payment required |
CARD_ The payment card was declined with a request for the card holder to call the issuer. |
> |
402 Payment required |
VERIFY_ The AVS could not be verified. |
> |
402 Payment required |
VERIFY_ The CVV could not be verified. |
> |
403 Forbidden |
CARD_ The location provided in the API call is not enabled for credit card processing. |
> |
{
"errors": [
{
"code": "AMOUNT_TOO_HIGH",
"category": "INVALID_REQUEST_ERROR"
}
]
}