Issuing beta migration guide

Learn how to migrate from the Issuing beta.

Stripe Issuing recently became generally available for all US businesses. When we exited our beta, we released pricing and changes to our API, which include features and updates to support its long-term evolution. Depending on your integration, some of these API changes will be breaking, so pay extra attention to every item in this guide.

We’ll be discontinuing the beta API on March 1, 2021. Below we’ve outlined all the changes to the API to help with your migration. Contact support with any questions.

Compatibility

To minimize disruption during migration, Stripe supports both the old and new API during the transition period.

Caution

As noted in each section, we recommend supporting both the old and new API until you’ve officially switched over. We also recommend creating a new Issuing account to test out the new API before switching over on your main account.

Attributes

For beta users, both legacy and new attributes are currently available on all Issuing objects. Renamed attributes point to the same backend value as their legacy counterpart. When the beta is discontinued, only the new attributes will be available.

To prepare, we recommend switching reads to support both the old and new attribute until you’ve successfully switched over to the new API.

Parameters

For renamed parameters, either the legacy or new name can be used but not both. When the beta is discontinued, only the new parameters will be accepted.

To prepare, we recommend switching writes to support both the old and new param until you’ve successfully switched over to the new API.

Enums

Transitioning to new enum values will be slightly more complicated. New values can be written and read back but old, existing values will continue to be returned until the beta is officially discontinued.

For example, the Cardholder type of business_entity has been renamed company. Existing cardholder objects will continue to show the old value, business_entity. New objects can be created with business_entity or company and whichever value is provided will be returned when read back.

To prepare, we recommend switching writes to the new value (for example, when creating a new cardholder set type to company) and handling either value on reads.

API Changes

Authorization

Replaced held _ amount with amount . amount will always be the total sum authorized or denied for capture in the cardholder currency. Unlike held _ amount , it won’t drop to zero upon capture.
Amount held by an authorization can be obtained by sum of its balance_transactions amounts.
Renamed held _ currency to currency .
Replaced authorized _ amount with merchant _ amount . merchant _ amount will always be the total sum authorized or denied for capture in the merchant currency. Unlike authorized _ amount , merchant _ amount can be reduced by reversals.
Renamed authorized _ currency to merchant _ currency .
Renamed held _ amount to amount in the approve an authorization endpoint.
Added a pending_request hash. This will only be populated during a synchronous webhook request for real-time authorizations.
Replaced pending _ held _ amount with pending _ request. amount .
Replaced pending _ authorized _ amount with pending _ request. merchant _ amount .
Replaced is _ held _ amount _ controllable with pending _ request. is _ amount _ controllable .
Renamed attributes of hashes in request_history :
Renamed request _ history. held _ amount to request _ history. amount .
Renamed request _ history. held _ currency to request _ history. currency .
Renamed request _ history. authorized _ amount to request _ history. merchant _ amount .
Renamed request _ history. authorized _ currency to request _ history. merchant _ currency .
Removed request _ history. violated _ authorization _ controls .
Discontinued several values for request_history.reason .
authentication _ failed , incorrect _ cvc , and incorrect _ expiry have been consolidated into verification _ failed . For more detail, use authorization.verification_data .
account _ compliance _ disabled and account _ inactive have been replaced with account _ disabled .
authorization _ controls was renamed spending _ controls to be consistent with the renamed attributes in the Card and Cardholder resources.
Discontinued verification _ data. authentication enum in favor of the more descriptive verification _ data. three _ d _ secure hash.
three _ d _ secure. result , which replaces authentication , contains more values than before. See a full overview of the new values .
This attribute will only be visible to users enrolled in the 3D Secure feature.
Renamed verification _ data. address _ zip _ check to verification_data.address_postal_code_check .
Renamed wallet _ provider attribute to wallet .

Transaction

Removed the following type values since they were uncommon and can be represented in other ways:
cash _ withdrawal (now capture )
refund _ reversal (now refund with negative amount )
dispute and dispute _ loss . A Disputes API is under development.
Stopped creating a second Transaction of type dispute to represent a won Dispute ’s money movement. Instead, we’ll add balance _ transactions directly to the Dispute .
Consequently, there will be no issuing _ transaction. created event for Dispute money movement. Instead, we’ll have a new event which will send the updated Dispute with balance _ transactions .
Removed dispute query param from list all transactions endpoint.
Restricted settlement query param from list all transactions endpoint to Settlement feature users.
Added purchase _ details for enhanced transaction data.

Cardholder

Removed the is _ default attribute. As a consequence, cardholder is a required parameter when creating a new card. The list all cardholders endpoint no longer accepts is _ default as a query parameter.
Renamed type from business _ entity to company to better align with hashes that contain additional information.
Removed billing. name since it’s always the same as the top-level name attribute on the resource.
Renamed authorization _ controls to spending_controls .

Card

Removed lost and stolen card statuses. These are represented as canceled with an optional cancellation_reason provided.
Renamed authorization _ controls to spending_controls .

Before

After

Command Line

Renamed replacement_reason values:
loss to lost
theft to stolen
damage to damaged
expiration to expired
Removed name . Refer to cardholder.name instead.
Renamed shipping. speed enum to shipping.service . The overnight value has been renamed priority .
Added replaced_by , to point to the card that replaced the current card.
Renamed authorization _ controls to spending_controls and removed max _ approvals , max _ amount , and currency . We recommend using amount -based limits for more accurate control over card spend.
merchant _ data. url will only be available to users enrolled in 3D Secure feature.
pin will only be available to users enrolled in PIN management feature.
The list all cards endpoint will no longer accept source and name parameters.
The retrieve card details endpoint has been discontinued. Instead, number and cvc can be expanded from the retrieve endpoint.

Disputes

Renamed disputed _ transaction to transaction .
Added balance _ transactions which will contain all BalanceTransactions associated with a Dispute .
Each BalanceTransaction will have a new type , source , description and reporting _ category corresponding to an Issuing Dispute as follows:
type: "issuing _ dispute"
source: "idp _ 1FMjf1GprvsjVv9gffmDmLGx"
description: "Issuing dispute"
reporting _ category: "Issuing Dispute"
We’ll send a new event, issuing _ dispute. funds _ reinstated , with the updated Dispute and new BalanceTransaction when a Dispute has been won.

Events

The following events are restricted to users enrolled in the Settlement feature:
issuing _ settlement. created
issuing _ settlement. updated

Balances

The issuing. pending balance has been removed from the Balance object. Refer to the issuing.available balance instead.