Issuing beta migration guide
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_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
withamount
.amount
will always be the total sum authorized or denied for capture in the cardholder currency. Unlikeheld_amount
, it will not drop to zero upon capture.- Amount held by an authorization can be obtained by sum of its balance_transactions amounts.
- Renamed
held_currency
tocurrency
. - Replaced
authorized_amount
withmerchant_amount
.merchant_amount
will always be the total sum authorized or denied for capture in the merchant currency. Unlikeauthorized_amount
,merchant_amount
can be reduced by reversals. - Renamed
authorized_currency
tomerchant_currency
. - Renamed
held_amount
toamount
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
withpending_request.amount
. - Replaced
pending_authorized_amount
withpending_request.merchant_amount
. - Replaced
is_held_amount_controllable
withpending_request.is_amount_controllable
.
- Replaced
- Renamed attributes of hashes in request_history:
- Renamed
request_history.held_amount
torequest_history.amount
. - Renamed
request_history.held_currency
torequest_history.currency
. - Renamed
request_history.authorized_amount
torequest_history.merchant_amount
. - Renamed
request_history.authorized_currency
torequest_history.merchant_currency
. - Removed
request_history.violated_authorization_controls
.
- Renamed
- Discontinued several values for request_history.reason.
authentication_failed
,incorrect_cvc
, andincorrect_expiry
have been consolidated intoverification_failed
. For more detail, use authorization.verification_data.account_compliance_disabled
andaccount_inactive
have been replaced withaccount_disabled
.authorization_controls
was renamedspending_controls
to be consistent with the renamed attributes in the Card and Cardholder resources.
- Discontinued
verification_data.authentication
enum in favor of the more descriptiveverification_data.three_d_secure
hash.three_d_secure.result
, which replacesauthentication
, 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_data.address_zip_check
to verification_data.address_postal_code_check. - Renamed
wallet_provider
attribute towallet
.
Transaction
- Removed the following type values since they were uncommon and can be represented in other ways:
cash_withdrawal
(nowcapture
)refund_reversal
(nowrefund
with negativeamount
)dispute
anddispute_loss
. A Disputes API is under development.
- Stopped creating a second
Transaction
of typedispute
to represent a wonDispute
’s money movement. Instead, we will addbalance_transactions
directly to theDispute
.- Consequently, there will be no
issuing_transaction.created
event forDispute
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_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 acceptsis_default
as a query parameter. - Renamed type from
business_entity
tocompany
to better align with hashes that contain additional information. - Removed
billing.name
since it’s always the same as the top-levelname
attribute on the resource. - Renamed
authorization_controls
to spending_controls.
Card
- Removed
lost
andstolen
card statuses. These are represented as canceled with an optional cancellation_reason provided. - Renamed
authorization_controls
to spending_controls.
- Renamed replacement_reason values:
loss
tolost
theft
tostolen
damage
todamaged
expiration
toexpired
- Removed
name
. Please refer to cardholder.name instead. - Renamed
shipping.speed
enum to shipping.service. Theovernight
value has been renamedpriority
. - Added replaced_by, to point to the card that replaced the current card.
- Renamed
authorization_controls
to spending_controls and removedmax_approvals
,max_amount
, andcurrency
. We recommend usingamount
-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
andname
parameters. - The retrieve card details endpoint has been discontinued. Instead, number and cvc can be expanded from the retrieve endpoint.
Disputes
- Renamed
disputed_transaction
totransaction
. - Added
balance_transactions
which will contain all BalanceTransactions associated with aDispute
.- Each
BalanceTransaction
will have a newtype
,source
,description
andreporting_category
corresponding to an IssuingDispute
as follows:type: "issuing_dispute"
source: "idp_1FMjf1GprvsjVv9gffmDmLGx"
description: "Issuing dispute"
reporting_category: "Issuing Dispute"
- Each
- We will send a new event,
issuing_dispute.funds_reinstated
, with the updatedDispute
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.pending
balance has been removed from the Balance object. Please refer to the issuing.available balance instead.