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.

info

Make sure that the collection of the recurring payments are not initiated by both the PSP and FinDock. This is not only relevant when migrating to a new PSP, but also if you start using FinDock with your current 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.

info

By default FinDock does not create installments for newly created opportunities with a closed status. If you are migrating closed donations and you want installments (e.g. for reporting), you can enable the Installments for Closed Opportunities setting in the FinDock for NPSP source connector. When enabled, each created installment also gets one FinDock payment record for the full amount of the related opportunity.

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.

info

If you have existing payment references you want to maintain, store them in the cpm__Custom_Payment_Reference__c field as this always takes precedence over the reference generated by FinDock.

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 recievable 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 recievable 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 recievable 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

tip

To find out what data is required to collect payments through a specific payment processor and method, visit our data quality article and check out the data rules sheet for details.

Adyen migrations

Target Object	Target Field	PSP data	Comments
Mandate	adph__Token__c	Token	Specifc field on Mandate for Adyen tokens

Axerve migrations

Target Object	Target Field	PSP data	Comments
Mandate	gffd__Bank_Transaction_Id__c	Bank Transaction Id	Specific field for Axerve
Mandate	gffd__MOTO__c	MOTO (true /false)	Specific field for Axerve
Mandate	gffd__Eligible_for_Token_Refresh__c	Eligible for Token Refresh (true /false)	Specific field for Axerve
Payment Profile	gffd__Target_To_Refresh_Token__c	Target to Refresh Token	Specific field for Axerve

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.

Target Object	Target Field	PSP data	Comments
Mandate	cpm__Custom_Reference__c	Prefix + Mandate	If the entire Buckaroo mandate reference, including prefix, is migrated as one value, the value should be added to this field.
Mandate	cpm__Prefix__c	Prefix	If the prefix is not included in migrated mandate references, add the prefix to this field.

Checkout.com migrations

Target Object	Target Field	PSP data	Comments
Payment Profile	ccph__Fingerprint__c	Fingerprint	Specific field for Checkout.com

GoCardless migrations

Target Object	Target Field	PSP data	Comments
Contact	gcf__GoCardless_Customer_Id__c	GoCardless Customer Id	Needed only if you use the Manual Direct Debit component for existing customers
Mandate	cpm__Custom_Reference__c	GoCardless Mandate Id	Example: MD000EHA3S6AT7
Payment Profile	N/A	N/A	If you want to use custom notifications with GoCardless Pro, you need to create payment profiles with a Bank Name to get all the required data in Salesforce.

Mollie migrations

Target Object	Target Field	PSP data	Comments
Contact	moph__Mollie_Customer_Id__c	Mollie Customer Id	Specific field for Mollie
Mandate	cpm__Reference__c	Mollie Mandate id	Example: mdt_4tCvx2TJEz

PayPal migrations

Target Object	Target Field	PSP data	Comments
Mandate	cpm__Custom_Reference__c	Payer	Billing Agreement ID with PayPal, e.g. B-8G591046VR212925B. This overwrites the Mandate Id.

Redsys migrations

Target Object	Target Field	PSP data	Comments
Mandate	cpm__Reference__c	DS_MERCHANT_IDENTIFIER	e.g. 01903f9b923895767228066924f23b5892e88fdb

Saferpay migrations

Target Object	Target Field	PSP data	Comments
Mandate	sford__Is_Alias__c	Credit card reference	Is Alias must be true for migrated recurring credit card transactions to allow further collections
Mandate	cpm__Reference__c	(Card) Alias	The authorization token from Saferpay for a recurring payment (not set up through FinDock).

SmartDebit migrations

Target Object	Target Field	PSP data	Comments
Mandate	cpm__Custom_Reference__c	Payer	Bacs reference with SmartDebit, e.g. UCOSHX7. This overwrites the Mandate Id.

Stripe migrations

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

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

Target Object	Target Field	PSP data	Comments
Contact	wpayc__WorldPay_ShopperId__c	WorldPay Shopper Id	Specific field for Worldpay

Vipps

Target Object	Target Field	PSP data	Comments
Mandate	cpm__Custom_Reference__c	Agreement ID	E.g. agr_123456

FinDock as processor

Autogiro migrations

In addition to the general migration guidance, 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 right-filled with zeroes.

AvtaleGiro migrations

For mapping details, please see Migrating AvtaleGiro Agreements

Bacs migrations

Target Object	Target Field	Bacs data	Comments
Mandate	cpm__Date_Signed__c	Date	FinDock automatically populates this for new mandates

SEPA migrations

Target Object	Target Field	SEPA data	Comments
Mandate	cpm__Last_Used__c	Date	Needs to be populated for recurring, otherwise the next installment generated by FinDock will be first automatically.
Mandate	cpm__Prefix__c	Text	Only populate if you have a prefix, and no Custom Reference value is used on the record.
Payment Profile	(address fields)	N/A	If you have UK payers for SEPA, you need to populate the address fields: Street, Housename Or Number, Zipcode, City, and Country.

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.