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 | Version in YYYY-dd-mm format. |
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. |
Make an API call Deprecated
This documentation is maintained for existing users. If you’re a new user, respond directly to the webhook. If you’re an existing user, plan to migrate to the direct webhook response. You can follow our direct webhook migration guide.
Make an API call to either approve or decline the request and include the Authorization ID. If you use this method, your webhook must approve or decline each authorization before responding to the incoming webhook request.
We recommend that you only use one of these two methods to respond to authorization requests. For users migrating from one method to another, both methods are supported during a migration. In the event both methods are used on the same authorization, the API call takes precedence over the direct response. For migrations, we recommend only using one method on a given request at a time.
If Stripe doesn’t receive your approve or decline response or request within 2 seconds, the Authorization
is automatically approved or declined based on your timeout settings.
Note
If your Issuing balance has insufficient funds for the incoming authorization, the authorization will be denied and your webhook endpoint will not 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. Once 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. Once you have it installed, 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.
Autopilot Public Preview
Autopilot is a set of fallback options that allow you to continue making real-time authorization decisions in the event your systems are down or don’t respond to an authorization request within the allotted time window.
For users with their own dedicated Bank Identification Numbers (BIN), we also offer Autopilot in the event that Stripe can’t communicate with the network to prevent any continuity issues that might result.
In both cases, we make an authorization decision on your behalf based on a predefined set of rules. We create authorization objects for transmission, so that reconciliation can take place for the Autopilot transactions. When an authorization is approved or declined through Autopilot while you’re down, the request_
field within the issuing_
webhook changes to webhook_
. When an authorization is approved or declined through Autopilot while Stripe is down, the request_
field within the issuing_
webhook changes to network_
.
Access to Autopilot is currently limited to US beta users. You must be an Issuing customer to join the beta. To request access to the beta, log in to your Stripe account and refresh the page. Contact Stripe for more information.
Fraud challenges Public Preview
Fraud challenges allow your cardholders to retry non-fraudulent transactions that would have otherwise been blocked.
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.
Fraud challenges are currently limited to beta users. You must be an Issuing customer to join the beta. To request access to the beta, log in to your Stripe account and refresh the page. Contact Stripe for more information.