Migrating payment data to FinDock

As part of a new FinDock implementation, you probably need to migrate historical payment data to FinDock. For example, you may need to preserve the data for auditing or want to continue collecting payments using existing payer details and authorizations.

This article outlines the required data importing order and explains key aspects of FinDock data objects to help you map existing data to FinDock objects and fields. Your mapping also needs to cover Salesforce objects that are central to FinDock, such as Contact, Account, Campaign, and Opportunity. However, this article only covers FinDock objects.

Before you start

There are a few important items to take care of before you start migrating data to FinDock.

Scope the data for migration

Do you need historical data for reporting purposes, or do you just need historical data required for collecting future payments? The latter is assumed, but the former is a very important aspect of the migration. Historical data that is only for the purpose of generating reports significantly expands what you need to migrate.

Install FinDock

This may seem obvious, but it is a critical step. You need to install FinDock and all relevant extension packages before migrating. This is required to get all the FinDock objects and fields, including new fields on standard Salesforce objects, in your org so that you have all the necessary migration target data points.

Use active or passive migration

If you wish the system to perform actions based on your data load (such as create new mandates), you need to complete the Salesforce and FinDock configuration. An active approach is only reasonable if you have a limited amount of data to migrate. FinDock evaluates every record as you insert it and takes action as needed to create or update related data.

For high volume imports (over 10,000 rows), we recommend disabling as much automation as possible to speed up the data import process. If FinDock is already configured, you can disable source connector(s) and payment extensions to block some automated actions. This means, however, your data import must provide all required information up front. Only with a complete data set can FinDock take the correct actions once payment processing starts.

Ensure UTF-8 encoding

All imported data must use UTF-8 encoding. FinDock does not change encoding on the fly, so any data not properly encoded must be changed before importing.

Study data models

Ensure you have a thorough understanding of FinDock and relevant Salesforce objects and entity relationships. Some information is provided in this article, but you should take time to study other sources as well, including this FinDock data model overview. If you are using the Nonprofit Success Pack (NPSP), the FinDock for NPSP data model is different as NPSP is considered the “source” of payment data in such a setup.

Determine source of recurring payments

If you want to collect recurring payments with FinDock, you need to know from where to get the recurring payment details. In other words, what system knows when to collect, how much, and from whom to collect? The three most typical scenarios are:

• Industry solution
  If an industry solution, such as Salesforce Nonprofit Cloud, is already in use for which FinDock offers a source connector, no migration is required. You can configure the source connector to use the industry-specific objects for recurring payments.
• Existing PSP account:
  If you use a PSP like Stripe or Mollie to collect recurring payments (e.g. subscriptions), you need to migrate the data from the PSP to FinDock Recurring Payment (or source-specific object) records in Salesforce. Once migrated, recurring payments should only be initiated through FinDock.
• 3rd party system:
  If another system outside Salesforce, such as a different CRM or an external finance system, is the source of recurring payment details, you need to migrate the data from that system to FinDock Recurring Payment (or NPSP Recurring Donation) records in Salesforce. Once migrated, recurring payments should only be initiated through FinDock.

Data import requirements

FinDock requires specific data that depends on payment method and processor. We have captured these requirements in the FinDock data quality tools. In addition to specific requirements, there are general high-level requirements that you can use when mapping data for import, as outlined in the following sections.

Changing Payment Service Provider

If you change providers, you need to contact the new payment processor to migrate your historical data to their system before loading data into Salesforce and FinDock. The process of migrating data from one PSP to another differs per provider.

It is also important to keep in mind that PSPs may offer different options for recurring payments. Many allow you to control the collection of recurring payments via their system and also support initiating the collection via another system such as FinDock.

With FinDock the collection of the recurring payments should always be controlled via FinDock. In other words, you define when the collection takes place using FinDock tools and not the PSP.

Migrating recurring payments

In a FinDock Standalone setup where FinDock is the source of payment data, the Recurring Payment object is used to manage the collection of recurring payments. If some other source is used, such as Salesforce Fundraising with Nonprofit Cloud, the source has its own object(s) for controlling recurring payments.

To collect recurring payments, your data import needs to include data for at least the following:

• Contact and/or Account
• Payment Profile
• Recurring Payment (or source-specific objects)
• Mandate

Migrating one-time payments

One-time payments are handled with the Installment object in FinDock, If NPSP is used, the Opportunity object captures the one-time payment for which FinDock automatically creates (and syncs) a corresponding Installment record.

Collecting a one-time payment with FinDock requires at least the following objects:

• Contact and/or Account
• Payment Profile
• Installment or Opportunity
• Mandate (if the payment is not yet collected or you want to maintain history data)

Order of data import

FinDock relies on data relationships to orchestrate payments. To correctly build these relationships during migration, a specific data loading order must be followed. Data for each object must be loaded in the order below:

1. Contact and Account
2. Payment Profile
3. Mandate Schedule (optional)
4. Mandate
5. Recurring Payment (or source-specific objects)
6. Other source records (e.g. Gift Transactions in Nonprofit Cloud)
7. Payment Schedule (optional)
8. Installment
9. Payment (NPSP Payment optional)
10. Inbound Report (optional)
11. Transaction Sets (optional)
12. Transactions (optional)

The following FinDock objects are for operational purposes only and not available for data migration:

• Audit Trail
• Log
• ProcessingHub File

Object-specific considerations

Every migration is unique and requires thoughtful planning, as well as a complete mapping of existing data points to Salesforce and FinDock data. To help you with this mapping, we summarize here special object-specific considerations.

Payment profile data

Payment profiles contain information required to process payments with a certain payment method, such as a bank account for direct debit or (obfuscated) credit card details. One contact or account and have multiple payment profiles.

When importing payment profiles, you need to deduplicate them on the contact or account level to ensure a particular IBAN, bank account or credit card is created only once for the particular contact or account. Note, however, that the same bank account, for example, can appear in multiple payment profiles if the payment profiles are connected to different contacts or accounts.

If you plan on using FinDock for MOTO payments, please also follow our recommendations for re-using cards.

Mandate and payment schedule data

Importing of historical data as mandate schedules and payment schedules is not required, but can be done for completeness and reporting purposes. When importing, make sure to set the status field cpm__Status__c to Verified. This ensures the migrated schedules are not run again by FinDock.

Mandate data

Careful migration of mandates is of the utmost importance. Incorrect mandate data can have a huge impact on collection runs because the payment processor might not be able to identify the mandate.

When importing existing mandates, make sure to use the Custom Reference field cpm__Custom_Reference__c for the historical mandate identification. This field always takes precedence over the reference generated by FinDock.

If the mandate needs to be registered before it can be used (such as with Bacs Direct Debit), set the Status field (cpm__Status__c) to Success if the mandate is already registered. If registration has not yet been done, set the Status to Pending Registration. The Status field can be left blank if registration is not required (such as with SEPA Direct Debit).

Other important fields to note:

• Last Used (cpm__Last_Used__c): make sure to also import the date the mandate was last used for a payment collection into this field. This ensures correct usage of sequence types where applicable.
• Active (cpm__Active__c): If the mandate should never be used again, set the checkbox to false. Take extra care when importing historical mandates that were only for one-time payments that are already collected. They must be set to false.
• Target (cpm__Target__c): If the same mandate reference is applicable for multiple targets, you need to create multiple mandate records to reflect this. The correct value for Target can be ascertained by translating the bank account for which the mandate is valid to the target name as defined in FinDock.
• Payment Processor (cpm__Payment_Processor__c): Unlike on other objects, for mandates, this is a text field.

Recurring payment data

Recurring payment records are only required if you’re not using a source like Salesforce Fundraising with Nonprofit Cloud. If you are going to use recurring payments, you need to ensure the Last Collection Date field (cpm__ls_coll_date__c) is populated with the date of the last payment of the recurring payment. FinDock uses this date to determine when to generate a new installment for the next collection.

After migration, we strongly recommend checking for active recurring payments that have a next collection date before today. Any results here might indicate a problem with the source data.

You can set a specific payment reference in the Custom Payment Reference field. This reference is used for all installments created from the recurring record and overridden the Final Payment Reference field. Be extra careful if you use the custom reference option. For some scenarios (e.g. FinDock Bacs Manual and SmartDebit), this can break reconciliation.

Source-specific data

When importing to source objects like NPSP Opportunities and Recurring Donations, or Nonprofit Cloud Fundraising Gift Transactions, we recommend deactivating the source connector in FinDock for migration. This prevents FinDock from automatically creating installments for the migrated source records.

Take care to populate the control fields (Payment Method, Processor, Target, Payment Profile and Mandate) with the correct values. Also make sure to use original API values for picklists and not translations.

Installment data

Installments are central to FinDock payment processing and as such use numerous lookups. Make sure you correctly handle the references to other objects via lookups when migrating installment data. This is especially important if FinDock Standalone is not used, but rather some other package, like Salesforce NPSP, is used as the source of payment data. Reporting results might be incorrect if the link between installment and source record is not properly defined.

Take care to populate the control fields (Payment Method, Processor, Target, Payment Profile and mandate) with the correct values. Also make sure to use API values for picklists and not the translated values.

