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.
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.
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.
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.
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
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
company) and handling either value on reads.
amountwill always be the total sum authorized or denied for capture in the cardholder currency. Unlike
held_amount, it will not drop to zero upon capture.
- Amount held by an authorization can be obtained by sum of its balance_transactions amounts.
merchant_amountwill always be the total sum authorized or denied for capture in the merchant currency. Unlike
merchant_amountcan be reduced by reversals.
amountin the approve an authorization endpoint.
- Added a pending_request hash. This will only be populated during a synchronous webhook request for real-time authorizations.
- Renamed attributes of hashes in request_history:
- Discontinued several values for request_history.reason.
incorrect_expiryhave been consolidated into
verification_failed. For more detail, use authorization.verification_data.
account_inactivehave been replaced with
spending_controlsto be consistent with the renamed attributes in the Card and Cardholder resources.
verification_data.authenticationenum in favor of the more descriptive
three_d_secure.result, which replaces
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.
- Removed the following type values since they were uncommon and can be represented in other ways:
dispute_loss. A Disputes API is under development.
- Stopped creating a second
disputeto represent a won
Dispute’s money movement. Instead, we will add
balance_transactionsdirectly to the
- Consequently, there will be no
Disputemoney movement. Instead, we’ll have a new event which will send the updated
- Consequently, there will be no
disputequery param from list all transactions endpoint.
settlementquery param from list all transactions endpoint to Settlement feature users.
purchase_detailsfor enhanced transaction data.
- Removed the
is_defaultattribute. As a consequence,
cardholderis a required parameter when creating a new card. The list all cardholders endpoint no longer accepts
is_defaultas a query parameter.
- Renamed type from
companyto better align with hashes that contain additional information.
billing.namesince it’s always the same as the top-level
nameattribute on the resource.
stolencard statuses. These are represented as canceled with an optional cancellation_reason provided.
- Renamed replacement_reason values:
name. Please refer to cardholder.name instead.
shipping.speedenum to shipping.service. The
overnightvalue has been renamed
- Added replaced_by, to point to the card that replaced the current card.
authorization_controlsto spending_controls and removed
currency. We recommend using
amount-based limits for more accurate control over card spend.
merchant_data.urlwill only be available to users enrolled in 3D Secure feature.
pinwill only be available to users enrolled in PIN management feature.
- The list all cards endpoint will no longer accept
- The retrieve card details endpoint has been discontinued. Instead, number and cvc can be expanded from the retrieve endpoint.
balance_transactionswhich will contain all BalanceTransactions associated with a
BalanceTransactionwill have a new
reporting_categorycorresponding to an Issuing
description: "Issuing dispute"
reporting_category: "Issuing Dispute"
- We will send a new event,
issuing_dispute.funds_reinstated, with the updated
Disputehas been won.
- The following events are restricted to users enrolled in the Settlement feature: