Webhook Events
FinCard Virtual pushes real-time event notifications to your configured webhook URL. Events are signed with the platform RSA private key — verify using the platform public key.
Callback URL: POST /api/v2.1/fincard/virtual/webhook/callback
Signature Verification
All webhook events include an X-FC-SIGNATURE header containing a SHA256withRSA signature of the response body, base64-encoded.
Your endpoint must return {"success": true} to acknowledge receipt.
Event Types
Card Operation Transaction Event
Triggered when card operations complete (create, deposit, withdraw, freeze, unfreeze, cancel, block, overdraft).
Card Authorization Transaction Event
Triggered for card consumption events (purchases, refunds, verifications).
Card Authorization Fee Transaction Event
Triggered when insufficient card balance causes fee deduction from merchant reserve.
Card 3DS Transaction Event
Triggered for 3DS verification (OTP), transaction authorization URLs, and physical card activation codes.
The values field is encrypted with the merchant’s RSA public key. Decrypt using your RSA private key.
Card Holder Event
Triggered when cardholder approval status changes.
Activate Card Event
Triggered when a physical card is activated.
Work Order Event
Triggered when work order status changes.
Wallet Transaction Event (v2)
Triggered for crypto wallet deposit/withdrawal completions.
Your webhook endpoint must respond with:
If your endpoint fails to respond or returns an error, the platform will retry delivery. Ensure idempotent processing using orderNo / tradeNo as deduplication keys.
