• Payment API

Payment Intent

The /PaymentIntent endpoint supports handling both one-time and recurring payments. For recurring payments, a Recurring block replaces, or is added alongside, the OneTime block in the request. Some Payment Service Providers (PSPs) require or optionally support an initial payment (a OneTime block) AND recurring payment in the same request for authorization. You can find out the initial payment details for a given PSP using GET /PaymentMethods. Please see the specific payment processor articles for further details.

When using the endpoint to initiate new payments, check the org configuration and make sure you have the correct details by querying the Payment Method and Source Connectors endpoints. Some payment methods enable or require further Package Actions. Be sure to also include these in the payment intent request.

In addition to setting up new one-time or recurring payments, you can pay existing one-time payments (installments) and update existing recurring payments. To pay an existing installment, simply exclude the Payer block and add the Id of the installment to the OneTime block. We recommend first checking the details of the installment using GET /Installment with the GUID or record Id.

To update the payment method, processor or other details of a recurring payment, remove the Payer block and add the identifier of the recurring payment to the Recurring block along with a PaymentMethod block that includes the details to be changed. As with installments, we recommend first checking current details by using GET /Recurring with the GUID or record Id.

The endpoint also supports checking the status of an existing installment or recurring payment. Use GET /PaymentIntent/{ID} where ID is payment intent Id for the installment or recurring payment.

Payment Intent object schema

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 as an Installment record in Salesforce.

Recurringobject (Recurring)

Data about a 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

Initiate, pay or update

The /PaymentIntent endpoint supports three POST actions: (1) initiate a new one-time or recurring payment, (2) pay an existing installment, and (3) update an existing recurring payment. All actions automatically update Salesforce data accordingly.

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 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 processed.

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": "Test",
        "LastName": "Payment",
        "Email": "test@findock.com",
        "MailingStreet": "Rocket Rd",
        "MailingCity": "Hawthorne",
        "MailingPostalCode": "CA 90250",
        "MobilePhone": "98989898"
      }
    }
  },
  "PaymentMethod": {
    "Name": "Direct Debit",
    "Parameters": {
      "iban": "NL13TEST0123456789",
      "holderName": "Test Payment"
    }
  },
  "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": "NL13TEST0123456789",
      "holderName": "Test Payment"
    }
  },
  "Settings": {
    "SourceConnector": "PaymentHub-for-NPSP",
    "ProcessingType": "CustomInboundReportSubType"
  },
  "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

Retrieve status

This endpoint returns the status of the inbound report for an installment or recurring payment along with information about the related installment or recurring payment record (of Recurring Payment, Gift Commitment or Recurring Donation object). To get details of the records themselves, use the /Installment and /Recurring endpoints.

IDstring

required

The Id of the payment intent to check.

Example
"pi_1hubybk7nh45rvbt6"

Responses

Response examples

API was called successfully.

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

Was this page helpful?