Getting started with the Payment API v2

The FinDock Payment API allows external systems to initiate personalized customer journeys for one-time or recurring payments to FinDock. The most common Payment API use cases include:

• Donation forms
• Invoice payment forms
• Webshop checkout forms

These and other use cases can be implemented with any remote platform that supports outbound REST calls, such as website and social media platforms, mobile apps, and so forth.

How it works

The API is set up so that a developer can use a simple sequence of actions to complete payment transactions.

1. Get details via the Payment API of the Salesforce configuration about available payment methods and source app.
2. Request initial details from the customer or donor.
3. Put in a payment request with the data you have collected through the Payment API.
4. Based on the API response, perform additional actions, such as redirecting or additional data collection
5. Provide final status confirmation of the transaction to the payer.

For details and visuals, see How the payment API works.

Before you start

Before you can start to develop an integration with the Payment API, you need:

1. A licensed installation and configured FinDock app in a Salesforce org with payment methods you want to use set up properly. Ask your Salesforce admin or visit Installing FinDock packages.
2. Authenticated access through a Connected App using Oauth2 authentication with at least the Manage user data via APIs (api) scope. The permissions for the user should include the FinDock Integration User permission set group.
3. A working connection with the WebHub in your Salesforce org.
4. OPTIONAL: Find out about (and perform) specific Salesforce configuration like deduplication rules and custom fields. For more information about deduplication and the FinDock API, please see the Configuring deduplication section in the Processing and reconciling online payments article.
5. Check out the latest version of our API
6. If you want to build a generic API for several organizations, get in touch so we can support you better.

Endpoints

All endpoints are based on the specific Salesforce org you are going to use with the FinDock Payment API. The endpoints consist of three parts:

• The Salesforce domain URL. You can find this under Salesforce Setup > Company Settings > My Domain.
• The Payment API base URL: /services/apexrest/cpm/v2/
• The Payment API endpoint: e.g. /PaymentIntent

For example, if your domain is https://findock-dev-ed.my.salesforce.com, you would send your payment requests to: https://findock-dev- ed.my.salesforce.com/services/apexrest/cpm/v2/PaymentIntent For a full list of endpoints, please visit our API reference guide.

Developing a typical Payment API flow

Step 1: Determine payment methods and processors.

Before you can do anything with the API, you need to find out which payment methods are available, and which payment processors are used for those methods. FinDock provides several informational endpoints to find out what configuration has been done in a specific Salesforce environment. If you perform a GET on /PaymentMethods with a bearer token similar to Bearer 00D3X000002nlLm!AQ0AQP9WRbZoTA5kQNZEmLql6EUrJwl9nSUZsF_ih83YlAmhOf..LIuXzx_UE3httOZ3IahVRTnnzHP_gtl3fK5HRQCtMMBy in the Authorization header, you get the following response:

{
    "PaymentMethods": [
        {
            "Processors": [
                {
                    "SupportsRecurring": true,
                    "RecurringRequiresInitialPayment": false,
                    "Parameters": [
                        {
                            "Required": false,
                            "Name": "locale",
                            "Description": "Expected input: language tags as outlined on https://www.oracle.com/java/technologies/javase/jdk13locales.html. Examples: nl-NL, en-US.",
                            "DataType": "String"
                        }
                    ],
                    "Name": "PaymentHub-Stripe",
                    "IsDefault": true
                }
            ],
            "Name": "CreditCard"
        },
        {
            "Processors": [
                {
                    "Targets": [
                        {
                            "publicTarget": "PaymentHub-SEPA",
                            "Name": "SEPA-target"
                        }
                    ],
                    "SupportsRecurring": true,
                    "RecurringRequiresInitialPayment": false,
                    "Parameters": [
                        {
                            "Required": true,
                            "Name": "iban",
                            "Description": "The IBAN of the payer",
                            "DataType": "String"
                        },
                        {
                            "Required": true,
                            "Name": "holderName",
                            "Description": "The holder name of the payer",
                            "DataType": "String"
                        },
                        {
                            "Required": false,
                            "Name": "bic",
                            "Description": "Bank identification code of the payer's bank",
                            "DataType": "String"
                        }
                    ],
                    "Name": "PaymentHub-SEPA",
                    "IsDefault": true
                }
            ],
            "Name": "Direct Debit"
        }
    ]
}

