Processing and reconciling online payments

info

This article applies to environments configured with Enhanced Online Experience. If you are working on an existing Classic Online Experience with API v1 implementation, we strongly recommend you migrate to Enhanced Online Experience (preferably with API v2). Please visit our migration article.

caution

Enhanced Online Experience (with API v2) will be in Beta from the October '20 release onwards.

All API calls, or PaymentIntents, and online notifications to FinDock with regards to Payments are processed through Guided Matching. API calls directly create data in Salesforce and notifications are accepted through the WebHub.

How it works

As described in our How to use the Payment API article, every call or notification first creates a staging Message record from which FinDock creates an Inbound Report. This Inbound Report record is processed through Guided Matching.

FinDock comes with a set of Managed and Suggested rules out-of-the-box, but you can extend these with your own Guided Matching rules. Some of the ‘Managed’ rules can also be customized to suit your business needs.

The entire PaymentIntent or Notification is always stored in the Raw Message field on the Inbound Report, so any data provided by you or the Payment Service Provider can be parsed and used in Guided Matching rules, even if the data is not stored in an Inbound Report field by FinDock.

caution

If something goes wrong while processing an API call or Notification, FinDock will set the status of the Inbound Report to Failed. We strongly recommend you implement an (automated) business process to handle these failed processes. You could for instance set up Guided Review.

Configuring processing of API calls (PaymentIntent)

note

This section assumes some knowledge of how to create and edit Guided Matching rules. Especially if you wish to add additional Guided Matching rules to the managed rules, we strongly suggest you familiarize yourself with Guided Matching if you have not already done so.

The PaymentIntent is the initial API call that creates data in Salesforce. By default, from the Inbound Report, FinDock creates Account, Contact, Payment Profile, Mandate, Installment and Recurring records where applicable.

Guided Matching rules can be configured through in the Guided Matching setup:

  1. Go to FinDock Setup
  2. Guided Matching Setup
  3. Select Object = ‘Inbound Report’
  4. Select Report Type = ‘PaymentIntent’
  5. Select a Report Sub Type:
    • Default: if you wish to use one set of rules for all the incoming API calls to /PaymentIntent
    • You can also create your own Report Sub Types, to distinguish between the processing of API calls. By passing the name as this Report Sub Type as value in the ReportSubType parameter of the Settings object of your API call, you can indicate this specific call needs to be processed with these rules. For more information on this parameter, please visit our API Reference.

Guided Matching Setup PaymentIntent

Configuring deduplication

To maintain data integrity and quality, the Payment API supports deduplication using Salesforce deduplication features and FinDock data enrichment options.

Deduplication is focussed on the Account, Contact and Payment Profile records. Payment Profiles are deduplicated automatically by FinDock.

note

The deduplication processing rules need to be configured in Salesforce before the Payment API can apply deduplication and data enrichment. Confirm with your Salesforce administrator the correct set of rules for your business case.

In Guided Matching, deduplication is performed in two steps:

1. Find duplicates

Duplicates are found through the Find Account by duplicate rules and Find Contact by duplicate rules Guided Matching rules of the Find duplicates Guided Matching rule type. If you do not wish to deduplicate Account and/or Contact records you can remove these rules from the list.

Find duplicates

2. Create or update records

By default:

  • If no duplicates are found, a record is created through the Create Account if not found and Create Contact if not found rules of the Create record rule type, taking the values provided in the API message (PaymentIntent).
  • If a duplicate record is found, the record is updated through the Update Account if found and Update Contact if found rules of the Update record rule type, taking the values in the API message and overriding current values on the record if present.

You can adjust the default behavior by:

  • Removing and/or replacing the rules with your own rules
  • Opening the rules by clicking them and adjusting their Mapping under Rule Setup. You can choose to set the value of the updated record to be the value of the PaymentIntent message, a field on the Inbound Report (for instance using an Account you passed in your API message instead of taking the Account from the found Contact) or a hard-coded value. If you do not wish to override existing values on a duplicate record that was found in your environment, you can select Only if blank.

Update account

Configuring Installment & Payment Profile relationships

You can choose whether we relate the Installment or Recurring that is created to either Contact or Account for this Inbound Report (Report Sub Type) by editing the Handle Payment Intent Rule.

You can set the Primary Relation to Contact or Account. Both the Installment and the Payment Profile will be related to this record.

Handle Payment Intent

By default, Guided Matching has the following behaviour:

  • If the Inbound Report only has a Contact -> Installment & Payment Profile linked to Contact
  • If the Inbound Report only has an Account -> Installment & Payment Profile linked to Account
  • If the Inbound Report has both a Contact and an Account -> FinDock uses the Primary Relation setting to determine what to link to the Installment & Payment Profile. By default, this is Contact.
  • If the Inbound Report has no Contact nor an Account -> Guided Matching process fails.
caution

Once saved, removed or changed Suggested rules cannot automatically be restored to their original state, without reinstalling the package. They can only manually be restored by setting the rules to the same logic.

Configuring processing of Notifications

Notifications can be sent by Payment Service Providers to update the status of a payment in Salesforce. By default, from the Inbound Report, FinDock creates and updates Payment Profile, Mandate, Installment, Recurring and Payment records. Notifications can be configured per Payment Service Provider and per event. Events contain specific updates to your payment like charge.succeeded and payment.failed.

Guided Matching rules can be configured through in the Guided Matching setup:

  1. Go to FinDock Setup
  2. Click the Guided Matching Setup tile.
  3. Select Object = ‘Inbound Report’
  4. For the Report Type, select the Payment Extension you wish to update like PaymentHub-Stripe.
  5. For Report Sub Type choose the specific event you wish to configure.

Guided Matching Setup Notification

Currently, none of the Managed Guided Matching rules on the notification Inbound Reports can be configured through the Guided Matching Setup. You can, however, add your own custom rules.

tip

Out-of-the-box FinDock handles only the most important events from Payment Service Providers. However, Payment Service Providers send many more events. If you want to process these events, simply configure Guided Matching rules for them!