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_authorization.request and sends it to your configured endpoint for your approval.

Responding to authorization requests

Make an API call to either approve or decline the request and include the Authorization ID.

Your webhook must approve or decline each authorization before responding to the incoming webhook request. If Stripe does not receive your approve or decline request within 2 seconds, the Authorization is automatically approved or declined based on your timeout settings.

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_authorization.request event. To learn more about funding your Issuing balance, read here.

server.rb

# Using Sinatra.
require 'sinatra'
require 'stripe'

set :port, 4242
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

# Uncomment and 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']
    handle_authorization(auth)
  end

  status 200
end

def handle_authorization(auth)
  # Authorize the transaction
  authorization = Stripe::Issuing::Authorization.approve(auth["id"])
end

Authorization requests

When an authorization request is sent to your webhook, the amount requested is stored in pending_request.

{
  "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_request 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:

Terminal

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_authorization.request events from the CLI for more streamlined testing.

Terminal

stripe trigger issuing_authorization.request

Learn more about setting up webhooks.