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 a deposit, capture when the rental ends

Key Points:

• Authorizations typically expire in 7-30 days (set by the card brand / issuer)
• A capture always takes the full authorized amount — partial capture is not supported
• One-time operation (cannot capture twice)
• To charge a different amount, void the authorization and run a new sale

API Route Options#

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

curl -X POST https://uat.auxcore.net/api/v1/transactions/7c9e6679-7425-40de-944b-e07fc1f90ae7/capture \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "transactionId": "TXN-1769608800000-A1B2C3D4",
    "type": "capture",
    "status": "settled",
    "amount": "150.00",
    "settledDate": "2026-01-28T14:00:00.000Z",
    "gatewayName": "NMI"
  }
}

Common Scenarios#

E-Commerce: Authorize then Capture#

# Step 1: Authorize at checkout (Public API)
curl -X POST https://uat.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 150.00,
    "transactionType": "auth",
    "SuggestedMode": "Card",
    "pciToken": "pci_tok_8f2c1a9b7e4d"
  }'
# Response: data.TransactionId = 7c9e6679-7425-40de-944b-e07fc1f90ae7

# Step 2: Capture when item ships (Admin API or AuxCORE SDK)
curl -X POST https://uat.auxcore.net/api/v1/transactions/7c9e6679-7425-40de-944b-e07fc1f90ae7/capture \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Hotel: Final Bill Differs From the Hold#

Capture cannot change the amount. If the final bill differs from the authorized hold, void the authorization and process a new sale for the final amount:

# Release the $500 hold
curl -X POST https://uat.auxcore.net/api/v1/public/void \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transactionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

# Charge the actual $250
curl -X POST https://uat.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Amount": 250.00, "SuggestedMode": "Card", "pciToken": "pci_tok_8f2c1a9b7e4d"}'

Validation Rules#

Every capture error is returned as HTTP 400 with error.code: "VALIDATION_ERROR" (or 404 NOT_FOUND for an unknown transaction); the reason is in error.message.

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

Authorization Expiration#

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

Webhooks#

No webhook event is sent when an authorization is captured. The authorization itself triggers transaction.approved; to confirm a capture, read the response or fetch the transaction (GET /api/v1/transactions/:id) and check type: "capture".

Best Practices#

✅ DO:#

• Capture promptly - Within 3-5 days
• Notify customers - When capture occurs
• Handle expiration - Check auth age before capture
• Test thoroughly - Verify capture logic

❌ DON'T:#

• Don't delay captures - Risk expiration
• Don't capture twice - Will fail
• Don't expect partial capture - The full authorized amount is captured
• Don't skip error handling - Always check response

Testing#

Test Captures in Sandbox#

# 1. Create authorization (Public API)
TXNID=$(curl -s -X POST https://uat.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 100.00,
    "transactionType": "auth",
    "SuggestedMode": "Card",
    "pciToken": "pci_tok_8f2c1a9b7e4d"
  }' | jq -r '.data.TransactionId')

# 2. Capture (Admin API)
curl -X POST https://uat.auxcore.net/api/v1/transactions/$TXNID/capture \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

# 3. Capture again — should fail with VALIDATION_ERROR
curl -X POST https://uat.auxcore.net/api/v1/transactions/$TXNID/capture \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

curl -X POST https://uat.auxcore.net/api/v1/auxvault/capture \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"TransactionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

{
  "success": true,
  "Status": 1,
  "TransactionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "message": "Transaction captured",
  "data": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "type": "capture", "status": "settled" }
}

curl -X POST https://uat.auxcore.net/api/v1/transactions/7c9e6679-7425-40de-944b-e07fc1f90ae7/cancel-capture \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "transactionId": "TXN-1769608800000-A1B2C3D4",
    "type": "auth",
    "status": "approved"
  }
}

curl -X POST https://uat.auxcore.net/api/v1/auxvault/cancel-capture \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"TransactionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'

Next Steps#

• Authorize transactions →
• Void transactions →
• Refund captured transactions →

Need help? Contact support@auxcore.net