Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-142008071.1 MB
Transactions

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

post/v2/locations/{location_id}/transactions

Path parameters

location_idstring required

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

Request body

buyer_email_addressstring

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_noncestring

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.

customer_card_idstring

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.

customer_idstring

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.

delay_captureboolean

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

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

notestring

An optional note to associate with the transaction.

This value cannot exceed 60 characters.

order_idstring

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.

reference_idstring

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.

verification_tokenstring

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

Example request

{
  "request_body": {
    "additional_recipients": [
      {
        "amount_money": {
          "amount": 20,
          "currency": "USD"
        },
        "description": "Application fees",
        "location_id": "057P5VYJ4A5X1"
      }
    ],
    "amount_money": {
      "amount": 200,
      "currency": "USD"
    },
    "billing_address": {
      "address_line_1": "500 Electric Ave",
      "address_line_2": "Suite 600",
      "administrative_district_level_1": "NY",
      "country": "US",
      "locality": "New York",
      "postal_code": "10003"
    },
    "card_nonce": "card_nonce_from_square_123",
    "delay_capture": false,
    "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
    "note": "some optional note",
    "reference_id": "some optional reference id",
    "shipping_address": {
      "address_line_1": "123 Main St",
      "administrative_district_level_1": "CA",
      "country": "US",
      "locality": "San Francisco",
      "postal_code": "94114"
    }
  }
}

Response

Success

Example response

{
  "transaction": {
    "created_at": "2016-03-10T22:57:56Z",
    "id": "KnL67ZIwXCPtzOrqj0HrkxMF",
    "location_id": "18YC4JDH91E1H",
    "product": "EXTERNAL_API",
    "reference_id": "some optional reference id",
    "tenders": [
      {
        "additional_recipients": [
          {
            "amount_money": {
              "amount": 20,
              "currency": "USD"
            },
            "description": "Application fees",
            "location_id": "057P5VYJ4A5X1",
            "receivable_id": "ISu5xwxJ5v0CMJTQq7RvqyMF"
          }
        ],
        "amount_money": {
          "amount": 200,
          "currency": "USD"
        },
        "card_details": {
          "card": {
            "card_brand": "VISA",
            "last_4": "1111"
          },
          "entry_method": "KEYED",
          "status": "CAPTURED"
        },
        "created_at": "2016-03-10T22:57:56Z",
        "id": "MtZRYYdDrYNQbOvV7nbuBvMF",
        "location_id": "18YC4JDH91E1H",
        "note": "some optional note",
        "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
        "type": "CARD"
      }
    ]
  }
}