Troubleshooting the Payment API v2

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 400 or 500. In the response you will find additional information on how to prevent or handle the error through an array of Errors with an error_code and error_message.

Example of a successful request (to the SourceConnector Provisioning API):

{
    "SourceConnectors": [
    {
        "Name": "PaymentHub",
        "PrettyName": "PaymentHub",
        "IsDefault": false
    }
    ]
}

Example of an error that is returned whenever an incorrect request is sent:

{
    "Errors": [
    {
        "error_message": "Amount can't be 0 or negative",
        "error_code": "200"
    }
    ]
}

Full list of possible response codes:

ResponseCode	Description
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
098	An object is missing and no default is specified
200	Invalid data: the supplied data is invalid or incorrect
500	Internal server error on PSP redirect
999	Error without specific category: consult the `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 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:

    {
    "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`.
The Salesforce user account used for API calls does not have the correct permissions for the API	FinDock requires several permissions to be assigned through permission sets or the FinDock Integration User permission group to the user that executes the API calls in Salesforce. For further information, see general 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], [098], [200], [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. Alternatively, 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 (Push) URL cannot be found by the PSP	Ensure the WebHub has been activated and has a working connection in FinDock Setup. 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. `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/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.

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 Log object

Every time a Payment API request or outbound WebHook notification results in an error, FinDock creates a record of the object Log in Salesforce.

For requests we store the initial request and the resulting error in the Message field.

API Log record example

For outbound webhook notifications we store the following data in the Message field:

Webhook Url: <url>
Outbound Payload: <generated Payload>
Exception: <Exception message - exception stack trace>

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

FinDock Inbound Report object

When you get no errors in the Log object or problems in the Messages object, but still don't see the expected behaviour there's usually an issue creating data in Salesforce. These issues can be found on the Inbound Report record.

For example, if you see no Installment or Recurring Payment you can check the Inbound Report related to your PaymentIntent call using the paymentIntentId returned in the API call.

If the status of your Installment isn't updated or you see no Mandate and Payment Profile you can check the Inbound Report created for the Notification of the Payment Service Provider.

For more details on online payments and Inbound Reports, please visit our Processing and reconciling online payments article.

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 (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 further 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. PSP dashboard example