Skip to main content

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:

ResponseCodeDescription
010Malformed request: missing one or more mandatory core parameter(s)
011Malformed request: missing one or more mandatory Payment Processor parameters
012Malformed request: missing one or more mandatory SourceConnector parameters
098An object is missing and no default is specified
200Invalid data: the supplied data is invalid or incorrect
500Internal server error on PSP redirect
999Error 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 causesPossible solution(s)
Missing or expired bearer tokenSetup 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 APIFinDock 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 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.

IssuePossible root cause(s)Possible solution(s)
"Contact error: Required fields are missing: [LastName]" or similar errorEven 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’ objectMake 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 configuredMake 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 dataMake 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]

IssuePossible root cause(s)Possible solution(s)
‘Page not found’ or similarHTTP instead of HTTPSWhen 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 resultPayment extension for the processor incorrectly configuredWhen 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 sideCallback/Push URL cannot be found by the PSPEnsure 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 errorThe 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.

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:

  1. Go to https://workbench.developerforce.com
  2. Select Production (if you are using a Production environment or Developer org) or Sandbox.
  3. Log in with Salesforce and click Allow Access.
  4. Go to Utilities > REST Explorer.
  5. Set URL to /services/apexrest/cpm/v2/PaymentMethods or one of our other endpoints.
  6. Select the right operation (e.g. GET or POST).
  7. If trying to perform a POST, add a request body.
  8. Click Execute.

The workbench shows you the response both Structured and Raw. Salesforce Workbench Payment API testing

note

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.

note

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