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 will be discontinuing the beta API on March 1, 2021. Below we have outlined all the changes to the API to help with your migration. Please contact support with any questions.
Compatibility
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 have 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 have 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_
has been renamed company
. Existing cardholder objects will continue to show the old value, business_
. New objects can be created with business_
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_
withamount amount
.amount
will always be the total sum authorized or denied for capture in the cardholder currency. Unlikeheld_
, it will not drop to zero upon capture.amount - Amount held by an authorisation can be obtained by sum of its balance_transactions amounts.
- Renamed
held_
tocurrency currency
. - Replaced
authorized_
withamount merchant_
.amount merchant_
will always be the total sum authorized or denied for capture in the merchant currency. Unlikeamount authorized_
,amount merchant_
can be reduced by reversals.amount - Renamed
authorized_
tocurrency merchant_
.currency - Renamed
held_
toamount amount
in the approve an authorisation endpoint. - Added a pending_request hash. This will only be populated during a synchronous webhook request for real-time authorisations.
- Replaced
pending_
withheld_ amount pending_
.request. amount - Replaced
pending_
withauthorized_ amount pending_
.request. merchant_ amount - Replaced
is_
withheld_ amount_ controllable pending_
.request. is_ amount_ controllable
- Replaced
- Renamed attributes of hashes in request_history:
- Renamed
request_
tohistory. held_ amount request_
.history. amount - Renamed
request_
tohistory. held_ currency request_
.history. currency - Renamed
request_
tohistory. authorized_ amount request_
.history. merchant_ amount - Renamed
request_
tohistory. authorized_ currency request_
.history. merchant_ currency - Removed
request_
.history. violated_ authorization_ controls
- Renamed
- Discontinued several values for request_history.reason.
authentication_
,failed incorrect_
, andcvc incorrect_
have been consolidated intoexpiry verification_
. For more detail, use authorization.verification_data.failed account_
andcompliance_ disabled account_
have been replaced withinactive account_
.disabled authorization_
was renamedcontrols spending_
to be consistent with the renamed attributes in the Card and Cardholder resources.controls
- Discontinued
verification_
enum in favor of the more descriptivedata. authentication verification_
hash.data. three_ d_ secure three_
, which replacesd_ secure. result authentication
, contains more values than before. A full overview of the new values can be found here.- This attribute will only be visible to users enrolled in the 3D Secure feature.
- Renamed
verification_
to verification_data.address_postal_code_check.data. address_ zip_ check - Renamed
wallet_
attribute toprovider wallet
.
Transaction
- Removed the following type values since they were uncommon and can be represented in other ways:
cash_
(nowwithdrawal capture
)refund_
(nowreversal refund
with negativeamount
)dispute
anddispute_
. A Disputes API is under development.loss
- Stopped creating a second
Transaction
of typedispute
to represent a wonDispute
’s money movement. Instead, we will addbalance_
directly to thetransactions Dispute
.- Consequently, there will be no
issuing_
event fortransaction. created Dispute
money movement. Instead, we’ll have a new event which will send the updatedDispute
withbalance_
.transactions
- Consequently, there will be no
- Removed
dispute
query param from list all transactions endpoint. - Restricted
settlement
query param from list all transactions endpoint to Settlement feature users. - Added
purchase_
for enhanced transaction data.details
Cardholder
- Removed the
is_
attribute. As a consequence,default cardholder
is a required parameter when creating a new card. The list all cardholders endpoint no longer acceptsis_
as a query parameter.default - Renamed type from
business_
toentity company
to better align with hashes that contain additional information. - Removed
billing.
since it’s always the same as the top-levelname name
attribute on the resource. - Renamed
authorization_
to spending_controls.controls
Card
- Removed
lost
andstolen
card statuses. These are represented as cancelled with an optional cancellation_reason provided. - Renamed
authorization_
to spending_controls.controls
- Renamed replacement_reason values:
loss
tolost
theft
tostolen
damage
todamaged
expiration
toexpired
- Removed
name
. Please refer to cardholder.name instead. - Renamed
shipping.
enum to shipping.service. Thespeed overnight
value has been renamedpriority
. - Added replaced_by, to point to the card that replaced the current card.
- Renamed
authorization_
to spending_controls and removedcontrols max_
,approvals max_
, andamount currency
. We recommend usingamount
-based limits for more accurate control over card spend. merchant_
will only be available to users enrolled in 3D Secure feature.data. url pin
will only be available to users enrolled in PIN management feature.- The list all cards endpoint will no longer accept
source
andname
parameters. - The retrieve card details endpoint has been discontinued. Instead, number and CVC can be expanded from the retrieve endpoint.
Disputes
- Renamed
disputed_
totransaction transaction
. - Added
balance_
which will contain all BalanceTransactions associated with atransactions Dispute
.- Each
BalanceTransaction
will have a newtype
,source
,description
andreporting_
corresponding to an Issuingcategory Dispute
as follows:type: "issuing_
dispute" source: "idp_
1FMjf1GprvsjVv9gffmDmLGx" description: "Issuing dispute"
reporting_
category: "Issuing Dispute"
- Each
- We will send a new event,
issuing_
, with the updateddispute. funds_ reinstated Dispute
and newBalanceTransaction
when aDispute
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.
balance has been removed from the Balance object. Please refer to the issuing.available balance instead.pending