Recipe: Auth/capture for e-commerce

When to use this pattern

You need to verify the card before fulfilling the order
You ship physical goods and want to charge only when the order ships
You want the option to adjust the amount (for example, partial shipments)

Flow

Step 1: Authorize at checkout

When the customer places their order, authorize the full amount. This places a hold on the customer's card but does not transfer funds.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "type": "auth",
    "amount": 7500,
    "payment_method": {
      "type": "card",
      "card": {
        "pan": "4111111111111111",
        "expiry_month": "12",
        "expiry_year": "2027",
        "cvv": "123",
        "cardholder_name": "Jane Smith"
      }
    },
    "metadata": {
      "order_id": "ORD-20260325-001"
    }
  }'

Authorization response

{
  "id": "TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC",
  "type": "auth",
  "amount": 7500,
  "transaction_state": "authorized",
  "response_status": "approved",
  "response_code": "00"
}

Save the id — you need it to capture or cancel later.

Step 2: Capture when you ship

When the order ships, capture the authorized amount (or a partial amount if you ship less).

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": 7500 }'

Step 3: Handle edge cases

Cancel if the order is canceled

If the customer cancels before shipment, void the authorization to release the hold immediately.

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

Partial shipment

If you ship only part of the order, capture only that amount. The remaining hold is released automatically.

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": 4500 }'

Decision tree

Best practices

Capture promptly — authorization holds typically expire in 7–10 days. Capture before the hold expires.
Use metadata — attach your order_id to the authorization so you can correlate transactions with orders.
Check AVS/CVV — review avs_result_code and cvv_result on the authorization response before fulfilling the order.
Idempotency — if your capture request times out, it is safe to retry; the API is idempotent for capture operations.