Real-Time Decisions

We recommend first reading our Webhooks guide for background.

Overview

Occasionally Increase needs to know what action to take on a user-initiated request in real time. The canonical example of this is when a user tries to use their card and Increase has to decide to approve the authorization or not. When this happens, we'll create a Real-Time Decision object in the API and send you a special real-time webhook.

Real-time webhooks

Real-time webhooks behave generally similarly to regular webhooks, but are delivered with zero latency from when they’re initiated. Additionally, they’re only delivered to a single Event Subscription webhook. You must explicitly create an Event Subscription with a selected_event_category of that specific event category, and only one Event Subscription with a selected_event_category that occurs in real-time can be active at once.

Real-time decisions

Real-Time Decisions are a regular API resource in the Increase API. When we need a decision from your application, we will create one, create an Event to indicate that it has been created, and send that Event to you in real-time via webhook as described above. At this point, your application will have 2-4 seconds (depending on the type of decision) to make a decision. You tell us your decision by POSTing to the Real-Time Decision action endpoint:

POST https://api.increase.com/real_time_decisions/{real_time_decision_id}/action

Depending on the type of decision, additional metadata might be required. For example, if a user is trying to add their card to their Apple Pay Wallet, your application might need to reply with the artwork the user should see. These metadata fields are exposed as properties of the above API endpoint.

It’s currently required that your application complete this HTTP request before responding to the webhook.

Example: responding to card authorizations in real time

Start by creating an Event Subscription via the API with selected_event_category: real_time_decision.card_authorization_requested. This webhook listener will only receive real-time authorization webhooks. The event payload your application will see looks like:

  {
    associated_object_id: string,
    associated_object_type: 'real_time_decision',
    category: 'real_time_decision.card_authorization_requested',
    created_at: string,
    id: string,
    type: 'event'
  }

This event references a Real-Time Decision object in our API.

In your webhook implementation, you should:

• Make a GET request to https://api.increase.com/real_time_decisions/{id}, replacing {id} with the value of associated_object_id in the webhook event payload. The response will look like:

  {
    id: string;
    created_at: string,
    timeout_at: string,
    status: 'pending',
    category: 'card_authorization_requested',
    card_authorization: {
      decision: null,
      card_id: string,
      account_id: string,
      presentment_amount: integer,
      presentment_currency: string,
      settlement_amount: integer,
      settlement_currency: string,
      merchant_category_code: string,
      merchant_acceptor_id: string,
      merchant_city: string | null,
      merchant_country: string,
      merchant_descriptor: string,
    },
    type: 'real_time_decision',
  }
  

• Decide if you want to approve or reject the authorization based on its properties.

• Make a POST request to https://api.increase.com/real_time_decisions/{id}/action to approve or decline the authorization with a JSON payload of:

  {
    "card_authorization": {
      "decision": "approve" | "decline"
    }
  }
  

• Respond with a 200 status code and any body. Note that you must synchronously wait for your approve/decline POST request to complete before your webhook responds with a 200.

Notes

Because of the short timeout, we won't retry webhooks that don't respond with a 200.

An easy way to test your webhook is to create a Card in the Increase Dashboard and then try to charge it in the Stripe dashboard. If you don't feel like going over live payment networks, you can also simulate an authorization via our API in the sandbox. (Note you'll need to create a separate Event Subscription in the sandbox before this will work.)