A deep dive into authorization and delayed capture.

Placing a hold on a card, or “pre-auth”-ing a transaction is very similar in practice as charging a card directly with the APIs.

When to delay capture?

Choosing to delay capture on a transaction instead of directly charging is usually decided by the type of business you have. You could place a hold on someone’s card while they borrow equipment or rent property. Other common use cases involve needing to confirm that customers have enough funds to purchase before they “test drive” a product, or implementing room for tipping or optional gratuity in a purchase flow.

The only difference when making a charge is thedelay_capture parameter included with the request, like this:

`POST /v2/locations/LOCATION_ID/transactions{
  "idempotency_key": "74ae1696-b1e3-4328-af6d-f1e04d947a13",
  "amount_money": {
    "amount": 5000,
    "currency": "USD"
  },
  "card_nonce": "card_nonce_from_square_123",
  **"delay_capture": false**
}`

Then the status from the transaction will show AUTHORIZED instead of the usual CAPTURED, like this:

{
   "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",
         "amount_money": {
           "amount": 5000,
           "currency": "USD"
         },
         "type": "CARD",
         "card_details": {
**           "status": "AUTHORIZED",
**           "card": {
             "card_brand": "VISA",
             "last_4": "1111"
           },
           "entry_method": "KEYED"
         }
       }
     ],
     "product": "EXTERNAL_API"
   }
 }

If you customer doesn’t have enough funds or credit in their account, this transaction will fail.

You now have a charge that is Authorized, and you have six days to either capture the payment, or void it out.

Capturing the payment

If you decide that you want to capture the payment for your authorization, you’ll need to use the CaptureTransaction endpoint:

`POST /v2/locations/{location_id}/transactions/{transaction_id}/capture`

From the example transaction above we would use:

`POST /v2/locations/`18YC4JDH91E1H`/transactions/`KnL67ZIwXCPtzOrqj0HrkxMF`/capture`

This endpoint doesn’t provide a response so an empty json object {} means there was a successful capture. You can always retrieve the transaction later to get the transaction details.

Voiding the payment

An authorized transaction will automatically be voided after 6 days, but it is a best practice to void the payment as soon as you know you won’t be capturing the funds so your customer can regain access to their money or credit.

Voiding is very similar to capturing, with only a slight difference in the endpoint’s URL.

`POST /v2/locations/{location_id}/transactions/{transaction_id}/**void`**

From the example transaction above we would use:

`POST /v2/locations/`18YC4JDH91E1H`/transactions/`KnL67ZIwXCPtzOrqj0HrkxMF`/void`

This endpoint also doesn’t provide a response, so an empty json object {} means there was a successful voiding of the authorized transaction.

You’re now set to authorize transactions for later capture with Square’s eCommerce APIs. If you have any questions, let us know in the comments. Until next time!