Take Card Payments

Take Card Payments

You can charge a card (credit/debit card or Square gift card) using the CreatePayment endpoint. As part of processing the payment, Square takes care of maintaining PCI compliance, detecting fraud, and managing disputes. When Square receives a CreatePayment request, it charges the specified card and deposits the funds in the Square Balance of the account.

This topic explains how to provide a card as a payment source in a CreatePayment request. It also explains card payment related considerations, including delayed payments (obtain only payment authorization) and how to manage a partial payment when a Square gift card is a payment source.

Specify the payment source Permalink Get a link to this section

You do not specify card information (card number, expiry date, and other information) directly in a CreatePayment request. Instead, you have the following options:

  • Specify a payment token representing a card. The payment token is a single-use secure token also known to as a nonce.

  • Specify an ID of a card on file.

Payment token as a payment source Permalink Get a link to this section

An application that integrate Square payments provide a payment token as a payment source in a CreateRequest. The application can be:

These applications process a payment in two-steps:

  1. Generate a payment token. The Square-provided client-side libraries take card information (a credit/debit card or Square gift card) in the application UI and generate a payment token.

  2. Charge the payment token. The application can then make a server-side CreatePayment call to charge the payment token.

    The following is an example CreatePayment request. It directs Square to charge $1 to the card represented by the payment token in the source_id.

    Create Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    curl https://connect.squareupsandbox.com/v2/payments \
      -X POST \
      -H 'Square-Version: 2021-05-13' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "amount_money": {
          "amount": 2000,
          "currency": "USD"
        },
        "source_id": "{PAYMENT_TOKEN_REPRESENTING_A_CARD}"
      }'

    Square charges the card and returns a Payment object in the response as shown.

    {
       "payment":{
          "id":"Lj1PeasZIDuX2oZzd1ZDHPFWdHLZY",
          "created_at":"2021-03-07T19:14:04.160Z",
          "updated_at":"2021-03-07T19:14:04.462Z",
          "amount_money":{
             "amount":2000,
             "currency":"USD"
          },
          "status":"COMPLETED",
          "delay_duration":"PT168H",
          "source_type":"CARD",
          "card_details":{
             "status":"CAPTURED",
             "card":{
                "card_brand":"AMERICAN_EXPRESS",
                "last_4":"6550",
                "exp_month":3,
                "exp_year":2023,
                "fingerprint":"sq-1-Qo2zq6ihytSFS7jL8DaOro1sBUOfsv8o5rzl1uxie4KPd-gZcTxOJRj3moHXZ-f2CA",
                "card_type":"CREDIT",
                "prepaid_type":"NOT_PREPAID",
                "bin":"371263"
             },
             "entry_method":"KEYED",
             "cvv_status":"CVV_ACCEPTED",
             "avs_status":"AVS_ACCEPTED",
             "statement_description":"SQ *DEFAULT TEST ACCOUNT",
             "card_payment_timeline":{
                "authorized_at":"2021-03-07T19:14:04.270Z",
                "captured_at":"2021-03-07T19:14:04.462Z"
             }
          },
          "location_id":"S8GWD5R9QB376",
          "order_id":"En8UuV6DqjJgMdryShWtf2sGGhTZY",
          "risk_evaluation":{
             "created_at":"2021-03-07T19:14:04.270Z",
             "risk_level":"NORMAL"
          },
          "total_money":{
             "amount":2000,
             "currency":"USD"
          },
          "approved_money":{
             "amount":2000,
             "currency":"USD"
          },
          "receipt_number":"Lj1P",
          "receipt_url":"https://squareupsandbox.com/receipt/preview/Lj1PeasZIDuX2oZzd1ZDHPFWdHLZY",
          "delay_action":"CANCEL",
          "delayed_until":"2021-03-14T19:14:04.160Z",
          "version_token":"Deu8CMXOnZK2l1v5KOdrkyb1pnBmj7YJG9semcUq7FV6o"
       }
    }
    

    Some of the highlights in the response are:

    • The payment status in the response is COMPLETED, which indicates that the payment source is successfully charged.

    • total_money is the sum of amount_money and tip_money. Because the example does not specify a tip when taking the payment, total_money is the same as amount_money.

    • order_id is the order that the Payments API created. For compatibility with other products (for example, the Point of Sale application), all payments taken for a Square seller need an order. If you do not supply one, the Payments API creates and maintains one automatically.

Testing Permalink Get a link to this section

