Fleet integration guide

Build a Fleet financial services integration with Issuing.

Build a fleet offering by using Stripe Issuing to create cards and process transactions for your customers’ business.

By the end of this guide, you’ll know how to:

Create verified connected accounts representing your business customers.
Create cards for your business customers and use these cards to spend funds.
Understand the additional fleet specific fields collected at the pump or point of sale.

Before you begin

Sign up for a Stripe account.
Activate Issuing in a sandbox environment from the Dashboard.
Configure your Connect platform branding settings for your business and add an icon.

Overview

Stripe Issuing enables fleet management platforms and operators to create and manage customized fleet card programs with physical or virtual payment cards. Issuing allows users to efficiently control, manage, and reconcile expenses related to their clients’ electric or traditional fuel vehicle fleets.

Stripe’s platform provides advanced capabilities with open-loop cards accepted anywhere, real-time spend controls at the point of purchase, advanced fraud protection leveraging Stripe’s fraud tools and authorization signals, and the ability to define card benefits unique to your program, such as 1% cashback on fuel spend. Fleet providers can also issue cards tied to individual or groups of vehicles, facilitating precise expense tracking (including odometer readings) and limiting spend to authorized drivers, merchants, or certain purchase categories.

Stripe’s platform provides data access to identify insights in spend patterns, mileage, maintenance, and transaction details, allowing businesses to customize their fleet program. This approach provides greater operational efficiency with realized cost savings, as well as an oversight of card-based expenditure across fuel, repairs, food, accommodation, and more.

Create connected accounts

Create a connected account

Create a connected account to represent a business customer of your platform. For your platform, each fleet operator would be represented as a connected account.

Connect account types

Issuing only supports connected accounts that don’t use a Stripe-hosted Dashboard, and where your platform is responsible for requirements collection and loss liability, also known as a Custom connected account. Learn how to create connected accounts that work with Issuing. If your existing accounts don’t match this configuration, you must recreate them.

The following request creates a US-based connected account with the correct configuration and requests the requisite capabilities:

The user’s account information appears in the response:

{
    ...
    "id":   "{{CONNECTED_ACCOUNT_ID}}",
    "controller": {
      "stripe_dashboard": {
        "type": "none"
      },
      "fees": {
        "payer": "application"
      },
      "losses": {
        "payments": "application"
      },
      "is_controller": true,
      "type": "application",
      "requirement_collection": "application"
    },
    ...
}

Note the connected account’s id. You’ll provide this value to authenticate as the connected account by passing it into requests in the Stripe-Account header.

If a connected account already exists, you can add the requisite capabilities by specifying the connected account id in the request:

Verify the connected account

Choose one of the following onboarding options:

Stripe-hosted onboarding is a web form hosted by Stripe with your brand’s name, color, and icon. Stripe-hosted onboarding uses the Accounts API to read the requirements and generate an onboarding form with robust data validation and is localized for all Stripe-supported countries.

Before using Connect Onboarding, you must provide the name, color, and icon of your brand in the Branding section of your Connect settings page.

You can use hosted onboarding to allow connected accounts to link an external_account (which is required for payouts) by enabling it through your Connect Onboarding settings.

To create an onboarding link for the connected account, use the Account Links API.

Caution

For security reasons, don’t email, text, or send account link URLs directly to your connected account. We recommend that you distribute the account link URL from within your platform’s application, where their account is authenticated.

The response you receive includes the url parameter containing the link for your connected account to onboard to your platform.

{
  "object": "account_link",
  "created": 1612927106,
  "expires_at": 1612927406,
  "url": "https://connect.stripe.com/setup/s/…"
}

At this point, Stripe has created and verified the connected account with active relevant capabilities to use Issuing and Treasury.

To learn more, see:

Create cardholders and cards

The Cardholder is the individual driver (that is, employee or contractor) that’s authorized by your business customer to use card funding by the associated balance. The Cardholder object includes relevant details, such as a name to display on cards and a billing address, which is usually the business address of the connected account or your platform.

Use the embedded Issuing cards list component to enable your connected accounts to create a Card for a Cardholder and associate it with the Financial Account.

