Preauthorization

---

Key Features

Temporary Balance Hold

Allows you to reserve a specific amount on the customer’s card without charging it immediately. This ensures funds remain available while the transaction is being completed or confirmed.

Tokenization Support

• With Existing Token: If the customer already has a card token, the pre-authorization is performed server‑to‑server with no customer interaction.

• Without Token: The system returns a checkout URL that you can send to the customer so they can complete the pre-authorization by entering their card details.

Expiration and Security Control The hold remains on the customer’s funds for a period set by the issuing bank (typically 7–30 days). No money is actually debited—only reserved.

Reusable for Multiple Charges A single pre-authorization can be used to capture one or multiple partial charges (depending on your processor), as long as they occur within the hold period and do not exceed the reserved amount.

---

Usage Flow

1. Request Pre-Authorization: Call POST /preauthorization with or without a tokenId.

2. Immediate Server‑Side: If a tokenId is provided, the hold is placed immediately and you receive confirmation.

3. Customer Checkout: If no tokenId, the API returns a checkoutUrl that you forward to the customer.

4. Customer Completes Pre-Auth: The customer enters their card data in the processor’s secure environment (e.g., CECA).

5. Store Pre-Auth ID: Save the returned preauthorizationId to use for subsequent captures.

---

Considerations

• A pre-authorization is not a charge—it’s a reservation of funds.

• It’s recorded with status IN_PROGRESS and must be captured manually via POST /preauthorization/authorization.

• If not captured before expiry, the hold is released automatically.

• Treat the preauthorizationId as a sensitive session identifier.

---

Pre-Authorization Capture (Authorization)

Enables you to convert a prior pre-authorization into an actual charge. Must be done within the hold period.

---

Key Features

Full or Partial Capture

You may charge the entire authorized amount or only a portion of it.

Original Token Validation

The system uses the same payment token, merchantId, terminalId, and userId from the original pre-authorization to ensure integrity.

Transaction Logging

The system records:

• Bank reference number

• Capture date

• Amount successfully charged

• Any remaining amount released back

---

Usage Flow

1. Invoke Capture: Call POST /preauthorization/authorization with preauthorizationId and the desired amountToCapture.

2. Validation: The system checks that the requested amount does not exceed the authorized hold.

3. Charge Execution: Funds are captured.

4. Response:

{
  "captured": true,
  "captureDate": "2025-05-13T14:22:00Z",
  "finalAmountCharged": 50.00,
  "remainingAmountUnlocked": 10.00
}

---

Considerations

• If your contract disallows multiple captures, you can only call this once per pre‑authorization.

• Requesting an amount greater than the hold returns 400 Bad Request.

• The captureDate serves as proof of completion.

• All captures occur in a secure environment with a valid digital signature.

• Processor errors return a specific error code and message for troubleshooting.