You can test the preceding CreatePayment call in the Square Sandbox.

  1. Make sure the endpoint URL specifies the Square Sandbox domain (connect.squareupsandbox.com). This example already does that.

  2. Update the cURL command by providing the following values and run the command:

    • source_Id field. Specify cnon:card-nonce-ok as the value. This is the test payment token that Square provides for Sandbox testing. Square does not charge the fake card it represents. However, you get a response as if the card is charged. For more information, see Square API endpoint testing.

    • Authorization header. Specify the Sandbox access token of your account. For more information, see Make a test API call.

  3. Run the command and verify this payment in the Sandbox Seller Dashboard. For more information, see Verify the transaction in the Sandbox Seller Dashboard.

Card on file as a payment source Permalink Get a link to this section

A seller can have customers with profiles created in the seller's Customer Directory. Each of these customers can optionally have a card on file (a credit card or Square gift card).

You can create a customer and add a card on file using one of the following methods:

In a CreatePayment request, you can specify a card on file as a payment source. When you specify a card on file, the customer ID is required as shown:

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "autocomplete": true,
    "amount_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "source_id": "{CARD_ON_FILE_ID}",
    "customer_id": "{CUSTOMER_ID}"
  }'

Testing Permalink Get a link to this section

You can test the preceding CreatePayment request in the Square Sandbox. In the following steps, you first create a customer and add a card on file. You then call CreatePayment with the card on file as the payment source.

  1. Create a customer. Make sure to update the command and provide the Sandbox access token.

    Create Customer
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    curl https://connect.squareupsandbox.com/v2/customers \
      -X POST \
      -H 'Square-Version: 2021-05-13' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "family_name": "Doe",
        "given_name": "John"
      }'
  2. Add a card on file. This example uses a Square-provided test payment token to add a card on file. In production, your application generates a payment token using card information that customers provide.

    For more information about adding a gift card on file, see Square API endpoint testing.

    Create Customer Card
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    curl https://connect.squareupsandbox.com/v2/customers/{customer_id}/cards \
      -X POST \
      -H 'Square-Version: 2021-05-13' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "card_nonce": "cnon:card-nonce-ok"
      }'

    This creates a card on file. You need the id of the card on file to take a payment.

  1. Run the CreatePayment request. Make sure to update the request by providing the customer ID and card on file ID. After processing the payment, the endpoint returns the resulting Payment object.

  1. Verify the transaction in the Sandbox Seller Dashboard. For more information, see Verify the transaction in the Sandbox Seller Dashboard.

Take partial payments with Square gift cards Permalink Get a link to this section

In a CreatePayment request, if the payment token or the card on file specified as the payment source is a gift card, there are additional considerations.

By default, the Payments API returns an error if the Square gift card does not have sufficient funds to pay the specified total. The CreatePayment endpoint supports the accept_partial_authorization optional parameter to take partial payments. For example, the following CreatePayment request attempts to charge $20 to a Square gift card on file. The request specifies a gift card ID on file and therefore the customer ID is also required.

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "autocomplete": true,
    "amount_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "source_id": "{GIFT_CARD_ON_FILE_ID}",
    "customer_id": "{CUSTOMER_ID}"
  }'

If the Square gift card does not have sufficient funds, the request returns an error. An example error response is shown:

{
   "errors":[
      {
         "code":"INSUFFICIENT_FUNDS",
         "detail":"Authorization error: 'INSUFFICIENT_FUNDS'",
         "category":"PAYMENT_METHOD_ERROR"
      }
   ],
   "payment":{
      ...
      },
      "status":"FAILED",
      "source_type":"CARD",
      "card_details":{
         "status":"FAILED",
         ...
         "errors":[
            {
               "code":"INSUFFICIENT_FUNDS",
               "detail":"Authorization error: 'INSUFFICIENT_FUNDS'",
               "category":"PAYMENT_METHOD_ERROR"
            }
         ]
      }
   }
}

You can optionally include the accept_partial_authorization parameter in the CreatePayment request body to allow taking partial payments.

"accept_partial_authorization" : true

In the preceding example, the CreatePayment request attempts to charge $20. Suppose the Square gift card specified in the request has only $10 available. If you allow accepting a partial payment, the request is approved for $10 as shown:

