You are viewing an old version of the API

All Versions

Charge

Deprecated

Effective August 15th, 2019

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

Deprecation date

2019-08-15

Retirement date

2021-09-01

Replaced by

CreatePayment Migration guide

Open in API Explorer

Path Parameters

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

Request Body

Name	Description
`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
`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.
`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
`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`
`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
`note string`	An optional note to associate with the transaction. This value cannot exceed 60 characters. Max Length 60
`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
`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.
`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.
`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.
`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
`additional_recipients AdditionalRecipient [ ]`	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.
`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.

Error Descriptions


                      
  
  
                        AMOUNT_TOO_HIGH

The requested payment amount is too high for the provided payment source.


                      
  
  
                        CARD_DECLINED

402 Request failed - the card was declined.


                      
  
  
                        CARD_DECLINED_CALL_ISSUER

402 Request failed - the payment card was declined with a request for the card holder to call the issuer.


                      
  
  
                        CARD_EXPIRED

The card issuer declined the request because the card is expired.


                      
  
  
                        CARD_PROCESSING_NOT_ENABLED

403 Forbidden - the location provided in the API call is not enabled for credit card processing.


                      
  
  
                        CARD_TOKEN_EXPIRED

The provided card token (nonce) has expired.


                      
  
  
                        CARD_TOKEN_USED

The provided card token (nonce) was already used to process payment.


                      
  
  
                        INVALID_CARD

The credit card cannot be validated based on the provided details.


                      
  
  
                        INVALID_CARD_DATA

Generic error - the provided card data is invalid.


                      
  
  
                        INVALID_EXPIRATION

The expiration date for the payment card is invalid. For example, it indicates a date in the past.


                      
  
  
                        ONE_INSTRUMENT_EXPECTED

400 Bad Request - a general error occurred.


                      
  
  
                        VERIFY_AVS_FAILURE

402 Request failed - the AVS could not be verified.


                      
  
  
                        VERIFY_CVV_FAILURE

402 Request failed - the CVV could not be verified.

Examples

All Versions

curl https://connect.squareup.com/v2/locations/18YC4JDH91E1H/transactions \
  -X POST \
  -H 'Square-Version: 2020-06-25' \
  -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"
  }
}

Transactions API You are viewing an old version of the API 2020-06-25 Version 2020-06-25 All Versions Transactions API Charge