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.
- Get details via the Payment API of the Salesforce configuration about available payment methods and source app.
- Request initial details from the customer or donor.
- Put in a payment request with the data you have collected through the Payment API.
- Based on the API response, perform additional actions, such as redirecting or additional data collection
- Provide final status confirmation of the transaction to the payer.
For details and visuals, please visit our How the payment API works article.
Before you start
Before you can start to develop an integration with the Payment API, you need:
- A licensed installation and configured FinDock app in a Salesforce environment or ‘org’ with payment methods you want to use set up properly. Ask your Salesforce admin or visit Installing FinDock packages.
- Authenticated access through a ‘Connected App’ with Oauth2 flow in the above Salesforce org authentication
- A working connection with the WebHub in your Salesforce org.
- 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.
- Check out the latest version of our API
- If you want to build a generic API for several organizations, get in touch so we can support you better.
We recommend you develop your API against a Salesforce sandbox environment. You can use a 30-day trial of FinDock to get started. You will need a license afterwards. Please contact support if you want an extended partner license.
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.
If the API returns no payment methods, this most likely means no payment methods have been activated. For more information, see Activating payment extensions.
Alternatively, you can get Payment Methods and Payment Processors through the GET /PaymentProcessors endpoint, which returns similar data in the response, but grouped by Processor instead of Payment Method.
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"
}
}
In this example, only the most basic parameters are used. Please visit our API Reference for a full list and detailed description of API request and response parameters.
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.