Migration guide for v20

Version 20 of stripe-dotnet contains some very sizable breaking changes.

The major reason that we moved forward on them was to clean up the abstraction around properties or endpoints that can return more than one resource. Before, we had a class that pointed to each potential sub-resource along with a Type property to indicate which one was filled. We wanted to replace this with an interface to make it easier to integrate and match the API more closely.

Because this is a large change, we also took the opportunity to do some housekeeping throughout the library. Most of this involves renaming fields and some resources to be more accurate according to how they're named in Stripe's REST API, but it also involves some smaller changes like moving some types and constants around.

Please see the list below for the complete set of changes.

Removal of the Stripe prefix

Nearly all classes exposed by the library have been renamed to remove the Stripe prefix, to avoid redundancy with the Stripe namespace. For example:

• StripeCharge is now Charge
• StripeRefundService is now RefundService

Interfaces for polymorphic resources

Resources where the exact type is not known in advance are now represented by interfaces:

• IBalanceTransactionSource represents all resources that can be the source of a balance transaction.
• IExternalAccount represents all resources that can be used to receive payouts. This can be a BankAccount or a Card.
• IPaymentSource represents all resources that can be used to create a charge. This can be an Account, BankAccount, Card, BankAccount or Source.
• IHasObject represents all Stripe resources with an Object property.

Since the concrete type represented by the interface can only be known at runtime, you'll probably want to use pattern matching to use the correct type. For instance:

IPaymentSource chargeSource = charge.Source;
if (chargeSource is Account account)
{
    // Do something with account
}
else if (chargeSource is BankAccount bankAccount)
{
    // Do something with bankAccount
}
else if (chargeSource is Card card)
{
    // Do something with card
}
else if (chargeSource is Source source)
{
    // Do something with source
}

Of course, if you already know the concrete type, you can cast directly. For instance, if your integration only accepts card payments, you could simply do this:

Card card = charge.Source as Card;

Likewise, the Data.Object property of Event objects is now typed as IHasObject. Previously, it was typed as dynamic. You can now use pattern matching to cast it to the correct type, or cast it directly by deducing the concrete type from the event's Type property. For instance:

if (event.Type == "source.chargeable")
{
    Source source = event.Data.Object as Source;
    // Do something with source
}
else if (event.Type == "invoice.created")
{
    Invoice invoice = event.Data.Object as Invoice;
    // Do something with invoice
}

Removal of StripeDeleted

The StripeDeleted class has been removed. All Delete methods now return an instance of the resource with Deleted set to true.

Nullable value types in options classes

All properties with value types in options classes are now nullable.

Source class

The old StripeSource class is now named Source.

The old Source class is gone, as its purpose is now filled by the IPaymentSource interface.

Changes to property names

Some properties in resource and options classes have been renamed so that they're more consistent with their name in Stripe's REST API or the rest of the library. For example:

• DateFilter on List APIs is now DateRangeOptions
• LiveMode is now Livemode
• BirthDay is now Dob
• LegalEntityVerification is now Verification

Nested parameters

Most options classes used as parameters for API methods with nested parameters have been modified to reflect the structure in Stripe's REST API. For example PersonalAddressLine1 on StripeAccountLegalEntityOptions has now been renamed to Line1 on AddressOptions which is itself under PersonalAddress on AccountLegalEntityOptions.

InvoiceItem and InvoiceItemService

We now have a dedicated service and related classes for the invoice item resource instead of using the ones for the invoice line item resource.

Changes to UsageRecordService

Methods for UsageRecordService now take a subscription item ID as the first parameter.

API version upgraded to 2018-09-24

Moved to API version 2018-09-24 leading to the following changes:

• Removal of StripeFileUpload in favour of File.
• The TransactionId parameter on the Issuing Create Dispute API is now called DisputedTransactionId.

Normalization of integer properties

All integer values now use long as their type instead of int.