Stripe recurring credit card migration
This guide walks you through the process of migrating Stripe recurring credit card payment data to FinDock.
Before you begin
You need to have FinDock installed and configured with the Stripe package. Make sure all configuration changes have been deployed to ensure control field picklists are up to date.
For an overview of the basic setup, you can check out our quick start.
Migration overview
The migration process is as follows:
- Check state of recurring subscriptions in Stripe.
- Cancel subscriptions (recurring credit card payments) in Stripe.
- Export subscription data from Stripe.
- Import subscription data to Salesforce.
- Set up payment collection in FinDock.
- Test migrated data.
Step 1 - Check subscriptions
Before starting the migration, you check the state of your current Stripe recurring payments. They could be in one of three states. We'll walk you through what to do based on the state.
Subscriptions managed by third party
Subscriptions are managed by a third party CRM or other system that sends the request for payment to Stripe at certain intervals, usually monthly. The payment data itself is stored in Stripe.
Subscriptions managed by Stripe
Subscriptions are managed by Stripe and appear in the subscriptions section in your Stripe Dashboard.
Subscriptions managed by another PSP
You intend to use Stripe, but you haven’t yet migrated subscriptions from your other payment service provider.
Step 2 - Cancel subscriptions
The cancellation process differs depending on who manages the subscriptions.
Cancel subscriptions managed by third party
Contact the third party and agree a date to end subscriptions and disconnect them from Stripe. Stripe does not support multiple connections over the API.
Cancel subscriptions managed by Stripe
From your Stripe dashboard, cancel your subscriptions for a certain date and make sure this end date lines up with the date you intend to start collecting payments through FinDock.
It’s also possible to cancel subscriptions in bulk using the API more info can be found in this Stripe article.
Cancel subscriptions managed by another PSP
Reach out to your current credit card processor and Stripe about the process of importing and cancelling these subscriptions. Stripe can help with the process of migrating to Stripe.
Step 3 - Export data from Stripe
Once you’ve established a plan for canceling your subscriptions and agreed a date when FinDock processes can take over, you are ready to export the data you need.
For example, you may have decided that in 10 days time your third party and/or Stripe stops managing your subscriptions. So, you now need to get the necessary data from Stripe and migrate that data into Salesforce.
You can export the data as a JSON, or you can use the built-in Export Function from Stripe. The best place to export and ensure you get all the data you need is from the Customers section.
Once you’ve selected your time period, click the Custom button shown in the screenshot below.
Then select the columns you need to export. The most important are Customer ID, Card ID and Card Fingerprint. You might also find others useful, such as Customer Email, to help you filter the exported data.
You export your recurring payments so you have a list of the customer IDs that you know are your Stripe subscriptions. Then you can use these IDs to sort your Customer export and filter out customers who only made one-off payments or other payments that don't need migrating. You’ll also find this info useful when updating the Day of the Month field on recurring payments in Salesforce. If your subscription is managed by a third party, ask how to filter out data so you only get your currently active recurring payment customers.
Step 4 - Import data to Salesforce
To collect recurring payments, your data import needs to include values for at least the following objects. The import must also occur in this order:
- Contact and/or Account
- Payment Profile
- Mandate
- Recurring Payment (RP) or Recurring Donation (RD)
Below is a table of the key fields and data mapping.
| Target Object | Target Field | PSP data | Comments |
|---|---|---|---|
| Contact | phstr__Stripe_Customer_Id__c | Stripe Customer Id | Specific field for Stripe, e.g. cus_1234absced |
| Mandate | cpm__Reference__c | Stripe Customer Id | Specific field for Stripe, e.g. cus_1234absced |
| Mandate | phstr__Payment_Method_Id__c | Stripe Payment Method Id | Specific field for Stripe, e.g. pm_123sdf3dsf3 or card_123w213sf |
| Payment Profile | phstr__Fingerprint__c | Fingerprint | Specific field for Stripe |
| Recurring Donation (RD) or Payment (RP) | npsp4hub__Payment_Method__c (RD) cpm__Payment_Method__c (RP) | Credit Card | Picklist field |
| Recurring Donation (RD) or Payment (RP) | npsp4hub__Payment_Processor__c (RD) cpm__Payment_Processor__c (RP) | PaymentHub-Stripe | Picklist field |
| Recurring Donation (RD) or Payment (RP) | npsp4hub__Target__c (RD) cpm__Target__c (RP) | Stripe target name | This value will be deployed to Picklist after you add your Stripe target and name it |
| Recurring Donation (RD) or Payment (RP) | npsp4hub__Payment_Profile__c (RD) cpm__Payment_Profile__c (RP) | Mandate ID | You’ll create this during the data import |
| Recurring Donation (RD) or Payment (RP) | npsp4hub__Mandate__c (RD) cpm__Mandate__c (RP) | Mandate ID | You’ll create this during the data import |
We created an example Stripe export and migration template containing so you can see where the data should reside. The different objects are separated by tabs you can click at the bottom.
The template is designed for a Salesforce NPSP migration. For non-NPSP migrations, you can simply change the Recurring Donation object to Recurring Payment. You also need to ensure you map the above fields to FinDock installments (this is handled automatically with the FinDock NPSP connector)
Step 5 - Set up payment collection
Once your data is migrated you need to set up recurring payment schedules. These automatically create payment schedules at an interval you choose. For recurring credit card payments, you probably need to create a schedule that runs daily, since it’s likely collections occur on multiple different days in the month.
Once created, you can auto-collect payments if you want to fully automate payment schedule runs.
Step 6 - Test migrated payments
You should try running a test payment schedule with auto run off so you can just generate and remove any installments you don’t want before processing.
You can create a payment schedule with status Scheduled. Procced on the schedule with starting the Generate step, and then remove all the installments you don’t want to process (just edit the payment schedule lookup field on the installment to unlink them).
Then, to test your data, start the process step and check the Stripe Dashboard for new payments or check for errors on the installment(s) linked to the Payment Schedule record.