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.

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:

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.

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

You have the following options with an approved payment:

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

  Complete payment

  cURL

  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 hasn't been updated since that version_token was generated.

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

  Cancel payment

  cURL

  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.

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 isn't 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 doesn't explicitly specify an order ID. When an order ID isn't 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.

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.