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

Endpoint: POST /PaymentIntent
Version: v2
Security: Salesforce_Production, Salesforce_Sandbox

## Request fields (application/json):

  - `body` (PaymentIntentNewOneTime (object) or PaymentIntentNewRecurring (object) or PaymentIntentPayInstallment (object) or PaymentIntentUpdateRecurring (object)) — one of:
    - PaymentIntentNewOneTime:
      - `SuccessURL` (string, required)
        The URL the payer is redirected to when a payment has been completed successfully.
        Example: "https://hostdomain.com/success"
      - `FailureURL` (string, required)
        The URL the user is redirected to when a payment has failed or was cancelled.
        Example: "https://hostdomain.com/failure"
      - `RedirectURL` (string)
        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.
        Example: "https://redirect-hostdomain.com/checkout/payment-parameters"
      - `WebhookURL` (string)
        URL where you want to receive [webhook notifications](/api/payment-api-v2/section/webhook-events-and-notifications) about the status of the payment.
        Example: "https://hostdomain.com/endpoint"
      - `Origin` (string)
        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"
      - `CampaignId` (string)
        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"
      - `Payer` (object, required) — one of:
        Information about the payer captured in a new or existing Account and/or Contact record.
        - Account:
          - `Id` (string)
            The unique GUID or Salesforce ID of the Account record.
            Example: "0011j00000itNdlAAE"
          - `RecordTypeName` (string)
            The Salesforce record type of the Account record.
            Example: "Household"
          - `SalesforceFields` (any)
            Example: {"Name":"Payment Family","BillingStreet":"Any Street","BillingCity":"Any City","BillingPostalCode":"00000"}
        - Contact:
          - `Id` (string)
            The unique GUID or Salesforce ID of the Contact record.
            Example: "0031j00000baD73AAE"
          - `SalesforceFields` (object)
            Example: {"FirstName":"Test","LastName":"Payment","Email":"test@findock.com","MailingStreet":"Any Street","MailingCity":"Any City","MailingPostalCode":"00000","MobilePhone":"012-3456789"}
      - `OneTime` (object, required)
        Value of the payment in the given currency.
      - `OneTime.Amount` (number, required)
        The amount collected or disbursed.
        Example: 10
      - `OneTime.CurrencyISOCode` (string)
        A valid [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). May be required depending on the Salesforce org configuration.
        Example: "EUR"
      - `PaymentMethod` (object, required)
        The payment processing details for the one-time payment.
      - `PaymentMethod.Name` (string, required)
        Name of the payment method.
        Example: "CreditCard"
      - `PaymentMethod.Processor` (string)
        Name of the FinDock package for the payment processor. If no processor is specified,
FinDock uses the default processor configured for the payment method.
        Example: "PaymentHub-Stripe"
      - `PaymentMethod.Target` (string)
        The merchant account that gets the money from the payment. If no target is provided,
FinDock uses whichever target that is set as the default in the payment processor configuration.
        Example: "Stripe-Main-Account"
      - `PaymentMethod.Parameters` (object)
        Additional parameters for the given payment method and processor combination.
        Example: {"locale":"en-GB"}
      - `Settings` (object)
        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](/docs/@production/reconciliation/what-is-guided-matching.md).
      - `Settings.SourceConnector` (string)
        The name of the source connector to use for processing, e.g. 'PaymentHub', PaymentHub-for-NPSP or 'FinDock-for-Fundraising'.
If no source connector is passed in the request, the default source connector set in the FinDock configuration is used.
        Example: "PaymentHub-for-NPSP"
      - `Settings.ProcessingType` (string)
        The Sub Type name of the Inbound Report which determines the [Guided Matching](/docs/@production/reconciliation/what-is-guided-matching.md)
