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 payment intent inbound report processing. Use GET /PaymentIntent/{ID} where ID is payment intent Id of the one-time or recurring payment.

Full Payment Intent Object

The schema below presents the entire scope of supported Payment Intent data. Please refer to the POST operation request body object schemas for details on what is required for specific operations.

SuccessURLstring

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

Format: url
Example: "https://hostname/success"

FailureURLstring

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

Format: url
Example: "https://hostname/failure"

RedirectURLstring

The URL where the user should be redirected to so additional information can be provided to complete the payment. This is primarily used for hosted payment forms of PSPs.

Format: url
Example: "https://redirect-hostname/checkout/payment-parameters"

WebhookURLstring

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

Format: url
Example: "https://hostname/endpoint"

Originstring

The channel used to create the payment intent, such as a payment form on a webpage. This information can be used when building customized follow-up logic in Salesforce.

Example: "Campaign payment form"

CampaignIdstring

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

Example: "7013X000001mAZbQAM"

PayerAny Of

Information about the payer captured in a new or existing Account and/or Contact record.

Must match one of

OneTimeobject

Details for a new one-time payment. If paying an existing one-time payment (installment), only Id is needed.

Recurringobject

The recurring block contains details for creating a new recurring payment or updated an existing one based on an Id.

PaymentMethodobject

The payment processing details for the one-time payment.

Settingsobject

Additional information 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

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

Example: { "cpm__Campaign__c": "a070Y000005M7t6", "cpm__Origin__c": "Online payment form" }

PackageActionsobject

Additional, package-specific actions to be performed with the payment intent.

Example: { "PaymentHub-GiftAid": { "CreateGiftAidDeclaration": { "dateMade": "2025-01-15", "startDate": "2025-02-01", "firstName": "Test", "lastName": "Donor", "houseNameOrNumber": 12, "postalCode": "L68 0AQ", "acquisitionMethod": "Digital" } } }

post/PaymentIntent

Create, pay or update payments

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

Must match one of

SuccessURLstring

required

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

Format: url
Example: "https://hostname/success"

FailureURLstring

required

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

Format: url
Example: "https://hostname/failure"

RedirectURLstring

The URL where the user should be redirected to so additional information can be provided to complete the payment. This is primarily used for hosted payment forms of PSPs.

Format: url
Example: "https://redirect-hostname/checkout/payment-parameters"

WebhookURLstring

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

Format: url
Example: "https://hostname/endpoint"

Originstring

The channel used to create the payment intent, such as a payment form on a webpage. This information can be used when building customized follow-up logic in Salesforce.

Example: "Campaign payment form"

CampaignIdstring

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

Example: "7013X000001mAZbQAM"

PayerAny Of

required

Information about the payer captured in a new or existing Account and/or Contact record.

Must match one of

OneTimeobject

required

Value of the payment in the given currency.

PaymentMethodobject

required

The payment processing details for the one-time payment.

Settingsobject

Additional information 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

Example: { "cpm__Campaign__c": "a070Y000005M7t6", "cpm__Origin__c": "Online payment form" }

PackageActionsobject

Additional, package-specific actions to be performed with the payment intent.

Example: { "PaymentHub-GiftAid": { "CreateGiftAidDeclaration": { "dateMade": "2025-01-15", "startDate": "2025-02-01", "firstName": "Test", "lastName": "Donor", "houseNameOrNumber": 12, "postalCode": "L68 0AQ", "acquisitionMethod": "Digital" } } }

Responses

Request examples

{
  "SuccessURL": "https://hostname/success",
  "FailureURL": "https://hostname/failure",
  "Payer": {
    "Contact": {
      "SalesforceFields": {
        "FirstName": "Test",
        "LastName": "Payer",
        "Email": "test@findock.com",
        "MailingStreet": "Any Street",
        "MailingCity": "Any City",
        "MailingPostalCode": "00000",
        "MobilePhone": "0123456789"
      }
    }
  },
  "PaymentMethod": {
    "Name": "DirectDebit",
    "Parameters": {
      "iban": "NL13TEST0123456789",
      "holderName": "Test Payer"
    }
  },
  "OneTime": {
    "Amount": 50.0
  }
}

Response examples

API was called successfully.

{
  "Id": "pi_1hubybk7nh45rvbt6",
  "PaymentMethod": {
    "Name": "CreditCard",
    "Processor": "PaymentHub-Stripe",
    "Target": "Stripe-Main",
    "Parameters": null
  },
  "Settings": {
    "SourceConnector": "PaymentHub-for-NPSP"
  },
  "RedirectURL": "https://redirect-hostname/checkout/payment-parameters"
}

get/PaymentIntent/{ID}

Check inbound report status

Use this operation to get the status of the inbound report of a payment intent along with information about the related installment or recurring payment (Recurring Payment, Gift Commitment or Recurring Donation object record). To get details of the related 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/v63.0/sobjects/Contact/a0P3X00000WjR8AUAV",
      "Type": "Contact",
      "Id": "a0P3X00000WjR8AUAV",
      "Name": "Test Payer"
    },
    "Account": {
      "Url": "/services/data/v63.0/sobjects/Account/0011j00000itNdlAAE",
      "Type": "Account",
      "Id": "0011j00000itNdlAAE",
      "Name": "Payer Family"
    }
  },
  "OneTime": {
    "Url": "/services/data/v63.0/sobjects/cpm__Installment__c/a083X00001aUMCnQAO",
    "Type": "cpm__Installment__c",
    "Id": "a083X00001aUMCnQAO",
    "Status": "Collected"
  }
}

Was this page helpful?