Pre-Authorization and Capture

Pre-Authorization and Capture is a two-step payment process that allows you to first pre-authorize funds on a customer’s card and then capture them later. This method ensures that the card is valid and has sufficient funds before completing the transaction.

With xMoney, you can pre-authorize an amount using cardTransactionMode = auth and later capture either the full or a partial amount. However, each pre-authorization supports only one capture—multiple captures are not allowed.

Key concepts

Pre-Authorization

• Purpose: Reserves funds on the customer’s card.
• Transaction State: No money moves yet; the issuing bank holds the pre-authorized amount pending capture.
• Use Cases: Verifying funds for e-commerce orders, pre-shipment bookings, hotel and rental reservations.

Capture

• Purpose: Finalizes the transaction by transferring funds from the customer’s card to your account.
• Timing: Performed after pre-authorization to confirm order details or product availability.
• Single Capture Only: xMoney allows only one capture per pre-authorization, whether partial or full.

Creating a Pre-Authorized Order

Use cardTransactionMode: auth when creating an order. Example request:

{
  "siteId": "yourSiteId",
  "customer": {
    // customer details
  },
  "order": {
    "orderId": "order1",
    "type": "purchase",
    "amount": 10,
    "currency": "EUR",
    "description": "Sample Pre-Auth Order"
  },
  "cardTransactionMode": "auth"
}

Result: The requested amount (e.g., 10 EUR) is pre-authorized on the customer’s card. Transaction/Order IDs: Retrieved from IPN/Webhook or direct response and stored for the capture request.

Capturing funds

Each pre-authorization supports a single capture—either full or partial.

Full Capture

Example cURL request to capture the full amount:

curl -X PUT "https://api-stage.xmoney.com/transaction/{transactionId}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer yourApiKey" \
  --data-urlencode "amount=10"

• transactionId: Retrieved from the pre-authorization step.
• amount: Must match the pre-authorized total for a full capture.

Partial Capture

If only part of the pre-authorized amount is needed (e.g., capturing 5 EUR from a 10 EUR pre-authorization), adjust the request:

curl -X PUT "https://api-stage.xmoney.com/transaction/{transactionId}" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -H "Accept: application/json" \
 -H "Authorization: Bearer yourApiKey" \
 --data-urlencode "amount=5"

After a partial capture:

• Captured: The specified amount (e.g., 5 EUR) is transferred to your account.
• Released: The remaining funds are freed from pre-authorization.
• No Additional Captures: Further capture attempts on the same pre-authorization will be rejected.

Important notes

• Capture Amount: Must be ≤ the pre-authorized amount; for partial captures, it must be strictly less.
• Single Capture: Attempting a second capture on the same transaction will be denied.
• Pre-Authorization Expiry: If you do not capture funds before expiry, they are automatically released.
• Status Monitoring: Check transaction status to confirm successful captures (complete-ok).

Conclusion

Using Pre-Authorization and Capture with xMoney provides flexibility in how and when you finalize payments. Whether capturing the full amount post-confirmation or adjusting for partial shipments, xMoney’s single-capture approach simplifies workflows while maintaining security and efficiency.