Captures

Capture previously authorized transactions.

Overview

Authorization (auth) holds funds on a customer's card without actually charging them. Capturing processes the charge and transfers the funds.

Use cases:

📦 E-commerce - Authorize at checkout, capture at shipping
🏨 Hotels - Authorize at booking, capture at checkout
🚗 Rentals - Authorize for deposit, capture actual charges
🛒 Split shipments - Capture each shipment separately

Key Points:

Authorizations typically expire in 7-30 days
You can capture the full amount or less
Cannot capture more than authorized
One-time operation (cannot capture twice)

API Route Options

Auth Type	Endpoint	Use Case
JWT Bearer	`POST /api/v1/transactions/:id/capture`	Dashboard / admin
SDK	`POST /api/v1/auxvault/capture`	auxVault.js SDK

The Public API (/api/v1/public/*) does not have a direct capture endpoint. Captures are performed via the Admin API or the AuxVault SDK.

Capture Full Amount (Admin API)

Endpoint

POST /api/v1/transactions/:transactionId/capture

curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_abc123/capture \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "data": {
    "captureId": "cap_xyz789",
    "transactionId": "txn_abc123",
    "status": "captured",
    "authorizedAmount": 150.00,
    "capturedAmount": 150.00,
    "capturedAt": "2026-01-28T14:00:00Z"
  }
}

Partial Capture

Capture less than the authorized amount:

curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_abc123/capture \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00
  }'

Response:

{
  "success": true,
  "data": {
    "captureId": "cap_partial_123",
    "transactionId": "txn_abc123",
    "status": "captured",
    "authorizedAmount": 150.00,
    "capturedAmount": 100.00,
    "remainingAmount": 50.00,
    "capturedAt": "2026-01-28T14:00:00Z"
  }
}

⚠️ Note: The remaining $50 authorization is automatically released.

Request Parameters

Parameter	Type	Required	Description
`amount`	decimal	No	Amount to capture (defaults to full)

Response Fields

Field	Type	Description
`captureId`	string	Unique capture identifier
`transactionId`	string	Original authorization ID
`status`	string	Transaction status (`captured`)
`authorizedAmount`	decimal	Original authorization amount
`capturedAmount`	decimal	Amount captured
`remainingAmount`	decimal	Uncaptured amount (released)
`capturedAt`	timestamp	When capture occurred

Common Scenarios

E-Commerce: Authorize then Capture

# Step 1: Authorize at checkout
curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "type": "auth",
    "amount": 150.00,
    ...
  }'
# Response: transactionId = txn_abc123

# Step 2: Capture when item ships (2 days later)
curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_abc123/capture

Restaurant: Add Tip After Service

# Step 1: Authorize meal cost
curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "type": "auth",
    "amount": 50.00,
    ...
  }'

# Step 2: Capture with tip added
curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_abc123/capture \
  -d '{
    "amount": 60.00
  }'

⚠️ Note: Capturing more than authorized may fail. Some processors allow 15-20% over authorization.

Hotel: Partial Release

# Step 1: Authorize $500 deposit
curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "type": "auth",
    "amount": 500.00,
    ...
  }'

# Step 2: Capture only actual charges ($250)
curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_abc123/capture \
  -d '{
    "amount": 250.00
  }'
# Remaining $250 automatically released

Validation Rules

Cannot Capture If:

Already captured

{
  "success": false,
  "error": {
    "code": "ALREADY_CAPTURED",
    "message": "Transaction already captured"
  }
}

Already voided

{
  "success": false,
  "error": {
    "code": "ALREADY_VOIDED",
    "message": "Cannot capture voided transaction"
  }
}

Authorization expired

{
  "success": false,
  "error": {
    "code": "AUTHORIZATION_EXPIRED",
    "message": "Authorization has expired"
  }
}

Amount exceeds authorization

{
  "success": false,
  "error": {
    "code": "AMOUNT_EXCEEDS_AUTH",
    "message": "Capture amount exceeds authorized amount"
  }
}

Not an authorization

{
  "success": false,
  "error": {
    "code": "NOT_CAPTURABLE",
    "message": "Only auth transactions can be captured"
  }
}

Authorization Expiration

Card Brand	Expiration Period
Visa	7 days
Mastercard	7 days (30 days for some MCC codes)
American Express	7 days
Discover	10 days

⚠️ Best Practice: Capture within 3-5 days to avoid expiration.

Webhooks

capture.succeeded

{
  "type": "transaction.captured",
  "data": {
    "transactionId": "txn_abc123",
    "captureId": "cap_xyz789",
    "authorizedAmount": 150.00,
    "capturedAmount": 150.00,
    "capturedAt": "2026-01-28T14:00:00Z"
  }
}

capture.failed

{
  "type": "capture.failed",
  "data": {
    "transactionId": "txn_abc123",
    "error": "Authorization expired",
    "attemptedAt": "2026-01-28T14:00:00Z"
  }
}

Best Practices

✅ DO:

Capture promptly - Within 3-5 days
Notify customers - When capture occurs
Handle expiration - Check auth age before capture
Partial captures - When appropriate (reduce disputes)
Track captures - Use webhooks for automation
Test thoroughly - Verify capture logic

❌ DON'T:

Don't delay captures - Risk expiration
Don't capture twice - Will fail
Don't exceed auth amount - May be declined
Don't skip error handling - Always check response
Don't forget webhooks - For async processing

Testing

Test Captures in Sandbox

# 1. Create authorization
TXNID=$(curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "type": "auth",
    "amount": 100.00,
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2027",
      "cvv": "123"
    },
    ...
  }' | jq -r '.data.transactionId')

# 2. Capture full amount
curl -X POST https://dev.auxcore.net/api/v1/transactions/$TXNID/capture

# 3. Test partial capture
curl -X POST https://dev.auxcore.net/api/v1/transactions/$TXNID/capture \
  -d '{"amount": 50.00}'

# 4. Test already captured error
curl -X POST https://dev.auxcore.net/api/v1/transactions/$TXNID/capture
# Should fail with ALREADY_CAPTURED

Cancel Capture

Reverse a capture, returning the transaction to authorized (approved) state. Useful when a capture was made in error and the settlement window hasn't closed.

Endpoint

POST /api/v1/transactions/:transactionId/cancel-capture

curl -X POST https://dev.auxcore.net/api/v1/transactions/txn_abc123/cancel-capture \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "status": "approved",
    "message": "Capture reversed. Transaction returned to authorized state."
  }
}

When to Use Cancel Capture

Scenario	Action
Captured wrong transaction	Cancel capture → re-capture correct one
Item out of stock after capture	Cancel capture → void
Capture made too early	Cancel capture → capture later
Settlement already processed	Cannot cancel — use refund instead

Validation

Cancel capture requires:

Transaction status must be settled

If the transaction has already processed through settlement, you must issue a refund instead.

Via SDK

curl -X POST https://api.auxvault.com/api/v1/auxvault/cancel-capture \
  -H "Authorization: Bearer lv_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"TransactionId": "txn_abc123"}'

Next Steps

Need help? Contact support@auxvault.com