setup which drives the data processing.
        Example: "CustomInboundReportSubType"
      - `SalesforceFields` (object)
        The SalesforceFields block is used to pass and values for the given 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"}
      - `PackageActions` (object)
        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"}}}
    - PaymentIntentNewRecurring:
      - `SuccessURL` (string, required)
        The URL the payer is redirected to when a payment has been completed successfully.
        Example: "https://hostdomain.com/success"
      - `FailureURL` (string, required)
        The URL the user is redirected to when a payment has failed or was cancelled.
        Example: "https://hostdomain.com/failure"
      - `RedirectURL` (string)
        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.
        Example: "https://redirect-hostdomain.com/checkout/payment-parameters"
      - `WebhookURL` (string)
        URL where you want to receive [webhook notifications](/api/payment-api-v2/section/webhook-events-and-notifications) about the status of the payment.
        Example: "https://hostdomain.com/endpoint"
      - `Origin` (string)
        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"
      - `CampaignId` (string)
        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"
      - `Payer` (object, required) — one of:
        Information about the payer captured in a new or existing Account and/or Contact record.
        - Account:
          - `Id` (string)
            The unique GUID or Salesforce ID of the Account record.
            Example: "0011j00000itNdlAAE"
          - `RecordTypeName` (string)
            The Salesforce record type of the Account record.
            Example: "Household"
          - `SalesforceFields` (any)
            Example: {"Name":"Payment Family","BillingStreet":"Any Street","BillingCity":"Any City","BillingPostalCode":"00000"}
        - Contact:
          - `Id` (string)
            The unique GUID or Salesforce ID of the Contact record.
            Example: "0031j00000baD73AAE"
          - `SalesforceFields` (object)
            Example: {"FirstName":"Test","LastName":"Payment","Email":"test@findock.com","MailingStreet":"Any Street","MailingCity":"Any City","MailingPostalCode":"00000","MobilePhone":"012-3456789"}
      - `OneTime` (object)
        One-time charge that may be required to set up and authorize the new recurring payment.
      - `OneTime.Amount` (number, required)
        The initial amount to be collected once.
        Example: 25
      - `Recurring` (object, required)
      - `Recurring.Amount` (number, required)
        The amount to be collected at regular intervals.
        Example: 10
      - `Recurring.Frequency` (string, required)
        The frequency with which installments are collected. e.g. 'Weekly', 'Monthly'. The formatting of the frequency options
depends on the source connector you provide in the payment intent message. Please adjust your values accordingly.
        Example: "Monthly"
      - `Recurring.CurrencyISOCode` (string)
        A valid [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). May be required depending on the Salesforce org configuration.
        Example: "EUR"
      - `Recurring.StartDate` (string, required)
        The first date the recurring payment is collected. Format is yyyy-mm-dd.
        Example: "2025-01-01"
      - `Recurring.EndDate` (string)
        The last date the recurring payment is collected. Format is yyyy-mm-dd.
        Example: "2025-12-01"
      - `PaymentMethod` (object, required)
        The payment processing details for the one-time payment.
      - `PaymentMethod.Name` (string, required)
        Name of the payment method.
        Example: "CreditCard"
      - `PaymentMethod.Processor` (string)
        Name of the FinDock package for the payment processor. If no processor is specified,
FinDock uses the default processor configured for the payment method.
        Example: "PaymentHub-Stripe"
      - `PaymentMethod.Target` (string)
        The merchant account that gets the money from the payment. If no target is provided,
FinDock uses whichever target that is set as the default in the payment processor configuration.
        Example: "Stripe-Main-Account"
      - `PaymentMethod.Parameters` (object)
        Additional parameters for the given payment method and processor combination.
        Example: {"locale":"en-GB","description":"Monthly membership fee"}
      - `Settings` (object)
        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](/docs/@production/reconciliation/what-is-guided-matching.md).
      - `Settings.SourceConnector` (string)
        The name of the source connector to use for processing, e.g. 'PaymentHub', PaymentHub-for-NPSP or 'FinDock-for-Fundraising'.
If no source connector is passed in the request, the default source connector set in the FinDock configuration is used.
        Example: "PaymentHub-for-NPSP"
      - `Settings.ProcessingType` (string)
        The Sub Type name of the Inbound Report which determines the [Guided Matching](/docs/@production/reconciliation/what-is-guided-matching.md)
setup which drives the data processing.
        Example: "CustomInboundReportSubType"
      - `SalesforceFields` (object)
        The SalesforceFields block is used to pass and values for the given 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"}
      - `PackageActions` (object)
        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"}}}
    - PaymentIntentPayInstallment:
      - `SuccessURL` (string, required)
        The URL the payer is redirected to when a payment has been completed successfully.
        Example: "https://hostdomain.com/success"
      - `FailureURL` (string, required)
        The URL the user is redirected to when a payment has failed or was cancelled.
        Example: "https://hostdomain.com/failure"
      - `RedirectURL` (string)
        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.
        Example: "https://redirect-hostdomain.com/checkout/payment-parameters"
      - `WebhookURL` (string)
        URL where you want to receive [webhook notifications](/api/payment-api-v2/section/webhook-events-and-notifications) about the status of the payment.
        Example: "https://hostdomain.com/endpoint"
      - `Origin` (string)
        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"
      - `CampaignId` (string)
        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"
      - `Payer` (object, required) — one of:
        Information about the payer captured in a new or existing Account and/or Contact record.
        - Account:
          - `Id` (string)
            The unique GUID or Salesforce ID of the Account record.
            Example: "0011j00000itNdlAAE"
          - `RecordTypeName` (string)
            The Salesforce record type of the Account record.
            Example: "Household"
          - `SalesforceFields` (any)
            Example: {"Name":"Payment Family","BillingStreet":"Any Street","BillingCity":"Any City","BillingPostalCode":"00000"}
        - Contact:
          - `Id` (string)
            The unique GUID or Salesforce ID of the Contact record.
            Example: "0031j00000baD73AAE"
          - `SalesforceFields` (object)
            Example: {"FirstName":"Test","LastName":"Payment","Email":"test@findock.com","MailingStreet":"Any Street","MailingCity":"Any City","MailingPostalCode":"00000","MobilePhone":"012-3456789"}
      - `OneTime` (object, required)
        Identification of the installment to be paid. The amount to pay is determined by the Amount Open
