Skip to main content
Version: may-22-production

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:

  • Salesforce NPSP:
    If NPSP is already in use, no migration is required. You can configure NPSP for FinDock to use recurring donations.
  • Existing PSP account:
    If you use a PSP like Stripe or Mollie to collect recurring payments (aka subscriptions), you need to migrate the data from the PSP to FinDock Recurring Payment (or NPSP Recurring Donation) 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’s tools and not the PSP.

important

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. When NPSP is used, the object controlling recurring payments is the NPSP Recurring Donation object.

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 Recurring Donation
  • 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 Recurring Donation (NPSP) or Agreement (Converse)
  6. Other source records (e.g. Opportunities in NPSP)
  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.

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 NPSP. 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.

Recurring Donation (NPSP) or Agreement (Converse) data​

When importing source objects like NPSP Recurring Donations or Converse Agreements, we strongly recommend deactivating the source connector in the FinDock. 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 NSPS, 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.

important

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.

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 ObjectTarget FieldPSP dataComments
Mandateadph__Token__cTokenSpecifc field on Mandate for Adyen tokens

Axerve migrations​

Target ObjectTarget FieldPSP dataComments
Mandategffd__Bank_Transaction_Id__cBank Transaction IdSpecific field for Axerve
Mandategffd__MOTO__cMOTO (true /false)Specific field for Axerve
Mandategffd__Eligible_for_Token_Refresh__cEligible for Token Refresh (true /false)Specific field for Axerve
Payment Profilegffd__Target_To_Refresh_Token__cTarget to Refresh TokenSpecific field for Axerve

Checkout.com migrations​

Target ObjectTarget FieldPSP dataComments
Payment Profileccph__Fingerprint__cFingerprintSpecific field for Checkout.com

GoCardless migrations​

Target ObjectTarget FieldPSP dataComments
Contactgcf__GoCardless_Customer_Id__cGoCardless Customer IdNeeded only if you use the Manual Direct Debit component for existing customers
Mandatecpm__Reference__cGoCardless Mandate IdExample: MD000EHA3S6AT7
Payment ProfileN/AN/AIf 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 ObjectTarget FieldPSP dataComments
Contactmoph__Mollie_Customer_Id__cMollie Customer IdSpecific field for Mollie
Mandatecpm__Reference__cMollie Mandate idExample: mdt_4tCvx2TJEz

PayPal migrations​

Target ObjectTarget FieldPSP dataComments
Mandatepp4ph__PayPal_Billing_Agreement_Id__cPayPal Billing Agreement IdSpecific field for PayPal
Payment Profilepp4ph__Payer_Id__cPayer IdSpecific field for PayPal
Payment Profilepp4ph__Payer_Name__cPayer NameSpecific field for PayPal
Payment Profilepp4ph__PayPal_Email_Address__cPayPal Email AddressSpecific field for PayPal

SIX Saferpay migrations​

Target ObjectTarget FieldPSP dataComments
Mandatesford__Is_Alias__cCredit card referenceIs Alias must be true for recurring credit card transactions migrated to SIX Saferpay to allow further collections

SmarDebit migrations​

Target ObjectTarget FieldPSP dataComments
Mandatecpm__Reference__cPayerBacs reference, e.g. UCOSHX7

Stripe migrations​

Target ObjectTarget FieldPSP dataComments
Contactphstr__Stripe_Customer_Id__cStripe Customer IdSpecific field for Stripe, e.g. cus_1234absced
Mandatephstr__Payment_Method_Id__cStripe Payment Method IdSpecific field for Stripe, e.g. pm_123sdf3dsf3 or card_123w213sf
Payment Profilephstr__Fingerprint__cFingerprintSpecific field for Stripe

Worldpay​

Target ObjectTarget FieldPSP dataComments
Contactwpayc__WorldPay_ShopperId__cWorldPay Shopper IdSpecific field for Worldpay

FinDock as processor​

SEPA migrations​

Target ObjectTarget FieldSEPA dataComments
Mandatecpm__Last_Used__cDateNeeds to be populated for recurring, otherwise the next installment generated by FinDock will be first automatically.
Mandatecpm__Prefix__cTextOnly populate if you have a prefix, and no Custom Reference value is used on the record.
Payment Profile(address fields)N/AIf you have UK payers for SEPA, you need to populate the address fields: Street, Housename Or Number, Zipcode, City, and Country.

Bacs migrations​

Target ObjectTarget FieldBacs dataComments
Mandatecpm__Date_Signed__cDateFindock automatically populates this for new mandates

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.