# 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

## Security:

  - `Salesforce_Production` (unknown)
    oauth2 scopes: full

  - `Salesforce_Sandbox` (unknown)
    oauth2 scopes: full

## Request fields (application/json):

  - `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)
    Information about the payer captured in a new or existing Account and/or Contact record.

  - `Payer.Id` (string)
    The unique GUID or Salesforce ID of the Account record.
    Example: 0011j00000itNdlAAE

  - `Payer.RecordTypeName` (string)
    The Salesforce record type of the Account record.
    Example: Household

  - `Payer.SalesforceFields` (any)
    Example: {"Name":"Payment Family","BillingStreet":"Any Street","BillingCity":"Any City","BillingPostalCode":"00000"}

  - `Payer.Id` (string)
    The unique GUID or Salesforce ID of the Contact record.
    Example: 0031j00000baD73AAE

  - `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/reconciliation/what-is-guided-matching).

  - `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/reconciliation/what-is-guided-matching)
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","acquisitionMeth…

  - `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

  - `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

  - `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

## Request examples:

  - `BasicOneTime` (unknown)
    A simple payment intent payload for a one-time payment with minimum required information.

  - `BasicRecurring` (unknown)
    A simple payment intent payload for a recurring payment with minimum required information.

  - `BasicRecurringWithInitialPayment` (unknown)
    A payment intent payload for a recurring payment that includes an initial one-time charge.

  - `BasicPayExistingInstallmentWithId` (unknown)
    A payment payload intent for paying an existing installment using the installment record Id for reference.

  - `BasicPayExistingInstallmentWithGUID` (unknown)
    A simple payment intent payload for paying an existing installment using the installment GUID for reference.

  - `AdvancedWithWebhook` (unknown)
    A payment intent payload for a one-time payment with a URL for webhook notifications.

  - `AdvancedWithOverrideProcessor` (unknown)
    A payment intent payload for a one-time payment that overrides the default payment processor for the payment method.

  - `AdvancedWithNonDefaultTarget` (unknown)
    A payment intent payload for a one-time payment that overrides the default target for payment method and its default payment processor.

  - `AdvancedWithFullContactAndAccount` (unknown)
    A payment intent payload for a one-time payment that includes details to create (after deduplication) of Contact and Account records for the payer.

  - `AdvancedWithOriginCampaign` (unknown)
    A payment intent payload for a one-time payment that includes the origin (channel) of the payment and associates the payment with a specific campaign in Salesforce.

  - `AdvancedWithOneTimeSFFields` (unknown)
    A payment intent payload for a one-time payment that includes additional information in Salesforce fields on the Installment record.

  - `AdvancedWithRecurringSFFields` (unknown)
    A payment intent payload for a recurring payment that includes additional information in Salesforce fields on the recurring record.

  - `AdvancedWithInboundReportSFFields` (unknown)
    A payment intent payload for a one-time payment that includes additional information to add to Salesforce fields on the Inbound Report record,
for example, to handle business-specific reconciliation logic.

  - `AdvancedWithPackageActions` (unknown)
    A payment intent message for a one-time donation that also creates a new Gift Aid Declaration record for the donor. The package action is available
in orgs with the FinDock source connector for Gift Aid.

  - `AdvancedWithMultiCurrency` (unknown)
    A payment intent payload for a recurring payment in a multi-currency org that explicitly passes the payment currency.

  - `AdvancedWithIdempotencyKey` (unknown)
    A payment intent payload that includes an idempotency key for the one-time payment to ensure the payment intent cannot be duplicated.

  - `AdvancedWithSourceAndMatchingSetup` (unknown)
    A payment intent message that sets the source (e.g. to override the default source connector) specific a special Inbound Report sub type to use
for matching and reconciliation rather than the default sub type for payment intent inbound reports provided by FinDock.

  - `UpdateRecurringMethod` (unknown)
    A payment intent payload to change the payment method of an existing recurring payment.

  - `UpdateRecurringMethodProcessor` (unknown)
    A payment intent payload to change the payment method and processor of an existing recurring payment.

  - `UpdateRecurringMethodProcessorTarget` (unknown)
    A payment intent payload to change the payment method and target of an existing recurring payment.

  - `UpdateRecurringMethodWithInitialPayment` (unknown)
    A payment intent payload to change the payment method of an existing recurring payment to a method that requires an initial charge,
like changing from direct debit to credit card.

## Response 200:

  - `200` (unknown)
    API was called successfully.

## 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 400:

  - `400` (unknown)
    The message was well-formed, but could not be processed.

## Response 422:

  - `422` (unknown)
    Something was wrong with the request parameters sent to the API. See [Error and response codes](/api/payment-api-v2/section/error-and-response-codes) for more information.

## Response 422 fields (application/json):

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

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

## Response 500:

  - `500` (unknown)
    Correct Request, but API call failed on an internal server error.