The Bridge + Stripe Issuing integration uses Stripe Issuing webhooks for all card transaction events. Bridge webhook events are still used for customer and KYC status updates.Documentation Index
Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt
Use this file to discover all available pages before exploring further.
Webhook sources
| Event type | Source | Description |
|---|---|---|
| Card authorizations and transactions | Stripe | issuing_authorization.* and issuing_transaction.* events |
| Cardholder creation | Stripe | issuing_cardholder.created |
| Customer and KYC updates | Bridge | customer.* events |
| Statement generation | Bridge API | On-demand via Bridge API |
Authorization lifecycle
When a card is used at a merchant, Bridge pulls funds onchain at the time of authorization. This triggers a sequence of Stripe and onchain events.Authorization created
When a card is authorized, Bridge validates the linked wallet has an active onchain approval and sufficient funds, then submits an onchain transaction to pull funds just-in-time. Stripe publishes anissuing_authorization.created event.
The onchain transaction completes asynchronously—you may receive the Stripe event before the onchain transaction is confirmed.
By default, Bridge doesn’t support the real-time
issuing_authorization.request webhook for approving or denying individual authorizations, due to transaction submission latency. Contact Bridge if you need real-time authorization control.Incremental authorizations
If a merchant requests an increased authorization amount (for example, adding a tip), an additional onchain pull is submitted for the incremental amount. Each increment corresponds to an item in therequest_history of the authorization and triggers an issuing_authorization.updated event.
Capture
When a merchant captures an authorization, Stripe publishes anissuing_transaction.created event. If the captured amount exceeds the originally authorized amount, Bridge submits an additional onchain pull for the difference.
Bridge may also proactively pull a small additional amount at authorization time based on the merchant category code (MCC) and the overcapture upper bound. Any difference between the proactive pull and the final captured amount is refunded once settlement is complete.
Refunds and reversals
If an authorization is partially or fully refunded, Stripe publishes anissuing_authorization.updated event with the new amount. Bridge asynchronously submits an onchain transaction to return the funds to the wallet. Multiple small refunds may be batched into a single onchain transaction.
Authorization expiry
If a merchant never captures an authorization, it eventually expires. Stripe publishes anissuing_authorization.updated event transitioning the authorization to expired. Bridge returns any remaining authorized funds to the wallet.
Key Stripe webhook events
| Event | Trigger | Onchain effect |
|---|---|---|
issuing_authorization.created | Card used at a merchant | Onchain pull submitted |
issuing_authorization.updated | Incremental auth, refund, or expiry | Additional pull or return submitted |
issuing_transaction.created | Merchant captures authorization | Additional pull if capture > auth amount |
issuing_transaction.updated | Transaction state changes | None |
issuing_cardholder.created | Bridge approves cards endorsement | None (managed by Bridge) |
Bridge webhooks for customer and KYC events
Customer lifecycle events—including cards endorsement status changes—continue to be delivered via Bridge webhooks. Subscribe to thecustomer event category to receive updates when:
- A customer’s
cardsendorsement is approved (and thestripe_cardholder_idis populated) - An endorsement is revoked (for example, after 24 hours without card creation)
- KYC requirements change