Learn how to obtain payment authorization when using a credit card as a payment source in a CreatePayment request.
Payments API

Delayed Capture of a Card Payment

Learn how to obtain payment authorization when using a credit card as a payment source in a CreatePayment request.

Overview 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 in the following example request:

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: 2022-06-16' \
  -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 example request obtains authorization for a $1 payment from the payment source represented by the payment token source_id. The resulting Payment has APPROVED as the status.

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

  • Complete the payment. Call CompletePayment to capture the payment.

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

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

    Note that Square supports optimistic concurrency for the CompletePayment endpoint. Each Payment includes a version_token field that uniquely identifies a specific version of the payment. You can optionally include this version_token in a CompletePayment request. In this case, the completion request succeeds only if the payment has not been updated since that version_token was generated.

  • Cancel the payment. Call CancelPayment to void the payment.

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

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

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

Time threshold Permalink Get a link to this section

For card payments, you have the following default time thresholds to capture (or cancel) a previously 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 takes one of the following actions, depending on the delay_action field value:

  • By default, delay_action is set to CANCEL and Square cancels the payment.

  • Applications can explicitly set delay_action to COMPLETE to direct Square to complete the payment. However, the application can set delay_action to COMPLETE only if the CreatePayment request does not explicitly specify an order ID. When an order ID is not specified, Square creates an order. This ensures that the order amount and payment amounts are the same and Square can therefore complete the payment.

Explicitly setting delay_action to COMPLETE in a CreatePayment request ensures that the authorized payment completes (either the seller completes it or, if the seller forgets, Square completes it on behalf of the seller at the time threshold).

The delayed_until field provides the date and time on Square servers when Square takes one of these automatic actions.

Configuring the time threshold Permalink Get a link to this section

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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.