{
   "payment":{
         ...
         "amount":1000,
         "currency":"USD"
      },
      "status":"APPROVED",
      "source_type":"CARD",
      "card_details":{
         "status":"AUTHORIZED",
         "card":{
            "card_brand":"SQUARE_GIFT_CARD",
            ...
         },
         ...
      }
   }
}

Important

It is the responsibility of the application developer to compare amount_money in the response with amount_money specified in the request. If the amount is less, the application should prompt the buyer for an additional payment to cover the remainder or cancel the gift card payment.

Delayed capture of a card payment Permalink Get a link to this section

In a CreatePayment request, you can set autocomplete to false to get payment approval but not charge the payment source as shown. The example request charges $1 to the payment source (a card) represented by the payment token specified as source_id.

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "autocomplete": false,
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "source_id": "{PAYMENT_TOKEN_REPRESENTING_A_CARD}"
  }'

The resulting Payment has APPROVED as the status.

{
  "payment": {
    "id": "VULXIlJz71QmmfblzQHGhnAkCkRZY",
    "amount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "status": "APPROVED",
    "delay_duration": "PT168H",
    "source_type": "CARD",
    },
  }
}

You have the follow-up options with an approved payment:

  • Complete the payment by using CompletePayment. It is also referred to as capture payment.

    Complete Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    curl https://connect.squareupsandbox.com/v2/payments/{payment_id}/complete \
      -X POST \
      -H 'Square-Version: 2021-05-13' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    Square finalizes the payment and sets the Payment status to COMPLETED.

  • Cancel the payment by using CancelPayment. It is also referred to as void payment.

    Cancel Payment
    • 1
    • 2
    • 3
    • 4
    • 5
    curl https://connect.squareupsandbox.com/v2/payments/{payment_id}/cancel \
      -X POST \
      -H 'Square-Version: 2021-05-13' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

    Square finalizes the payment and sets the Payment status to CANCELED.

For card payments, you have the following default time thresholds to capture (or cancel) an authorized payment:

  • 36 hours for in-person (card present) payments, where the card was swiped, dipped, or tapped using a card reader.

  • 7 days for online (card not present) payments, where the buyer used a card on file or typed the card number.

After the time period expires, if the payment is not in a terminal state (COMPLETED, CANCELED, or FAILED), Square cancels the payment. The delayed_until field provides the date and time on Square servers when Square cancels the payment.

You can change the preceding default thresholds by specifying the delay_duration field in a CreatePayment request. The time periods you specify must be at least 1 minute and less than the preceding threshold values.

Note

To hold the authorized funds beyond the time threshold, consider storing the card on file with a Customer object. You can then charge the card on file to create a new payment after the original payment is canceled.

Delayed capture is required when you want to create payments and apply them later to an order. For more information, see Orders integration.

Statement descriptions Permalink Get a link to this section

For card payments, you can optionally specify statement_description_identifier in a CreatePayment request. This topic explains what Square does with this identifier in constructing statement descriptions that it sends to banks. The topic also explains related caveats.

Square sends statement description information for payments that Square processes on behalf of the seller, per the bank requirements. This information then appears on customers' card or bank statements when they make or receive payments.

Clear and accurate statement descriptions explain charges and payments and can help reduce the risk of chargebacks and disputes. Bank and card network rules require that statement descriptions clearly indicate the business responsible for the charge or payment, in addition to providing other details to help customers understand their statements.

The general format of a statement description that banks include on a customer card or bank statement is:

<Payment-facilitator-id><Business-name><Delimiter><Identifier>

SQ *MYPHARMACY*#02943 is an example statement descriptor:

  • Payment-facilitator-id. For Square-generated descriptors, this value is SQ *.

  • Business name. This is the business name shown in the Seller Dashboard. A seller configures this information as part of the business receipt configuration in the Seller Dashboard.

  • Delimiter. This is the required delimiter. Square adds this only if you provide the identifier.

  • Identifier (optional). The preceding example shows a pharmacy store number (#02943) as the identifier. When you take a payment using CreatePayment, if the request includes the statement_description_identifier, Square uses the value as the identifier.

Note the caveat about statement descriptions. In constructing a statement descriptor, after Payment-facilitator-id, Square is limited to 20 characters to provide the information. Accordingly, Square truncates the identifier portion as needed. In addition, note that the statement description that Square sends to the card networks can be further truncated before being displayed to the cardholder. Therefore, information in the Payment object (that is, the statement_description on the card_details property) is not guaranteed to be exactly what the buyer sees.

Related topics Permalink Get a link to this section