(Classic) Troubleshooting the Payment API v1

END-OF-LIFE ANNOUNCEMENT The Classic Online Experience with Payment API version 1 will be decommissioned at the end of 2024. All Payment API integrations should migrate to version 2, the Enhanced Online Experience, by January 2025.

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.

API response codes

The API always returns the status 200, with a ResponseCode and an IsSuccess parameter in the body. When IsSuccess = False, an Error object is returned.

Response Code	Description
001	Request processed successfully
010	Malformed request: missing one or more mandatory parameters
011	Malformed request: missing one or more mandatory Payment Processor parameters
012	Malformed request: missing one or more mandatory Source Connector parameters
020	Invalid data: the supplied data is incorrect (e.g. an invalid email
address)
030	Deduplication error: the request failed because a [deduplication
rule](https://docs.findock.com/api-v1/#deduplication) prevented record creation
and/or an update
040	Invalid API token: only possible when using the API unauthenticated,
which is strongly discouraged
098	An object is missing, and no default is specified
999	Error without specific category: check error_message for details

Common issues

The following sections describe the most common issues and (possible) solutions.

Authentication or access rights issues

Codes [040], [999] The first thing you need to ensure is correct are the authentication to the specific Salesforce or and the access rights of the ‘Site Guest User’ and ‘Integration User’ configured to handle Payment API calls.

Issue Missing access rights to a Salesforce org and/or permissions to specific Objects and Fields in Salesforce. Example error:

    {
    "message": "Session expired or invalid",
    "errorCode": "INVALID_SESSION_ID"
    }

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 `refresh_token` to retrieve a new `authentication_code`.
‘Site Guest User’ does not have the correct permissions for the API	FinDock requires several permission sets to be assigned to the Site Guest User. Check the site guest user permissions against the required permissions.
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). Check the site guest user permissions against the required permissions
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 [010], [011], [012], [020], [098], [999] 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 [098]	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 [098]	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. Alternativley, configure a default Source Connector in the FinDock Setup.
“Required Parameter "Contact" missing for section Payer" or similar error
[010]	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 [030], [999]

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 URL not configured correctly in FinDock (for example, HTTP vs HTTPS)	Ensure you use the exact Salesforce Site URL with the right /path/, including trailing ‘/’ and leading ‘https.’ Ensure the Salesforce site configured in the Callback URL has been activated. 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. TwitterHandle__c), 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. cpm__Bank__Account__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.

Salesforce Workbench

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 the Workbench.
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/v1.0/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. Salesforce Workbench Payment API testing

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 Messages object example

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). Salesforce object history example

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

    "Error": {
            "error_message": "Invalid request. Please read the documentation or contact support.",
            "error_code": "999",
            "typeName": "API_Request_Base.ApiException",
            "stackTraceString": "Class.API_Payment_POST_V1_0.determinePaymentMethodAndEnrichRequestIfRequired: line 113, column 1\nClass.API_Payment_POST_V1_0.getPaymentMethodNameForPSP: line 37, column 1\nClass.API_Payment_POST_V1_0.validateRequestParameters: line 572, column 1\nClass.API_Payment_POST_V1_0.prepareData: line 246, column 1\nClass.API_Payment_V1_0.postPayment: line 69, column 1",
            "lineNumber": 113
    }

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:

cpm = FinDock
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 logs

Salesforce debug logging on, for example, the ‘Site Guest User’ or ‘Integration User’ 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

This information can help you determine whether the issue is with FinDock configuration, the PSP configuration or your API call. PSP dashboard example