The Status field cpm__Status__c only supports the predefined values. Importing values that are not standard FinDock values might cause inconsistent and unexpected behavior.

Gift Aid data

If you are migrating Gift Aid data, you need to determine which donations are eligible for Gift Aid and carefully map data to ensure only those existing donations (and future donations) are included in new Gift Aid claims.

First you should migrate the data for Gift Aid Declarations. These records are checked by FinDock when determining if eligible donations can be claimed. Only eligible donations with a valid Gift Aid declaration are processed and sent to HMRC.

For donations with claimed Gift Aid:

• Create a Closed Won opportunity.
• Create a receivable installment for the donated amount with Gift Aid Claimed marked true.
• Create a Gift Aid installment for the already claimed Gift Aid amount.

For donations with pending Gift Aid claims:

• Create a Closed Won opportunity.
• Create a receivable installment for the donated amount with Eligible for Gift Aid marked true.

For donations not eligible for Gift Aid:

• Create a Closed Won opportunity.
• Create a receivable installment for the donated amount with Exclude from Gift Aid marked true.

Payment data

There is more than one “Payment” object in Salesforce. There is a standard Payment object, an NPSP Payment object (npe01__OppPayment__c) and the FinDock Payment object (cpm__Payment__c). Make sure you migrate payment data to the intended object.

FinDock payments must be linked to their respective installments. The Amount Open field (cpm__Amount_Open__c) on the installment is calculated based on the related payment records.

Control fields (Payment Method, Processor, Target, Payment Profile and mandate) on payments are important for reporting purposes. However, they have no direct impact on the operation of FinDock. Also make sure to use API values for picklists and not the translated values.

Inbound Report and Transaction data

Inbound reports and transactions are not part of data migrations. If there is comparable historical data, they can be included for reporting purposes. Take care to set the status of the transactions to a Matched or Manually Matched status, and make sure the payments created from those bank transactions are correctly linked to their relevant transaction records. If done incorrectly, this might have a severe impact on reporting and financial exports to bookkeeping software.

Processor-specific considerations

Adyen migrations

Axerve migrations

Buckaroo

For SEPA Direct Debit migrations, special attention is needed in the area of mandate reference handling. There are two ways to manage the Buckaroo prefix.

Checkout.com migrations

GoCardless migrations

Mollie migrations

PayPal migrations

Redsys migrations

Saferpay migrations

Access PaySuite (SmartDebit) migrations

Stripe migrations

Further Stripe migration requirements

If you are going to use MOTO payments, make sure you migrate the data needed for credit card re-use.

If you are moving SEPA Direct Debit payments to FinDock, you need to get the SEPA mandate Stripe Payment Method Id into FinDock. If the field is not included in reports, it can be queried via the Stripe API.

Worldpay

Vipps

FinDock as processor

Autogiro migrations

Before you start migrating existing Autogiro recurring payments to FinDock, please first assess the types of payment collection in use. Autogiro supports two: automatic recurring collection based on a single payment order to initiate collection, and recurring collection based on recurring payment collection instructions. FinDock only supports the latter.

If you have any automatic collection in use, these orders need to be cancelled as part of the FinDock migration. We recommend proceeding in batches, cancelling a small set of orders, migrating those, and restarting collection through FinDock. Once your process is confirmed to work, you should gradually move remaining automated orders to FinDock, for instance, in batches of increasing size.

When it comes to migrating Autogiro data, in addition to the general migration guidance noted above, special handling of custom mandate Id values may be needed. Payer numbers (mandate Ids) in FinDock must be filled with leading zeros to match the expected 16-digit length. If, for example, the payer’s Bankgiro number is migrated and used for the mandate Id, the value needs to be filled with leading zeroes.

Also, note that you need to use the BBAN record type and page layout for Payment Profile for Autogiro payer bank details. Start by selecting Sweden from the country picklist. This will show you which fields should be populated for Swedish banks accounts.

AvtaleGiro migrations

For mapping details, please see Migrating AvtaleGiro Agreements

Bacs migrations

SEPA migrations

Testing and verifying migration

You should fully test your migration script and data preparation in a sandbox org before migrating data to a production org. Use the sandbox setup to confirm:

• Historical data use UTF-8 encoding
• Data mapping is working as expected
• Data for closed payment collections is complete
• Data required for continued payment collections is complete

Once you have migrated data to your production org, we recommend running reports on the historical data period to confirm the migrated data meets the needs of your finance department.

To verify your data is correct:

1. Create a payment schedule with the payment processor and method you have migrated.
2. Run the Generate step to create and select installments.
3. Run the Data Quality validation.
4. If the validation results in errors, check if they are historical or migration issues.
5. Fix errors and re-do steps 1-3.