upgrading-from-v0.7.0.md

Summary of changes

@stripe/stripe-react-native v0.8.0 brings a change to the parameters provided to the createPaymentMethod, confirmPayment, confirmSetupIntent, collectBankAccountForPayment, and collectBankAccountForSetup methods. Simply put, there are three changes:

1. Renamed the type field to paymentMethodType

• This affects the first argument to createPaymentMethod, and the second argument to confirmPayment, confirmSetupIntent, collectBankAccountForPayment, and collectBankAccountForSetup

2. Moved all other payment method data to a nested object under the paymentMethodData key.

• This affects the first argument to createPaymentMethod, and the second argument to confirmPayment, confirmSetupIntent, collectBankAccountForPayment, and collectBankAccountForSetup

3. Moved setupFutureUsage to the options argument

• This means you'll now pass setupFutureUsage to the third argument of confirmPayment and confirmSetupIntent, instead of the second argument.

4. Renamed type field to paymentMethodType on PaymentMethod.Result, PaymentIntent.Result, and SetupIntent.Result

• These types are returned by the following methods: createPaymentMethod, retrieveSetupIntent, confirmSetupIntent, confirmPayment, collectBankAccountForPayment, collectBankAccountForSetup, verifyMicrodepositsForPayment, or verifyMicrodepositsForSetup.

Examples

Below are the old payment method type formats, followed by the new ones. This represents the object you would pass as the first argument to createPaymentMethod, and the second argument to confirmPayment, confirmSetupIntent, collectBankAccountForPayment, and collectBankAccountForSetup.

Card

Before:

{
  type: 'Card',
  token: string,
  billingDetails: BillingDetails,
}
// OR
{
  type: 'Card',
  paymentMethodId: string,
  cvc: string,
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'Card',
  paymentMethodData: {
    token: string,
    billingDetails: BillingDetails,
  }
}
// OR
{
  paymentMethodType: 'Card',
  paymentMethodData: {
    paymentMethodId: string,
    cvc: string,
    billingDetails: BillingDetails,
  }
}

Ideal

Before:

{
  type: 'Ideal',
  bankName: string,
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'Ideal',
  paymentMethodData: {
    bankName: string,
    billingDetails: BillingDetails,
  }
}

Fpx

Before:

{
  type: 'Fpx',
  testOfflineBank: boolean
}

After

{
  paymentMethodType: 'Fpx',
  paymentMethodData: { testOfflineBank: boolean }
}

Alipay

Before:

{
  type: 'Alipay',
}

After

{
  paymentMethodType: 'Alipay',
}

Oxxo

Before:

{
  type: 'Oxxo',
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'Oxxo',
  paymentMethodData: {
    billingDetails: BillingDetails,
  }
}

Sofort

Before:

{
  type: 'Sofort',
  country: string,
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'Sofort',
  paymentMethodData: {
    country: string,
    billingDetails: BillingDetails,
  }
}

GrabPay

Before:

{
  type: 'GrabPay',
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'GrabPay',
  paymentMethodData: {
    billingDetails: BillingDetails,
  }
}

Bancontact

Before:

{
  type: 'Bancontact',
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'Bancontact',
  paymentMethodData: {
    billingDetails: BillingDetails,
  }
}

SepaDebit

Before:

{
  type: 'SepaDebit',
  iban: string,
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'SepaDebit',
  paymentMethodData: {
    iban: string,
    billingDetails: BillingDetails,
  }
}

Giropay

Before:

{
  type: 'Giropay',
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'Giropay',
  paymentMethodData: {
    billingDetails: BillingDetails,
  }
}

AfterpayClearpay

Before:

{
  type: 'AfterpayClearpay',
  shippingDetails: ShippingDetails,
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'AfterpayClearpay',
  paymentMethodData: {
    shippingDetails: ShippingDetails,
    billingDetails: BillingDetails,
  }
}

Klarna

Before:

{
  type: 'Klarna',
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'Klarna',
  paymentMethodData: {
    billingDetails: BillingDetails,
  }
}

Eps

Before:

{
  type: 'Eps',
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'Eps',
  paymentMethodData: {
    billingDetails: BillingDetails,
  }
}

P24

Before:

{
  type: 'P24',
  billingDetails: BillingDetails,
}

After

{
  paymentMethodType: 'P24',
  paymentMethodData: {
    billingDetails: BillingDetails,
  }
}

AuBecsDebit

Before:

{
  type: 'AuBecsDebit',
  formDetails: FormDetails,
}

After

{
  paymentMethodType: 'AuBecsDebit',
  paymentMethodData: {
    formDetails: FormDetails,
  }
}

USBankAccount

Before:

{
  type: 'USBankAccount',
  billingDetails: BillingDetails,
  accountNumber: string,
  routingNumber: string,
  accountHolderType: BankAcccountHolderType,
  accountType: BankAcccountType,
}

After

{
  paymentMethodType: 'USBankAccount',
  paymentMethodData: {
    billingDetails: BillingDetails,
    accountNumber: string,
    routingNumber: string,
    accountHolderType: BankAcccountHolderType,
    accountType: BankAcccountType,
  }
}

Why did you make this change? It's annoying for me to have to make these adjustments.

We completely understand, especially since this basically just feels like a rename. And if you're not using TypeScript, then this migration is much harder.

This change will help us smoothly add in future payment methods with multiple "attach" options, like we've done with the new USBankAccount payment method. It also more closely matches parameters used in stripe-js, so our hope is to make the experience in using that JS library and this one very similar and intuitive.