You are viewing an old version of the API
Charge

Deprecated

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

Deprecated - recommend using CreatePayment

Your request to this endpoint must include either:

  • A value for the card_nonce parameter (to charge a card nonce generated with the SqPaymentForm)
  • 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.

Required permissions PAYMENTS_WRITE

Path Parameters

Name Description
location_id
string

Required

The ID of the location to associate the created transaction with.

Request Body

Name Description
amount_money
Money

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 currency must match the currency associated with the business that is charging the card.

idempotency_key
string

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.

Max Length 192 Min Length 1
additional_recipients
Additional​Recipient [ ]

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.

billing_address
Address

The buyer's billing address. This value is optional, but this transaction is ineligible for chargeback protection if neither this parameter nor shipping_address is provided.

buyer_email_address
string

The buyer's email address, if available. This value is optional, but this transaction is ineligible for chargeback protection if it is not provided.

card_nonce
string

A nonce generated from the SqPaymentForm that represents the card to charge.

The application that provides a nonce to this endpoint must be the same application that generated the nonce with the SqPaymentForm. Otherwise, the nonce is invalid.

Do not provide a value for this field if you provide a value for customer_card_id.

Max Length 192
customer_card_id
string

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.

Max Length 192
customer_id
string

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.

Max Length 50
delay_capture
boolean

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

An optional note to associate with the transaction.

This value cannot exceed 60 characters.

Max Length 60
order_id
string

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.

Max Length 192
reference_id
string

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.

Max Length 40
shipping_address
Address

The buyer's shipping address, if available. This value is optional, but this transaction is ineligible for chargeback protection if neither this parameter nor billing_address is provided.

verification_token
string

A token generated by SqPaymentForm's verifyBuyer() that represents customer's device info and 3ds challenge result.

Response Fields

Name Description
errors
Error [ ]

Any errors that occurred during the request.

transaction
Transaction

The created transaction.

Examples

You are viewing an old version of the API
POST /v2/locations/{location_id}/transactions
cURL
  • cURL
  • Ruby
  • Python
curl https://connect.squareup.com/v2/locations/{location_id}/transactions \
  -X POST \
  -H 'Square-Version: 2019-11-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -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
  }'
Response JSON
{
  "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"
  }
}

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?