This article describes an integration with version 2 of the Payment API. If you are working on an existing API version 1 implementation, we strongly recommend you migrate to API v2. Please visit our migration article.
Enhanced Online Experience (with API v2) will be in Beta from the October '20 release onwards.
When something goes wrong with a Payment API call, FinDock tries to help you with Response Codes and descriptive Error Messages. However, due to the underlying complexity of the Salesforce platform, sometimes we are unable to determine the nature of the problem. In these cases, the API returns error code 999 with a generic error message. The information gathered here will hopefully help you troubleshoot both specific and generic API errors.
Error and Response Codes
When the API was not called successfully, you will receive a HTTP Status Code
In the response you will find additional information on how to prevent or handle the error through an array of
Errors with an
Example of a successful request (to the SourceConnector Provisioning API):
Example of an error that is returned whenever an incorrect request is sent:
Full list of possible response codes:
|010||Malformed request: missing one or more mandatory core parameter(s)|
|011||Malformed request: missing one or more mandatory Payment Processor parameters|
|012||Malformed request: missing one or more mandatory SourceConnector parameters|
|020||Invalid data: the supplied data is incorrect (e.g. an invalid email address)|
|098||An object is missing and no default is specified|
|999||Error without specific category: consult the |
The following sections describe the most common issues and (possible) solutions.
Authentication or access rights issues
Codes ,  The first thing you need to ensure is correct and valid authentication to the specific Salesforce environment and FinDock objects.
Issue Missing access rights to a Salesforce org and/or permissions to specific Objects and Fields in Salesforce. Example error:
|Possible root causes||Possible solution(s)|
|Missing or expired bearer token||Setup authentication with the Salesforce environment and pass the Bearer in the Authorization header. Use the |
|The Salesforce user account used for API calls does not have the correct permissions for the API||FinDock requires several permission sets to be assigned to the user that executes the API calls in Salesforce, usually a non-person account (Integration User).|
|The Salesforce user account used for API calls does not have the correct permissions for the one or more Salesforce Objects that are updated once FinDock has created data in Salesforce.||Since a lot of logic can be triggered when creating or updating a contact, account or other records in Salesforce, the (Integration) user executing the API calls requires access to these objects. For instance, if you use the Salesforce Nonprofit Success Pack (NPSP), an account is created if a new contact is made without an existing account. Also check for permissions on opportunity objects.|
Missing or incorrect data issues
Codes , , , , ,  A lot of issues are caused by either missing or invalid request parameters. These errors can be thrown both by the Payment API itself, or by processes in Salesforce like validation rules and Apex classes. Some of the most common errors and their possible root causes and solutions are described in the table below.
|Issue||Possible root cause(s)||Possible solution(s)|
|"Contact error: Required fields are missing: [LastName]" or similar error||Even though the field is not required in the API, there might be logic set up in Salesforce that makes the field required on insert or update.||Check your Salesforce configuration, e.g. validation rules, to see if the field is mandatory and adjust accordingly.|
|"No Default Setup Record found for category PSP" or similar error ||API request is missing the ‘Payment Method’ object||Make sure your request adheres to the request parameters in the API reference guide|
|“No Default Setup Record found for category source” or similar error ||API request is missing the ‘Source Connector’ object and no default Source Connector has been configured||Make sure your request adheres to the Request parameters in the API reference guide. Alternatively, configure a default Source Connector in the FinDock Setup.|
“Required Parameter "Contact" missing for section Payer" or similar error  | API request is missing Payer data | Make sure your request adheres to the request parameters in the API reference guide by either including a Payer block with Contact and/or Account, and valid InstallmentId in the Payment block.
Missing or incorrect configuration issues
Many issues are caused by a missing or incorrect configuration Salesforce and/or FinDock. Please always double-check if you have followed our configuration instructions step-by-step and confirm the configuration is correct. Codes , 
|Issue||Possible root cause(s)||Possible solution(s)|
|‘Page not found’ or similar||HTTP instead of HTTPS||When you create a site in Salesforce, it might look like an HTTP URL in the Salesforce Setup field. However, it reroutes to a HTTPS URL. All FinDock related configuration and setup should be done with HTTPS.|
|Redirect URL gives error or unexpected result||Payment extension for the processor incorrectly configured||When you get an error page after clicking the RedirectURL returned by the API, we often find that the configuration in the processor (like Mollie, Adyen, Stripe) console is not correct. Please check your settings against the relevant payment extension articles. NOTE: With some processors we also see very specific errors like ‘Invalid Credit Card number’ returned that are caused by deviations in the general setup and not by issues with the actual credit card details passed by the API.|
|No payment in Salesforce or Installment not updated after Payment is completed from PSP side||Callback/Push URL cannot be found by the PSP||Ensure the WebHub has been activated and has a working connection in FinDock Setup > WebHub. If applicable to this Payment Extension configuration (as mentioned in the configuration document), ensure you have copied the exact Notification URL into the PSP dashboard configuration. Ensure the payment extension endpoint is activated and deployed in FinDock Setup > Remote Site Settings and in the Salesforce Setup > Remote Site Settings.|
|API throws “Cannot deserialize instance of date from VALUE_STRING value 04-05-1986 or request may be missing a required field” or similar error "Unknown field: cpm.API_Request_Response.Payer.ExtraterrestrialAttribute" or similar error “System.NullPointerException: Attempt to de-reference a null object” or similar error||The API uses strict deserialization, so you cannot use parameters and values that are unknown to the API as request parameters, or as a (custom) field on the sObject you are trying to update. These errors can also be thrown when a call from the API triggers logic in Salesforce that tries to copy / update other objects.||Check if you are using the correct parameters as specified in the API reference guide. Check if the fields you are using are present on the sObject you are trying to update. Check if you are passing custom fields in the CustomFields object in the request for FinDock custom objects like Recurring and Payment. Check if you are using the correct format for passing custom fields on Standard Salesforce Objects like Contact in the API (e.g. ´TwitterHandlec´), including ´c´. Check if you are using the correct format for passing custom fields on Custom Salesforce Objects like Payment in the API (e.g. ´cpmBankAccount__c´), including the namespace of the package. Check if updating one of the sObjects in the API (like Contact, Installment, Payment) triggers logic like mapping Installment fields to Opportunity fields (standard in NPSP) or other sObjects. If this is the case, check if the field you are trying to update (like campaign) is available and accessible on all objects in the chain.|
Tools to help troubleshooting
The root cause of a Payment API issue can be either in your API call, the API, other (3rd party) packages, Salesforce or customization of the Salesforce org. There are several tools at your disposal to narrow down the origin of the problem.
To quickly simulate an API call with an authenticated user, you can use the Salesforce Workbench. Since you will be executing the call from an authenticated context and probably with an admin user, this is a quick way to find out whether you have issues with authentication. It also allows you to test out use cases without coding to see if the Salesforce and FinDock configuration are working correctly.
To use Salesforce Workbench:
- Go to https://workbench.developerforce.com
- Select Production (if you are using a Production environment or Developer org) or Sandbox.
- Log in with Salesforce and click Allow Access.
- Go to Utilities > REST Explorer.
- Set URL to /services/apexrest/cpm/v2/PaymentMethods or one of our other endpoints.
- Select the right operation (e.g. GET or POST).
- If trying to perform a POST, add a request body.
- Click Execute.
The workbench shows you the response both Structured and Raw.
We strongly advise you to work with a dedicated tool like Postman for further development and testing of your API requests.
FinDock Messages object
FinDock stores all inbound and outbound messages in the Messages object in the FinDock app including, for instance, the payload of the message. You can find them under FinDock > Messages in Salesforce.
- If you do not find a message corresponding to the webhook call of the payment processor, check the settings related to the Remote Site Settings and Callback URL as described above.
- If the status of the message is 'Scheduled' instead of 'Finished,' wait for a little while and check again. FinDock handles processor callbacks asynchronously.
- If the status of the message is ‘Failed,’ check ‘Failure Reason’ in the error section.
FinDock Log object
Every time a Payment API request results in an error, FinDock creates a record of the object
Log in Salesforce. On this record we store the initial request and the resulting error, for future reference and analysis.
Salesforce object history
Salesforce tracks the history of important fields like Status and Amount on FinDock objects, such as Installment. You can find the history in the Related section of a specific record. This can give you clues as to what did and did not happen and which user performed what action(s).
Verbose header parameter
If the Response Code and Error Message are too generic, you can add a header parameter ‘verbose’ with value ‘true.’ This returns the original status code and error thrown by Salesforce. Example with Status Code = 500
Since the code for managed packages in Salesforce (like FinDock) is obfuscated, you do not see a full stack trace or the actual code. However, information like the namespace and Apex class names can help you narrow down in which package the error has occurred to start root cause analysis. Common packages and namespaces found in Salesforce implementations with FinDock include but are not limited to:
npsp= Salesforce Nonprofit Success Pack
FinDock Support can use the error message to deep-dive the root cause if the issue was caused by our package.
Please only use this option in sandbox or developer environments, since the errors are not user friendly and are hard to handle programmatically.
Salesforce debug logging on, for example, the (integration) user you have chosen to acquire an authentication token and connect the WebHub with, can help narrow down the cause of an issue. Please refer to the Salesforce Set Up Debug Logging article for more information.
Payment processor dashboards
Almost all Payment Service Providers (PSPs) provide a dashboard, like the screenshot below, where you can check actions initiated by the FinDock Payment API. With these dashboard, you can check, for instance:
- Whether following the redirectURL returned in the response has led to (the correct) data with the PSP
- View what data (like amount, status of the payment) should have been sent from the PSP to FinDock
- Some PSPs even tell you what exact events were sent to what endpoint, so you can fruther pinpoint where the root cause can be found.
This information can help you determine whether the issue is with FinDock configuration, the PSP configuration or your API call.