Migrating from API v1 to API v2

With the FinDock July 2020 release, version 2 of the Payment API was introduced. This new version of the Payment API provides significant benefits in performance, ease-of-integration and functionality. Active development of new features on version 1 stopped with the July 2020 release.

To find out the high-level differences between API v1 and API v2, please visit our How does the Customer Payment API work?.

Detailed information about the API v1 and API v2 can be found in the API reference:

• API Reference v1
• API Reference v2

Breaking changes & new functionality

The API v2 introduces breaking changes to the following components:

• Renamed /Payment endpoint to /PaymentIntent to clarify that a POST request to this endpoint creates an Inbound Report record, from which an Installment or Recurring record is created through Guided Matching, instead of a Payment record in Salesforce. A GET request on /PaymentIntent returns a PaymentIntent (Inbound Report) object with related Installment and/or Recurring & Payment records. Payment records are created from callbacks from Payment Service Providers.
• Removed redundant /Processors endpoint: the same data is available through the /PaymentMethods endpoints.
• Changed body / definition of the /PaymentIntent request to FinDock:
  • The Payment object has been renamed to OneTime to better reflect the resulting data in Salesforce.
  • All parameters that are only used to persist data in Salesforce, without triggering logic in the API, have been moved to a SalesforceFields object.
    • This object takes any value for a Salesforce Standard or Custom Field is copied to the created record in Salesforce
    • The SalesforceFields object is available in the Root of the request, the sub-objects of Payer (Contact & Account) and the OneTime (Installment) & Recurring objects. SalesforceFields added to the Root of the request will be persistent on the Inbound Report object.
• Changed body / definition of the /PaymentIntent response from FinDock has changed:
  • A POST on /PaymentIntent no longer returns a Payment or Payer object, since the creation of Salesforce data like Contact. Installment and Opportunity are now handled asynchronously. Once the Installment has been created, you will receive a Webhook on “Installment status change” if you have added a WebhookURL variable.
    NOTE: Please make sure your callback url endpoint is added to the Salesforce Remote Site Settings, to allow traffic from Salesforce to the endpoint.
  • A GET on /PaymentIntent now returns an PaymentIntent object with Installment or Recurring object with related Payments similar to the Webhook on “Installment status change”
  • The body of the Webhook on “Installment status change” is unchanged.
• Split HTTP Status Codes: FinDock no longer always returns 200 on every API call. If an error occurs, FinDock will return a 4xx or 5xx status code with a more detailed ResponseCode and errorMessage.
  • This change has made the IsSuccess parameter redundant and it has thus been removed.
  • A 200 response now means the Inbound Report was created successfully in Salesforce and FinDock was able to return a response. However:
    • The complete payment flow may still fail upon redirection to the PSP, even though we try to do as much validation on the initial call to the API. Please handle these errors as well.
    • The further creation of data in Salesforce by Guided Matching from the Inbound Report may still fail on Validation Rules and Customization in Salesforce. Please make sure the proper checks and Guided Review processes are set up.
• Changed Error response:
  • API now returns an array of errors
  • Removed redundant ResponseCode parameter from Error object
• Renamed & Changed ParameterMap object:
  • Changed name to Parameters in both the GET /PaymentMethod response and the POST /PaymentIntent request where the optional and required parameters for all Payment Methods in a Salesforce org can be requested and used.
  • Added Enum parameter to the GET /PaymentMethod response in case only a limited amount of (picklist) values is allowed. Example: iDeal Issuer.
  • Removed AuthorizationRequired parameter.
  • Changed specific Parameters per PSP. Please see migration steps for specifics.
• Changed PaymentMethod object:
  • Removed PaymentProfile from definition. Fields that were part of the Payment Profile will be added to the Parameter object. This is implemented per Payment Service Provider.
  • Removed SourceConnector object and Added Settings object to store Salesforce data processing parameters like SourceConnector.
  • Added a new parameter ProcessingType which sets the SubType of Inbound Report. This SubType can be used to apply different Guided Matching rulesets to different API calls.
• Removed the ability to perform Unauthenticated (to Salesforce) calls with just a FinDock API Token. Please use Salesforce Authentication with your API calls. More information on Authentication can be found in the API Reference.
• Removed ability to pass a RecurringId in a /PaymentIntent request.
• Removed Account & Contact processing settings from API to Guided Matching: parameters with regards to deduplication, update/create of records & primary relation were removed from the API. These settings can now be configured in your Salesforce orgs Guided Matching setup.
• Introduced idempotency key parameter (optional): a unique identifier can be passed in the API to ensure the same transaction is not executed twice. This way you can safely retry an API call without creating duplicate payments.

Migration steps

On the Salesforce side

The API v2 creates the same Salesforce data as the API v1. The API v2 does however require a connection with the new WebHub to function:

1. The handling of notifications from Payment Service Providers will be done through the Notification Gateway which is part of the WebHub. For more information, see Configuring WebHub and Notification Gateway
2. Because the creation of Salesforce data is now handled asynchronously, when the data is created has however changed. Data creation is done based on Messages records that are queued and ordered by creation date to prevent conflicts. From these Messages records FinDock creates Inbound Report records that are handled through Guided Matching. No action is required to make this work, once the WebHub is set up.
3. Configure Guided Matching rules with regards to Account & Contact creation, update & deduplication if required for your business case. You can leave these as-is if the default handling suits your requirements. Please read our Processing and reconciling online payments article for more details.

On the API side

1. Change your base URLs from /services/apexrest/cpm/v1.0/ to /services/apexrest/cpm/v2/
2. If you were using the API Unauthenticated (with just a FinDock API token from the FinDock setup), please implement Authentication through Salesforce.
3. Change PaymentMethod response handling: incorporate the new Enum field in your logic if relevant to your use case.
4. Change all API calls referencing /Payment to /PaymentIntent
5. Change the /PaymentIntent request body:
   1. Add a Settings object to the root of the request body.
   2. Remove the SourceConnector object and add a parameter SourceConnector to the new Settings object in the root of the request.
   3. Rename Payment object to OneTime.
   4. Add all Contact and Account fields except for RecordTypeName to a SalesforceFields object under Contact and / or Account.
   5. Remove Relationship parameters:
      • AccountUpdate & ContactUpdate
      • PrimaryRelation
      • IgnoreAccount
   6. Rename the ParameterMap object in PaymentMethod to Parameters
   7. Add an idempotency key (optional)
   8. PSP specific changes to parameters: to be added when a PSP is refactored
6. Change PaymentIntent response handling:
   1. Remove references to the IsSuccess parameter and base your logic on the HTTP Status Code, where 200 = Success and 4xx and 5xx = Failed
   2. Change your handling of HTTP Status Codes to account for 4xx and 5xx responses on error scenarios.
   3. Handle errors as array
   4. Remove usage of ResponseCode parameter and replace with ErrorCode parameter.
   5. If you are using the returned InstallmentId from the POST /Payment response, please implement the Webhook on “Installment status change” to handle your business logic.

Testing

We advise you to at minimum test the following:

• Creating a new one-time & recurring payment
• Updating an existing one-time payment (Installment)
• Installment, Recurring & Payment records created in Salesforce through the API. The resulting data should be the same as when using API v1.
• Webhooks sent to your WebhookURL if applicable.