Skip to main content

How the Payment API works

The Payment API is a REST API used to initiate online payment transactions and/or submit recurring payments to the FinDock app in Salesforce. The API abstracts both Salesforce and FinDock configuration details for specific payment processors and methods, instead providing several informational resources to retrieve environment-specific parameters of a particular implementation.

From payer to collection#

Enhanced Online Payment Experience

Once the payer has entered the data in the online form:

  1. The form sends a payment request or PaymentIntent to the FinDock Payment API.
  2. FinDock validates the PaymentIntent and creates a payment with the Payment Service Provider (PSP)*.
  3. FinDock sends a response with a RedirectURL to the a PSP payment page back to the form.** FinDock also creates a messages record in Salesforce through the WebHub with an authorized user to store the request and handle data creation. In parallel (asynchronously) FinDock creates Salesforce data:
    • An Inbound Report record is created from the message (step 2).
    • The inbound report is processed through Guided Matching to create data:
      • Create or update Contact and/or Account records.
      • Create Installment and/or Recurring records, update Installment records.
  4. The form redirects the payer to the PSP payment page based on the RedirectURL:
    • Payer either completes or cancels the payment on the PSP page.
    • PSP page redirects payer to success or failure page provided in the initial payment request.
  5. The PSP notifies the FinDock Notification Gateway (WebHub) of the result of step 4.
  6. FinDock WebHub creates a Message record in Salesforce over the Salesforce API, from which an Inbound Report record is created.
  7. The inbound report is processed through Guided Matching to create data and reconciled against the data created previously:
    • Creates a Payment record in Salesforce related to the Installment record created in step 3.
    • Reduces the amount on the installment by the amount of the payment.
    • Updates the status of the installment (e.g. to 'Paid').

If the Payment was not completed the status of the Installment is updated to Failed. If you use a source connector, like for NPSP, FinDock updates the data in this package.

tip

The out-of-the-box Guided Matching rule set used to process the API call can be configured and extended. For more information, please read our Processing and Reconciling online payments article.

(*) The following validations are performed on the request sent to the Payment API:

  • Contains negative amounts
  • Contains not existing record types
  • Contains not existing targets
  • Recurring End Date < Recurring Start Date
  • OneTime required fields (Amount)
  • Recurring required fields (Amount, Frequency, StartDate)
  • Installment required fields (ID or GUID)
  • Does not have OneTime, Recurring or Installment section
  • Required parameter not provided
  • Parameter value not in enum
  • Payment method requires initial payment for recurring: Recurring and no OneTime sections available
  • Payment method does not require initial payment for recurring: Recurring and OneTime section available
  • Payment method does not supports recurring, but Recurring section available.
  • Installment section with a OneTime or Recurring section.

(**) For certain payment methods like direct debit and Acceptgiro, steps 4-7 are not always required since the payment will be handled by sending files to and receiving files from your bank. These files can be generated from the data created through the API with Payment Schedules.

Next steps#

Get started with the Payment API

Create one-off and recurring payments through the API

Check the API Reference Guide