B2B Payments integration guide

To spend money using cards, add funds to the Issuing balance on your account. This balance represents funds reserved for Issuing and is safely separated from your earnings, payouts, and funds from other Stripe products.

You can add funds from your Dashboard or using the create top-up endpoint.

curl https://api.stripe.com/v1/topups \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d destination_balance=issuing \
  -d amount=2000 \
  -d currency=usd \
  -d description="Top-up for Issuing, 21 December 2024" \
  -d statement_descriptor=Top-up

Create a cardholder

The Cardholder is the company or business entity that’s authorised to use card funding by the Issuing 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.

The following API call creates a new Cardholder:

curl https://api.stripe.com/v1/issuing/cardholders \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d name="Company Card" \
  --data-urlencode email="company@example.com" \
  --data-urlencode phone_number="+18008675309" \
  -d status=active \
  -d type=company \
  -d "billing[address][line1]"="123 Main Street" \
  -d "billing[address][city]"="San Francisco" \
  -d "billing[address][state]"=CA \
  -d "billing[address][postal_code]"=94111 \
  -d "billing[address][country]"=US

Stripe returns a Cardholder object that contains the information you provided and sends the issuing_cardholder.created webhook event.

Create a card

Create a card and attach it to the Cardholder that you want to make the authorised user of the card.

In the following examples, we show you how to create a virtual card. You can, however, create physical cards and ship them to cardholders in live mode.

curl https://api.stripe.com/v1/issuing/cards \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d currency=usd \
  -d type=virtual \
  -d cardholder=
{{CARDHOLDER_ID}}

Stripe returns a Card object on creation, and sends the issuing_card.created webhook event:

{
  "id": "ic_1NvPjF2SSJdH5vn2OVbE7r0b",
  "object": "issuing.card",
  "brand": "Visa",
  ...
  "status": "inactive",
  "type": "virtual"
}

You need to activate the card before a user can use it. While you can activate virtual cards in the same API call you used to create it, physical cards must be activated separately. When ready, activate the card by marking the status as active:

curl https://api.stripe.com/v1/issuing/cards/ic_1NvPjF2SSJdH5vn2OVbE7r0b \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d status=active

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

{
  "id": "ic_1NvPjF2SSJdH5vn2OVbE7r0b",
  "object": "issuing.card",
  "brand": "Visa",
  ...
  "status": "active",
  "type": "virtual",
}

To learn more, see:

• Virtual cards
• Physical cards
• Use the Dashboard for Issuing with Connect
• Create cards with the API

Create an authorisation

To observe the impact of card activity on the associated balance, generate a test authorisation. You can do this in the Issuing page of the Dashboard for the connected account, or with the following call to the Authorisation API:

curl https://api.stripe.com/v1/test_helpers/issuing/authorizations \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d card=
{{CARD_ID}} \
  -d amount=1000 \
  -d authorization_method=chip \
  -d "merchant_data[category]"=taxicabs_limousines \
  -d "merchant_data[city]"="San Francisco" \
  -d "merchant_data[country]"=US \
  -d "merchant_data[name]"="Rocket Rides" \
  -d "merchant_data[network_id]"=1234567890 \
  -d "merchant_data[postal_code]"=94107 \
  -d "merchant_data[state]"=CA

After approval, Stripe creates an Authorization in a pending state while it waits for capture. Note the authorisation id that you’ll use to capture the funds:

{
  "id": "iauth_1NvPyY2SSJdH5vn2xZQE8C7k",
  "object": "issuing.authorization",
  "amount": 1000,
  ...
  "status": "pending",
  "transactions": [],
}

Capture the funds

Capture the funds using the following code:

curl -X POST https://api.stripe.com/v1/test_helpers/issuing/authorizations/
{{AUTHORIZATION_ID}}
/capture \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

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