Payment Intent

Download Spec

The /PaymentIntent endpoint allows for payments to be initiated through a configured Salesforce environment and updates Salesforce data accordingly. The PaymentIntent API requires a Payment Method, Payment Processor and Source Connector to perform a successful request.

The available Payment Method 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. You can initiate payments for existing installments.

To learn more, see How to use the Payment API.

The Payment Intent object

Idstring

The Payment Intent Id. Can also be found on the Inbound Report record in Salesforce.

Example: "pi_1hubybk7nh45rvbt6"

Statusstring

The Payment Intent Status.

Enum: New
Processing
Guided Review
Matched
Failed
Example: "Matched"

IdempotencyKeystring

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Example: "1hubybk7nh45rvbt6"

SuccessURLstring

The URL the user is redirected to when a payment has been completed successfully.

Format: url
Example: "https://www.example.com/success"

FailureURLstring

The URL the user is redirected to when a payment has failed or was cancelled.

Format: url
Example: "https://www.example.com/failure"

WebhookURLstring

URL where you want to receive webhook notifications about the status of the payment.

Format: url
Example: "www.findock.com/api/endpoint"

Originstring

The origin of the payment, e.g. Webform-1. This information can be used when building customized follow-up logic in Salesforce.

Example: "Webform"

CampaignIdstring

Id of a campaign in Salesforce. When a valid value is passed, the campaign is linked to the installment or recurring payment object in Salesforce.

Example: "7013X000001mAZbQAM"

Payerobject (Payer)

Data on the paying party. Can be an existing or new Account and/or Contact.

OneTimeobject (OneTime)

Data on new or existing single payment. Stored Installment record in Salesforce.

Recurringobject (Recurring)

Data on new Recurring Payment.

PaymentMethodobject (PaymentIntentPaymentMethod)

Data on how the payment is processed. Includes, for instance, the payment method, payment processor, target and additional required parameters.

Settingsobject (PaymentIntentSettings)

Data on how the payment should be processed in Salesforce. Includes the source connector and additional parameters like ProcessingType that can be used for Guided Matching.

SalesforceFieldsobject (InboundReportSalesforceFields)

The SalesforceFields block is used to pass Salesforce fields and values that have been created on the object in Salesforce. To find out which Salesforce Fields have been configured, check the 'Object Manager' in the Salesforce Setup.

Example: { "cpm__Campaign__c": "a070Y000005M7t6", "cpm__Origin__c": "My Form" }

PackageActionsarray

A list of additional actions that can be performed when making this request. Refer to the source connector or processor articles for further information.

post/PaymentIntent

Initiate a new payment

The FinDock Payment API supports both one-time and recurring payments. To perform recurring payments, a 'Recurring' block replaces the 'OneTime' block in the request. Some Payment Service Providers (PSPs) require an initial payment AND recurring payment in the same request for authorization of the transaction. You can find out whether this is the case for a specific Payment Processor through the GET /PaymentMethod and GET /PaymentProcessors endpoints. Please see the specific payment processor articles on the details of performing a one-time and/or recurring payment. To perform payments on an existing Installment, simply remove the Payer block and add the Id of the Installment to the OneTime block.

Must match one of

SuccessURLstring

required

The URL the user is redirected to when a payment has been completed successfully.

Format: url
Example: "https://www.example.com/success"

FailureURLstring

required

The URL the user is redirected to when a payment has failed or was cancelled.

Format: url
Example: "https://www.example.com/failure"

Payerobject (PayerRequest)

required

Specifies the payer of the payment. You can either pass Contact and / or Account fields like FirstName and LastName or a SalesforceId of an existing Contact and / or Account as Id. Contacts and Accounts can be deduplicated with Salesforce deduplication rules. If an Id of an existing Salesforce Installment record is provided in the OneTime object, this object is no longer required in the request. FinDock will instead the Contact and / or Account from the provided record.

PaymentMethodobject (PaymentMethodRequest)

Data on how the Payment will be performed.

OneTimeobject (NewPaymentRequest)

required

Create a new one-time Payment.

Responses

Request examples

{
  "SuccessURL": "https://www.example.com/success",
  "FailureURL": "https://www.example.com/failure",
  "Payer": {
    "Contact": {
      "SalesforceFields": {
        "FirstName": "Eric",
        "LastName": "Johnson",
        "Email": "test@findock.com",
        "MailingStreet": "Rocket Rd",
        "MailingCity": "Hawthorne",
        "MailingPostalCode": "CA 90250",
        "MobilePhone": "98989898"
      }
    }
  },
  "PaymentMethod": {
    "Name": "Direct Debit",
    "Parameters": {
      "iban": "NL44ABNA6333227641",
      "holderName": "Eric Johnson"
    }
  },
  "OneTime": {
    "Amount": 10.0
  }
}

Response examples

API was called successfully.

{
  "Id": "pi_1hubybk7nh45rvbt6",
  "PaymentMethod": {
    "Name": "Direct Debit",
    "Processor": "PaymentHub-SEPA",
    "Target": "PRIMARY-BANK-ACCOUNT",
    "Parameters": {
      "iban": "NL44ABNA6333227641",
      "holderName": "Eric Johnson"
    }
  },
  "Settings": {
    "SourceConnector": "PaymentHub-for-NPSP",
    "ProcessingType": "Default"
  },
  "RedirectURL": "https://myfindock-developer-edition.eu29.force.com/apex/moph__redirect?failureRedirectURL=http%3A%2F%2Fwww.failure.nl&installmentId=a083X00001brHBqQAM&paymentMethod=CreditCard&recurring=false&successRedirectURL=http%3A%2F%2Fwww.success.nl"
}

get/PaymentIntent/{ID}

Retrieve payment status

Returns the status of a specific payment. Response will contain data on what One-time or Recurring payments have been created. For one-time payments, further information can be retrieved by performing a GET request on the /Installment endpoint with the Id of the One-time object of type cpm__Installment__c provided in the response. If Payer data like Contact and Account was created or found in Salesforce, this data is also provided.

IDstring

required

The Id of the PaymentIntent to retrieve.

Example: "pi_1hubybk7nh45rvbt6"

Responses

Response examples

API was called successfully.

{
  "Id": "pi_1hubybk7nh45rvbt6",
  "Status": "Matched",
  "Payer": {
    "Contact": {
      "Url": "/services/data/v48.0/sobjects/Contact/0031j00000baD73AAE",
      "Type": "Contact",
      "Id": "a0P3X00000WjR8AUAV",
      "Name": "Eric Johnson"
    },
    "Account": {
      "Url": "/services/data/v48.0/sobjects/Account/0011j00000itNdlAAE",
      "Type": "Account",
      "Id": "a0P3X00000WjR8AUAV",
      "Name": "Johnson Family"
    }
  },
  "OneTime": {
    "Url": "/services/data/36.0/sobjects/a083X00001aUMCnQAO",
    "Type": "cpm__Installment__c",
    "Id": "a083X00001aUMCnQAO",
    "Status": "Outstanding"
  }
}