When creating an Account Session, enable the Issuing cards list component by specifying issuing_cards_list in the components parameter. You can enable or disable individual features of the Issuing cards list component by specifying the features parameter under issuing_cards_list.

After creating the account session and initializing ConnectJS, you can render the Issuing cards list component in the front end:

From here, users can click Create card to begin creating a new Cardholder and Card. The user can also activate the card during creation, or do so afterwards.

At this point, there’s an active card attached to a cardholder and financial account. See the Issuing page for the connected account to view the card and cardholder information.

To learn more, see:

Use the card

When a card is used to make a purchase, it generates an authorization request, which can be approved or declined in real-time.

With a configured fleet card program, you’ll access additional fleet-specific fields gathered at the pump or point of sale. This includes odometer reading, driver identification, fuel type, gallons pumped, and itemized non-fuel product details, enabled by a fleet-specific chip configuration on the card. This data becomes available at the point of purchase during authorization, and later when the transaction is processed. Some fuel dispensers allow partial authorization.

Create an authorization

To observe the impact of card activity on the associated balance, generate a test authorization.

As a user with a Commercial Fleet card program, you receive specific fleet-related data on the Authorization object.

You can create a test authorization on the Issuing page of the Dashboard for the connected account, or with the following call to the Authorizations API:

After approval, Stripe creates an Authorization in a pending state while it waits for capture.

The authorized amount is the default amount held for a fuel dispenser transaction unless you’ve provided a different partial authorization amount in your response to the issuing_authorization.request webhook.

Make note of the authorization id that you’ll use to capture the funds:

{
  "id": "iauth_1NvPyY2SSJdH5vn2xZQE8C7k",
  "object": "issuing.authorization",
  "amount": 10000,
  ...
  "fleet": {
    "cardholder_prompt_data": {
      "odometer": 42424,
    },
    "purchase_type": "fuel_purchase",
    "service_type": "self_service",
  },
  "status": "pending",
  "transactions": [],
}

Simulate fuel dispenser completion

In testing environments, you can simulate the completion of fuel being dispensed using the following code:

The Authorization remains in a pending state until it’s captured. The amount is updated to reflect the total amount of fuel dispensed, and additional fleet-specific fields are now available:

{
  "id": "iauth_1NvPyY2SSJdH5vn2xZQE8C7k",
  "object": "issuing.authorization",
  "amount": 1000,
  ...
  "fleet": {
    "cardholder_prompt_data": {
      "odometer": 42424,
    },
    "purchase_type": "fuel_purchase",
    "reported_breakdown": {
      "fuel": {
        "gross_amount_decimal": "10.0",
      },
      "non_fuel": {
        "gross_amount_decimal": "0"
      },
      "tax": {
        "local_amount_decimal": "0.03",
        "national_amount_decimal": null
      }
    },
    "service_type": "self_service",
  },
  "fuel": {
    "industry_product_code": "001",
    "quantity_decimal": "5.0",
    "type": "unleaded_regular",
    "unit": "us_gallon",
    "unit_cost_decimal": "200",
  },
  "status": "pending",
  "transactions": [],
}

Capture the funds

In testing environments, you can capture the funds using the following code:

After the authorization is captured, Stripe creates an Issuing Transaction, the status of the authorization is set to closed.

As a user with a Commercial Fleet card program, you receive specific fleet-related data on the Transaction, (for example, to reconcile purchases).

{
  "id": "ipi_1MykXhFtDWhhyHE1UjsZZ3xQ",
  "object": "issuing.transaction",
  "amount": 1000,
  ...
  "purchase_details": {
    "fleet": {
      "cardholder_prompt_data": {
        "odometer": 42424,
      },
      "purchase_type": "fuel_purchase",
      "reported_breakdown": {
        "fuel": {
          "gross_amount_decimal": "10.0",
        },
        "non_fuel": {
          "gross_amount_decimal": "0"
        },
        "tax": {
          "local_amount_decimal": "0.03",
          "national_amount_decimal": null
        }
      },
      "service_type": "self_service",
    },
    "fuel": {
      "industry_product_code": "001",
      "quantity_decimal": "5.0",
      "type": "unleaded_regular",
      "unit": "us_gallon",
      "unit_cost_decimal": "200",
    },
  }
}