Skip to main content
Version: v2

Pre-Auth & Capture Flow

Overview​

The pre-authorization flow is a two-step payment process for CARD payment methods. Step 1 places a hold (authorization) on the customer's card without charging it. Step 2 captures (charges) the authorized amount, either fully or partially.

Key characteristics:

  • authorizeCard: true + partialAuthorization: true on the create payment request
  • Payment reaches AUTHORIZED state after step 1
  • Merchant must explicitly call PATCH /v2/payments/{paymentId}/capture within 7 days
  • Supports full capture, partial capture, and per-allocation capture (split-tender)
  • Omitted allocations in capture request are auto-cancelled with CCG_AUTOMATED_CANCEL

Sequence Diagram — Full Flow​

Step 1 — Create Pre-Auth Payment​

Request​

Sample Request — Pre-Auth
curl -X POST "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments" \
  -H "Authorization: Bearer <token>" \
  -H "X-Merchant-Id: b955db5e-aef2-47de-bbb9-c80b9cc16e8f" \
  -H "X-Upstream-Env: dev" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantTransactionId": "preauth-20260404-001",
    "amount": 25000,
    "currencyCode": "USD",
    "authorizeCard": true,
    "partialAuthorization": true,
    "customer": {
      "hsid": "b313c1d1-b5b6-4ec7-8b5a-3a9cf7755060"
    },
    "paymentAllocations": [
      {
        "amount": 25000,
        "paymentMethodId": "b0b3c48d-4cf6-404a-a554-e14640a51c5b"
      }
    ]
  }'

Response — 202 Accepted​

{
  "url": "https://api-stg.uhg.com/.../v2/payments/770e8400-e29b-41d4-a716-446655440000",
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "merchantTransactionId": "preauth-20260404-001",
    "amount": 25000,
    "currencyCode": "USD",
    "status": "INITIATED",
    "authorizeCard": true,
    "partialAuthorization": true
  }
}

GET — After Authorization (200 OK)​

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "amount": 25000,
    "authorizedAmount": 25000,
    "capturedAmount": 0,
    "status": "AUTHORIZED",
    "authorizeCard": true,
    "partialAuthorization": true,
    "paymentAllocations": [
      {
        "id": "cccc1111-2222-3333-4444-555566667777",
        "amount": 25000,
        "authorizedAmount": 25000,
        "capturedAmount": 0,
        "status": "AUTHORIZED"
      }
    ]
  }
}

Webhook — PAYMENT_AUTHORIZED​

{
  "name": "PAYMENT_AUTHORIZED",
  "source": "merchant-portal",
  "payload": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "merchantTransactionId": "preauth-20260404-001",
    "amount": 25000,
    "status": "AUTHORIZED",
    "paymentAllocations": [
      {
        "id": "cccc1111-2222-3333-4444-555566667777",
        "amount": 25000,
        "authorizedAmount": 25000,
        "status": "AUTHORIZED"
      }
    ]
  }
}

Step 2 — Capture​

Full Capture (No Request Body)​

Omitting the request body captures the full authorized amount on all allocations.

curl -X PATCH "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/770e8400-e29b-41d4-a716-446655440000/capture" \
  -H "Authorization: Bearer <token>" \
  -H "X-Merchant-Id: b955db5e-aef2-47de-bbb9-c80b9cc16e8f" \
  -H "X-Upstream-Env: dev" \
  -H "Content-Type: application/json"

Partial Capture (With Request Body)​

Capture less than the authorized amount. The remaining authorized amount is released.

Sample Request — Partial Capture
curl -X PATCH "https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/v2/payments/770e8400-e29b-41d4-a716-446655440000/capture" \
  -H "Authorization: Bearer <token>" \
  -H "X-Merchant-Id: b955db5e-aef2-47de-bbb9-c80b9cc16e8f" \
  -H "X-Upstream-Env: dev" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentAllocations": [
      {
        "id": "cccc1111-2222-3333-4444-555566667777",
        "amount": 18000
      }
    ],
    "metadata": {
      "captureReason": "partial-fulfillment"
    }
  }'

Capture Validation Rules​

RuleHTTP StatusError
Payment must be in AUTHORIZED state400INVALID_REQUEST
Capture amount ≤ authorized amount per allocation400INVALID_REQUEST
Allocation id must belong to the payment400INVALID_REQUEST
Combined metadata (existing + new) ≤ 20 entries400INVALID_REQUEST

Capture Response — 202 Accepted​

{
  "url": "https://api-stg.uhg.com/.../v2/payments/770e8400-e29b-41d4-a716-446655440000",
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "amount": 25000,
    "authorizedAmount": 25000,
    "capturedAmount": 18000,
    "status": "COMPLETED",
    "paymentAllocations": [
      {
        "id": "cccc1111-2222-3333-4444-555566667777",
        "amount": 25000,
        "authorizedAmount": 25000,
        "capturedAmount": 18000,
        "status": "COMPLETED"
      }
    ]
  }
}

Authorization Expiry​

RuleDetail
Expiry window7 days from authorization
After expiryAuthorization hold is automatically released by the card issuer
Action requiredMerchant must create a new payment; expired authorizations cannot be captured
No automatic notificationThe system does not currently send a webhook when an authorization expires
Time-Sensitive

Pre-authorized payments must be captured or cancelled within 7 days. After expiry, the authorization hold is released by the issuing bank, and the payment can no longer be captured. The merchant must create a new payment with a new merchantTransactionId.

Partial Authorization (Healthcare / FSA/HSA Cards)​

When partialAuthorization: true, the card issuer may approve less than the requested amount. This is common with FSA/HSA healthcare cards where the eligible amount may differ from the total.

ScenarioauthorizedAmountNext Step
Full authorizationEquals amountCapture full amount
Partial authorizationLess than amountCapture partial, merchant handles remainder (e.g., second payment)
Declined0Payment fails