The response tells you this Salesforce org supports credit card payments through Stripe and direct debit payments through the FinDock SEPA package. If any ‘Parameters’ are returned, these need to be (if Required = True) provided in the /PaymentIntent request message as ‘Parameters’ in the PaymentMethod object.

Step 2: Determine source.

The “source” in the FinDock context is where payment data resides. This can be either FinDock (standalone configuration) or another Salesforce app like Nonprofit Success Pack. In the latter case, a source connector is configured to merge data to the source app and create data in Salesforce. Through the API, find out what source connector has been configured in the specific Salesforce org you are accessing. If you perform a GET on /SourceConnectors with a bearer token in the authorization header, you get the following response:

{
    "SourceConnectors": [
        {
            "PrettyName": "PaymentHub for NPSP",
            "Name": "PaymentHub-for-NPSP",
            "IsDefault": false
        },
        {
            "PrettyName": "GiftAid Source Package",
            "Name": "GiftAid-Source",
            "IsDefault": false
        },
        {
            "PrettyName": "PaymentHub",
            "Name": "PaymentHub",
            "IsDefault": true
        }
    ]
}

This Salesforce org supports creating data with FinDock standalone (PaymentHub) and syncing with the Salesforce Nonprofit SuccessPackage (NPSP) and creating Gift Aid declarations for the UK market.

Step 3: Create the submission form.

There are two ways to build up your submission form for the actual payment or donation: hard-coded or dynamic.

Hard-coded: Get payment methods, processor and source for the specific Salesforce org ahead of time and hard-code them into your payment form.

• Pro: fast implementation
• Cons:
  • Details required to perform a payment may change.
  • Configuration (e.g. available payment methods) in the Salesforce org may change
  • No personalization of the payment journey based on Salesforce data

If you decide to hard-code this configuration in your API call, make sure to stay up-to-date with releases of both FinDock and the PSP you are using and apply changes accordingly. You could also regularly poll the API for changes.

Dynamic: For each payment or donation perform the /PaymentMethods and /SourceConnectors call in step one, and then build the form based on the returned data. With this approach, you don’t need to refactor your donation form if anything changes on the Salesforce/FinDock side. You can apply business logic based on real-time data from the Salesforce org.

Step 4: Make the payment.

To make a payment, perform a POST to /PaymentIntent with at least a Payer, Payment and Payment Method in the request body and a Bearer token in the Authorization Header. We will leave the SourceConnector variable out, which will prompt FinDock to take the default source connector.

{
"SuccessURL": "https://www.example.com/success",
"FailureURL": "https://www.example.com/error",
 "Payer": {
   "Contact": {
     "SalesforceFields": {
       "FirstName": "Donald",
       "LastName": "Johnson"
     }
   }
 },
 "OneTime": {
   "Amount": "36"
 },
 "PaymentMethod": {
   "Name": "CreditCard",
   "Processor": "PaymentHub-Stripe"
   }
}

FinDock creates the required Installment and Contact records in Salesforce based on the request message. The Salesforce IDs of these records are returned in the response:

   {
    "Settings": {
        "SourceConnector": "PaymentHub",
        "ProcessingType": "Default"
    },
    "RedirectURL": "https://redirect.test.findock.com/3xnllmuai2/PaymentHub-Stripe/checkout?publicKey=pk_test_eGC6TxzQ60CdjpAkt2RG3CwZ008WiiOn12&sessionId=cs_test_tH90HM3vWqWOJQOShTCpstJmTDkB2MkTMzhZEkBgl9Cd2XKRY5KF4RTZ",
    "PaymentMethod": {
        "Processor": "PaymentHub-Stripe",
        "Name": "CreditCard"
    },
    "Id": "pi_or20pvm7fv9zow3e2"
}

Step 5: Redirect for additional details.

If additional information (like credit card details) are required, use the RedirectURL from the response message to redirect the customer/donor to the payment form provided by the payment processor, in this case Stripe. Once the transaction is completed, the customer/donor is redirected to a final SuccessURL specified in the initial request.

Step 6: Processor updates FinDock.

After the transaction is completed successfully, the payment processor updates the status of the transaction with FinDock. FinDock updates the required data in Salesforce by creating a payment under the previously created installment record.

Congratulations! You have now performed your first end-to-end payment with FinDock!

Next steps

Perform a single or recurring payment through the API based on your business requirements. For further information, see How to use the Payment API v2.

Check out the Integration checklist for additional tips on how to get the maximum value from our API.