field on the Installment record.
      - `OneTime.Id` (string, required)
        The record Id or GUID of the installment.
        Example: "a083X00001aUMCnQAO"
      - `PaymentMethod` (object, required)
        The payment processing details for the one-time payment.
      - `PaymentMethod.Name` (string, required)
        Name of the payment method.
        Example: "CreditCard"
      - `PaymentMethod.Processor` (string)
        Name of the FinDock package for the payment processor. If no processor is specified,
FinDock uses the default processor configured for the payment method.
        Example: "PaymentHub-Stripe"
      - `PaymentMethod.Target` (string)
        The merchant account that gets the money from the payment. If no target is provided,
FinDock uses whichever target that is set as the default in the payment processor configuration.
        Example: "Stripe-Main-Account"
      - `PaymentMethod.Parameters` (object)
        Additional parameters for the given payment method and processor combination.
        Example: {"locale":"en-GB","description":"Monthly membership fee"}
      - `Settings` (object)
        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](/docs/@production/reconciliation/what-is-guided-matching.md).
      - `Settings.SourceConnector` (string)
        The name of the source connector to use for processing, e.g. 'PaymentHub', PaymentHub-for-NPSP or 'FinDock-for-Fundraising'.
If no source connector is passed in the request, the default source connector set in the FinDock configuration is used.
        Example: "PaymentHub-for-NPSP"
      - `Settings.ProcessingType` (string)
        The Sub Type name of the Inbound Report which determines the [Guided Matching](/docs/@production/reconciliation/what-is-guided-matching.md)
setup which drives the data processing.
        Example: "CustomInboundReportSubType"
      - `SalesforceFields` (object)
        The SalesforceFields block is used to pass and values for the given 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"}
      - `PackageActions` (object)
        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"}}}
    - PaymentIntentUpdateRecurring:
      - `SuccessURL` (string, required)
        The URL the payer is redirected to when a payment has been completed successfully.
        Example: "https://hostdomain.com/success"
      - `FailureURL` (string, required)
        The URL the user is redirected to when a payment has failed or was cancelled.
        Example: "https://hostdomain.com/failure"
      - `RedirectURL` (string)
        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.
        Example: "https://redirect-hostdomain.com/checkout/payment-parameters"
      - `WebhookURL` (string)
        URL where you want to receive [webhook notifications](/api/payment-api-v2/section/webhook-events-and-notifications) about the status of the payment.
        Example: "https://hostdomain.com/endpoint"
      - `OneTime` (object)
        One-time charge that may be required to authorize the updated recurring payment method.
      - `OneTime.Amount` (number, required)
        An initial amount to be collected once.
        Example: 1
      - `Recurring` (object, required)
      - `Recurring.Id` (string, required)
        The record Id or GUID of the recurring payment.
        Example: "a0V3X00000S7BuCUAV"
      - `PaymentMethod` (object, required)
        The payment processing details for the one-time payment.
      - `PaymentMethod.Name` (string, required)
        Name of the payment method.
        Example: "CreditCard"
      - `PaymentMethod.Processor` (string)
        Name of the FinDock package for the payment processor. If no processor is specified,
FinDock uses the default processor configured for the payment method.
        Example: "PaymentHub-Stripe"
      - `PaymentMethod.Target` (string)
        The merchant account that gets the money from the payment. If no target is provided,
FinDock uses whichever target that is set as the default in the payment processor configuration.
        Example: "Stripe-Main-Account"
      - `PaymentMethod.Parameters` (object)
        Additional parameters for the given payment method and processor combination.
        Example: {"locale":"en-GB","description":"Monthly membership fee"}

## Response 200 fields (application/json):

  - `Id` (string)
    The Payment Intent Id. Can also be found on the Inbound Report record in Salesforce.
    Example: "pi_1hubybk7nh45rvbt6"

  - `PaymentMethod` (object)

  - `PaymentMethod.Name` (any)
    Example: "CreditCard"

  - `PaymentMethod.Processor` (any)
    Example: "PaymentHub-Stripe"

  - `PaymentMethod.Target` (any)
    Example: "Stripe-Main"

  - `PaymentMethod.Parameters` (any)
    Example: {"description":"Monthly membership fee"}

  - `Settings` (object)

  - `Settings.SourceConnector` (any)
    Example: "PaymentHub-for-NPSP"

  - `RedirectURL` (any)
    Example: "https://redirect-hostdomain.com/checkout/payment-parameters"

## Response 422 fields (application/json):

  - `error_code` (integer, required)
    Example: 999

  - `error_message` (string, required)
    Example: "Contact error: Required fields are missing: [LastName]"