Issuing real-time authorizations
Learn about real-time authorizations.
Using the synchronous webhook, you can approve or decline authorization requests in real time.
Your webhook endpoint can be configured in your settings. When a card is used to make a purchase, Stripe creates an issuing_ and sends it to your configured endpoint for your approval.
Get started with our interactive guide to real-time authorizations.
Responding to authorization requests
You can respond to authorization requests by responding directly to the webhook event.
Respond directly
Respond to the issuing_ webhook event directly to either approve or decline an authorization after it’s received.
Webhook response
Our webhook accepts JSON responses with the following parameters:
Status code: Return 200 to indicate success.
Header:
| field name | required or optional | description |
|---|---|---|
| Stripe-Version | required | See API Versioning for supported values. |
| Content-Type | optional | The only content type accepted for Authorization webhook responses is application/json. |
Body:
| field name | required or optional | type | description |
|---|---|---|---|
| approved | required | Boolean | Set true to approve an authorization and false to decline. |
| amount | optional | Integer | If the authorization’s pending_ property is true, you can provide this value to control how much to hold for the authorization. It must be positive. |
| metadata | optional | Set of key-value pairs | This can be useful for storing additional information about the object in a structured format. |
| send_fraud_challenges Public preview | optional | Array of strings | You can send a fraud challenge for this authorization only through SMS. Leave it blank if you don’t want to send a challenge. |
# Using Sinatra. require 'sinatra' require 'stripe' set :port, 4242 # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('sk_test_BQokikJOvBiI2HlWgH4olfQ2') # Replace with a real secret. You can find your endpoint's secret in your webhook settings. webhook_secret = 'whsec_...' post '/webhook' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil # Verify webhook signature and extract the event. begin event = Stripe::Webhook.construct_event( payload, sig_header, webhook_secret ) rescue JSON::ParserError => e # Invalid payload. status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature. status 400 return end if event['type'] == 'issuing_authorization.request' auth = event['data']['object'] # ... custom business logic status 200 header 'Stripe-Version' => '2025-03-31.basil', 'Content-Type' => 'application/json' data = { 'approved' => true } body data.to_json end # ...handle other cases end
If Stripe doesn’t receive your approve or decline response within 2 seconds, the Authorization is automatically approved or declined based on your timeout settings, or Autopilot settings, if configured.
Note
If your Issuing balance has insufficient funds for the incoming authorization, the authorization will be denied and your webhook endpoint won’t receive the issuing_ event. To learn more about funding your Issuing balance, read here.
Authorization requests
When an authorization request is sent to your webhook, the amount requested is stored in pending_.
{ "id": "iauth_1CmMk2IyNTgGDVfzFKlCm0gU", "object": "issuing_authorization", "approved": false, "amount": 0, "currency": "usd", "status": "pending", ... "pending_request": { "amount": 400, "currency": "usd", "merchant_amount": 360, "merchant_currency": "gbp" } }
The top-level amount in the request is set to 0 and approved is false. After you respond to the request, the top-level amount reflects the total amount approved or declined, the approved field is updated, and pending_ is set to null.
Testing webhooks locally
To test webhooks locally, you can use Stripe CLI. After you install it, you can forward events to your server:
stripe listen --forward-to localhost:4242/webhook Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
In another terminal, you can then manually trigger issuing_ events from the CLI for more streamlined testing.
stripe trigger issuing_authorization.request
Learn more about setting up webhooks.
Monitor your webhook responses
Monitor your webhook responses for timeouts and errors by subscribing to the issuing_ and issuing_ webhook events. When the request_history.reason property is either webhook_ or webhook_, Stripe isn’t receiving your responses. Don’t rely on approved to gauge integration health because Autopilot can approve on your behalf during an error condition. For example, investigate if an authorization has approved: true but request_. We surface detailed error messages in the request_history.reason_message field.
Autopilot Public preview
Autopilot provides fallback options that allow you to continue making real-time authorization decisions when your systems are down, don’t respond to an authorization request, or provide an invalid response.
Autopilot makes an authorization decision on your behalf based on a predefined set of rules. We create Authorization objects for transmission to reconcile Autopilot transactions. When Autopilot approves or declines an authorization, the request_history.reason property of the issuing_ webhook is either webhook_ or webhook_:
webhook_if you respond to the real-time authorization webhook with an invalid Stripe API version in the request headers, or if we can’t process your response.error webhook_for all other failure modes.timeout
To configure Autopilot, contact Stripe support, and monitor.
Stripe Autopilot Public preview
For users with their own dedicated Bank Identification Numbers (BIN), Stripe Autopilot can help make authorization decisions when the card network can’t reach Stripe.
When an authorization is approved or declined through Stripe Autopilot while Stripe is down, the request_history.reason property of the issuing_ webhook is network_.
In some cases, Stripe declines an authorization but can’t communicate with the card network, and the network approves the authorization. When that happens, Stripe doesn’t hold the authorized funds, but they might still be captured.
To configure Stripe Autopilot, contact Stripe support, and monitor.
Fraud challenges through webhooks Public preview
Fraud challenges allow your cardholders to retry non-fraudulent transactions that would have otherwise been blocked. While fraud challenges are generally available, the ability to trigger them yourself through real-time webhook responses is in public preview.
To manage the rules that dictate when a fraud challenge is sent, adjust your response to the issuing_ webhook. You can trigger fraud challenges in scenarios where you detect spending that appears suspicious and want additional verification (for example, a cardholder using their card out of the country).
To do so, decline the issuing_ webhook and include the send_ field with the ["sms"] value.
Triggering fraud challenges through real-time webhook responses is currently limited to preview users. You must be an Issuing customer to join the preview. To request access to the preview, log in to your Stripe account and refresh the page. Contact Stripe for more information.