If you are just starting to work with the API, please see our Getting started with the Payment API article!

Since our API is created for Salesforce implementations, there are some Salesforce-specific things to take into account. Alongside the primitive datatypes such as String, the Payment API uses several datatypes that might be unknown to you if you are not familiar with Salesforce or the Force.com platform. The data types that are only applied in Salesforce contexts are Salesforce Objects (sObjects) and Record Types and custom fields.

sObjects

sObjects are objects that can be stored in the Force.com platform database, and they are representations of data that persists in the Salesforce database. Some API resources accept, or even require, sObjects. The Payer object, for example, requires sObjects such as Contact and Account. The API allows you to define these objects in requests, as shown below, where both a Contact and an Account sObject are defined. FinDock objects like PaymentProfile can be used in the same way, but require you to specify the fields as custom fields.

Example body of a request for creating a Contact and an Account sObject

{
    "SuccessURL":"http://success.com",
    "FailureURL":"http://failure.com",
    "Payer":{
        "Contact":{
            "FirstName":"Eric",
            "LastName":"Johnson",
            "Email":"eric@johnson.com",
            "MailingStreet":"Rocket Rd",
            "MailingCity":"Hawthorne0",
            "MailingPostalCode":"CA 90250",
            "MobilePhone":"98989898"
        },
        "Account":{
            "Name":"Johnson Family",
            "Website":"www.spacex.com",
            "BillingStreet":"Rocket Rd",
            "BillingCity":"Hawthorne",
            "BillingPostalCode":"CA 90250"
        },
        "AccountRecordTypeName":"Household",
        "AccountUpdate":"Replace",
        "ContactUpdate":"Replace",
        "AllowDeduplication":true,
        "PrimaryRelation":"Contact"
    }
}

Record Types

Record types let Salesforce administrators offer different business processes, picklist values, and page layouts to different users. Organizations can, for example, differentiate between Account objects in Salesforce by assigning them either to the Record Type of Organization or Household. This facilitates the application of different types of page layouts or possible field values based on what Record Type an Account is. Your Salesforce Administrator can tell you more about the Record Types used in the Salesforce org.

Custom Fields

Salesforce allows administrators to add custom fields to objects in Salesforce. These fields can be seen in the Salesforce Object Manager of the Salesforce org setup. The API allows you to send Salesforce custom fields, and their corresponding values, as attributes in requests to the API.

Custom fields for standard Salesforce objects like Contact and Account are passed with "__c" at the end. For illustration, we have added the field TwitterHandle to the Salesforce Contact object.

TwitterHandle | TwitterHandle__c | Text(50)

{
  "Payer":{
    "Contact":{
      "FirstName":"Eric",
      "LastName":"Johnson",
      "TwitterHandle__c": "@EricJohnsonSalesforce"
    }
  }
}

Custom fields for custom FinDock objects like Payment and Recurring are passed in a CustomFields object.

{
  "Payment":{
    "Amount": 10.0,
    "CustomFields": {
      "Sales_Invoice__c": "a506E0000009TfL"
    }
  }
}

Authentication is accomplished through an Oauth2.0 authorization flow. Each Salesforce environment requires its own token. A refresh token can be used to acquire a new access token if the current token has expired. Read more on how to authenticate to Salesforce in the Salesforce developer guide. Both client_secret and client_secret can be acquired from the Salesforce 'Setup' from a 'Connected App'.

• The Authorization token can be passed as a Bearer token in the request Header.
• To Acquire a new Authorization token with the returned Refresh token, please make sure to pass the right grant_type, client_id, client_secret and refresh_token as specified in the Salesforce documentation referenced above. To get up and running quickly, use the (unofficial-but-provided-by) Salesforce Postman Collection, as explained in this blog and look for the 'auth' folder.

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

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

{
    "ResponseCode": "001",
    "IsSuccess": true,
    "SourceConnectors": [
        {
            "Slug": "PaymentHub",
            "Name": "PaymentHub",
            "IsDefault": false
        }
    ]
}

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

{
    "ResponseCode": "999",
    "IsSuccess": false,
    "Error": {
        "error_message": "Contact error: Required fields are missing: [LastName]",
        "error_code": "999"
    }
}

Full list of possible response codes:

For more information on errors and response codes and debugging the API, please read our Troubleshooting the Payment API article.

To receive updates on a created Payment with the /Payments endpoint, you can pass an endpoint URL in the WebhookURL parameter in the request body. If the status of the Payment (Installment record in Salesforce) changes, either by an update from a PSP or manually, you will receive a notification with the following body. The message contains the id, status, amount and other data of the original Payment request, as well as actual performed Payments related to the request.

To allow webhook notifications to be sent from FinDock, you need to add your URL to the Remote Site Setting of the Salesforce environment.

{
"Url": "/services/data/v36.0/sobjects/Installment__c/a083E00000AG04mQAD",
"Type": "Installment__c",
"Id": "a083E00000AG04mQAD",
"Target": "Target Name 1",
"Status": "Collected",
"Payments": [
    {
        "Url": "/services/data/v36.0/sobjects/Payment__c/a0R3E000008WvL9UAK",
        "Type": "Payment__c",
        "Id": "a0R3E000008WvL9UAK",
        "Target": "Target Name 1",
        "PaymentProcessor": "PaymentHub-Mollie",
        "PaymentMethod": "ideal",
        "CollectionDate": "2020-03-26",
        "Amount": 100
    }
],
"PaymentProcessor":"PaymentHub-Mollie",
"PaymentMethod": "ideal",
"Amount": 100
}

Informational resource that returns a list of all available and active payment methods, and the active processors that have those payment methods enabled. Payment Methods range from Direct Debit, to Credit Card and various Online payments through Payment Service Providers (PSPs).

Informational resource that returns a list of all available and active payment processors that can be used to perform a payment, and the active payment methods which they support. A payment processor 'processes' the payment. Some Payment Processors require additional parameters to be passed. The API returns these with instructions in the 'Parameters' block in the response.

Informational resource that returns the source connector used in a specific Salesforce environement. A source connector represents an application in Salesforce that will be used to ultimately store the transaction that is being initiated through the Payment API.

Informational resource that returns the package actions possible and/or required for a certain Salesforce environment. Package actions are additional actions that can be performed for a specific FinDock Extension, like a payment extension or source connector. Package Actions can be used to perform additional actions in Salesforce through FinDock while making a Payment Request, like creating a record.

If a Payment Methods or Source Connector has a Package Action, these can be found in the specific Extension or Source Connector extension is an example of such a package.

The /Payments endpoint allows for Payments to be made through a configured Salesforce environment and updates Salesforce data accordingly. The Payment API requires a 'Payment Method', 'Payment Processor' and 'Source Connector' to perform a successful request. The available Payment Method, Processors and Source Connectors for a specific Salesforce environment can be queried through their specific endpoints. Some Payment Methods enable or require further Package Actions. Be sure to include these in the request. It is also possible to perform Payments on existing Installments.