Skip to main content
Version: may-24-sandbox

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​

Online payment process

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

  1. The webpage (a front-end payment form) sends a PaymentIntent message to the FinDock Payment API.
  2. FinDock validates the payment intent and creates a payment with the Payment Service Provider (PSP).
  3. An Inbound Report record is created for the payment intent and processed through Guided Matching.
  4. FinDock sends a response with a RedirectURL back to the form.
  5. 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.
  6. The PSP notifies FinDock about the result of step 5.
  7. FinDock creates inbound reports from PSP notifications in Salesforce over the Salesforce API.

The inbound reports are 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, FinDock updates the data for the source objects as well.

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 support recurring, but Recurring section available.
  • Installment section with a OneTime or Recurring section.

For certain payment methods, steps 4-7 are not always required. Payment collection instead happens through file transfers with your bank. These files can be generated from the data created through the Payment 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