Handle partial captures

Prerequisites

A valid API key — see Obtain API credentials
An authorized transaction from a card_auth request (the two-step flow)

When to use partial captures

Split shipments: An order with multiple items ships in separate packages. Capture the amount for each shipment as it leaves.
Adjusted totals: The final order amount is less than the initial authorization (item unavailable, price adjustment).
Hotel / rental: The estimated hold exceeds the actual charge.

Step 1: Authorize the full estimated amount

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "type": "auth",
    "amount": 50000,
    "payment_method": {
      "type": "card",
      "pan": "5500000000005678",
      "expiry":
        "month": "07",
        "year": "2029"
      },
      "cardholder_name": "Nyota Uhura",
      "cvv": "789",
      "address_line1": "42 Subspace Ln",
      "zip": "30301"
    },
    "metadata": {},
    "recurring": false,
    "purchase_description": "Starfleet uniform"
  }'

Response returns transaction_state: authorized with amount: 50000. Save the id.

Step 2: Capture a partial amount

Send POST /v1/transactions/{id}/capture with an amount less than the authorized total.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-02KNUHURA8YWP4LT9G3X5V7Z0/capture \
  -H "Content-Type: application/json" \
  -H "APIKEY: YOUR-API-KEY" \
  -d '{
    "type": "capture",
    "amount": 30000,
    "tip": 0
  }'

Step 3: Verify the capture

The response confirms the captured amount. The remaining 200.00 USD hold (500.00 authorized − 300.00 captured) is released back to the person.

{
  "id": "TRANSACTION-02KNUHURA8YWP4LT9G3X5V7Z0",
  "type": "capture",
  "transaction_state": "completed",
  "response_status": "Approved",
  "response_code": "00",
  "amount": 30000,
  "tip": 0,
  "correlation_id": "f6a7b8c9-d0e1-2345-f012-3456789abcde"
}

How partial captures work

Scenario	Authorized	Captured	Released to person
Full capture	500.00	500.00	0.00
Partial capture	500.00	300.00	200.00
Zero capture (cancel)	500.00	0.00	500.00

Rules and constraints

Rule	Details
Capture amount must be ≤ authorized amount	You cannot capture more than was authorized
Single capture per authorization	Each authorization can be captured once (for multiple captures, use multiple authorizations)
Timing	Must capture before the authorization expires (7–30 days, varies by issuer)
Tip at capture	You can include a `tip` in the capture request; the total (amount + tip) must not exceed the authorized amount

Split shipments

For orders that ship in multiple packages, authorize the full order amount up front, then create separate authorizations for each shipment and capture individually. This is more reliable than attempting multiple partial captures against a single authorization.

Next steps

Authorize and capture separately — the full two-step flow
Add a tip or surcharge — adjust the amount before capture
About cancels and refunds — what to do if you do not need to capture