Recipe: Authorize and capture

When to use two-step payments

E-commerce — authorize at checkout, capture when the order ships
Hotels / car rentals — authorize an estimated amount, capture the final charge
Subscriptions — authorize a recurring amount, capture after usage is calculated

For a comparison of one-step vs. two-step flows, see Sale vs. authorization.

Payment state lifecycle

Prerequisites

A valid API key — see Obtain API credentials
A TSYS integration configured for card processing

Step 1: Authorize

Send a card_auth transaction to place a hold on the customer's card.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "type": "card_auth",
    "amount": 4995,
    "card": {
      "pan": "4111111111111111",
      "expiry_month": "12",
      "expiry_year": "2027",
      "cvv": "123",
      "cardholder_name": "Jane Smith",
      "address": { "line1": "123 Main St", "zip": "62704" }
    }
  }'

Authorization response

{
  "id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC",
  "type": "card_auth",
  "amount": 4995,
  "transaction_state": "authorized",
  "response_status": "approved",
  "response_code": "00",
  "avs_result_code": "Y",
  "cvv_result": "M",
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Save the id — you need it for capture or cancel.

Check fraud signals

Review avs_result_code and cvv_result before fulfilling. If AVS or CVV fails, consider canceling the authorization. See Fraud prevention.

Step 2: Capture

When you are ready to charge (for example, when the order ships), capture the authorized amount.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/capture \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{ "amount": 4995 }'

Partial capture

To capture less than the authorized amount (for example, partial shipment), specify a smaller amount. The remaining hold is released.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/capture \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{ "amount": 2500 }'

Step 3: Handle edge cases

Cancel before capture

If the order is canceled before capture, void the authorization to release the hold.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/cancel \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY"

Authorization expired

Authorization holds typically expire after 7–10 days. If the hold expires before capture, you must create a new authorization.

Timing rules

Event	Timing
Authorization created	Immediate
Hold placed on card	Immediate
Capture window	7–10 days (processor-dependent)
Settlement after capture	Next batch close

Best practices

Capture promptly — don't let authorization holds expire. Capture as soon as you're ready.
Check AVS/CVV — review fraud signals on the auth response before fulfilling.
Use metadata — attach your order ID to the transaction for reconciliation.
Include idempotency keys — safe to retry if the capture request times out.
Log correlation_id — include it in your order records for support requests.