# Stripe

FinDock integrates with [Stripe](https://stripe.com/), a well-known international Payment Service Provider (PSP).

Please note that your contractual limitations with Stripe apply. If your contract doesn’t include a certain payment method, the FinDock extension cannot use that method either.

| [Multi-merchant](/docs/payment-processors/multi-merchant-accounts-for-psps) | [Multi-currency](/docs/payment-processors/multiple-currency-support-in-findock) |
|  --- | --- |
|  |  |


| Payment Method | [Online Payment Flow](/docs/payments/accepting-payments-with-findock#online-payment-collection) | [Integration Patterns](/docs/payments/accepting-payments-with-findock#online-integration-patterns) | [Data Entry](/docs/payments/accepting-payments-with-findock#data-entry) | One-time | Recurring | [Refunds](/docs/payment-processors/payment-methods/payment-methods-overview#refunds) |
|  --- | --- | --- | --- | --- | --- | --- |
| [ACH Direct Debit](/docs/payment-processors/payment-methods/ach-direct-debit) | Online Redirect | API, [Virtual Terminal](/docs/payments/accepting-payments-with-findock#findock-virtual-terminal) | No |  |  |  |
| [Apple Pay](/docs/payment-processors/payment-methods/apple-pay) | Online Redirect | API | No |  |  |  |
| [Bacs Direct Debit](/docs/payment-processors/payment-methods/bacs-direct-debit) | Online Redirect | API | No |  |  |  |
| [Bancontact](/docs/payment-processors/payment-methods/bancontact) | Online Redirect | API | No |  |  |  |
| [BLIK](/docs/payment-processors/payment-methods/blik) | Online Redirect | API | No |  |  |  |
| [Card](/docs/payment-processors/payment-methods/cards) | Online Redirect | API, Virtual Terminal | No |  |  |  |
| [iDEAL - Wero](/docs/payment-processors/payment-methods/ideal) | Online Redirect | API | No |  |  |  |
| [Google Pay](/docs/payment-processors/payment-methods/google-pay) | Online Redirect | API | No |  |  |  |
| [Pre-authorized Debit (PAD)](/docs/payment-processors/payment-methods/pre-authorized-debit) | Online Redirect | API | No |  |  |  |
| [Przelewy24](/docs/payment-processors/payment-methods/przelewy24) | Online Redirect | API | No |  |  |  |
| [Satispay](/docs/payment-processors/payment-methods/satispay) | Online Redirect | API | No |  |  |  |
| [SEPA Direct Debit](/docs/payment-processors/payment-methods/sepa-direct-debit) | Online Redirect | API | No |  |  |  |


**Prerequisites**

* FinDock installed and configured
* WebHub connected
* A Stripe [account](https://docs.stripe.com/get-started/account/activate) and a [sandbox](https://docs.stripe.com/sandboxes) for [testing](https://docs.stripe.com/testing)


## Install the Stripe extension

Follow the standard procedure for [installing payment processors](/docs/setup/add-payment-extensions) to add the Stripe payment extension and activate payment methods.

Check and assign the [required permissions](/docs/setup/general-permission-guidance). If you are using custom permission set groups, ensure the [package-specific permission sets](/docs/setup/permission-set-groups#stripe-permission-sets) are assigned.

## Configure the Stripe extension

After the Stripe payment extension is activated in FinDock, you need to link it to your Stripe account. Please take note of the following:

* Do not connect a Stripe account to FinDock in multiple orgs. You should use one connection per Stripe account (test or live mode) to avoid Stripe notifications going to the wrong org.
* Avoid connecting a Stripe account to multiple 3rd party applications. FinDock may receive notifications from other connected apps which end up as failed inbound reports. You can use Guided Matching to check the Raw Message field on the failed report for indications of which application is the source of the notifications to gracefully handle the failures, but it would be better to [restructure accounts](https://docs.stripe.com/get-started/account/multiple-accounts) and separate your connected applications.


When connecting to Stripe, Stripe asks you to select an account from your available Stripe accounts. If the account you want to use is not displayed, please check that the account uses the [Stripe Developer role](https://docs.stripe.com/get-started/account/teams/roles).

To connect FinDock to a Stripe account:

1. Launch the FinDock app and click the **FinDock Setup** tab.
2. Click **Processors & Methods** in the left-hand menu.
3. On the **Installed** tab, click the Stripe processor entry.
4. Click **Add account** and enter a name for the Stripe account (distinguishable from other targets).
5. Adjust the toggles as needed.
  * **Test Account**: enable if you are setting up a configuration to connect with a [Stripe sandbox](https://docs.stripe.com/sandboxes)
  * **Default Account**: enable if this account should be used as the default account for Stripe payments.
  * **ACH Instant Verification Only**: enable to only allow payers to verify their bank account by logging in to their bank. For information, [see below](#ach-and-pad-bank-account-validation)
  * **PAD Verification Method**: define the accepted verification method(s) for new PAD payments. For information, [see below](#ach-and-pad-bank-account-validation)
6. Click **Connect with Stripe**. You are redirected to the Stripe Connect page.
7. Select the Stripe (sandbox or live) account for this integration and enter your credentials. Do not use the **Skip this form** option. This creates an anonymous connection for demonstration only.
8. Wait to be redirected back to FinDock and click **Save**.


If you add more accounts, use the default toggle to define which account should be used in calls the Payment API that don't specify an account (target).

To disconnect a Stripe account, simply go to the account settings and click **Disconnect Stripe**.

If you migrating from a previous Stripe integration with FinDock, you need to manually delete the old webhooks for FinDock in your Stripe account.

## Paying with Apple Pay and Google Pay

Stripe enables payments with an Apple Pay or Google Pay digital wallet. No extra configuration is required to enable this for FinDock.

To use Apple Pay and Google Pay:

1. Create an installment with payment method CreditCard and payment processor PaymentHub-Stripe.
2. Redirect the user to the Stripe (CreditCard) checkout payment page on their Android or Apple device (or in their Chrome browser logged in with their Google Account).
  * If the installment was created through the FinDock API, please use the RedirectURL provided in the response.
  * If the user has a digital wallet installed, Stripe automatically recognizes the wallet and shows an Apple Pay or Google Pay button.
3. When the payer clicks the button:
  * If data like billing address and email address missing: prompted to add these from this screen:

  * Prompted to pay with Passcode
4. The payer is redirected to:
  * SuccessURL if the payment is successful
  * FailureULR if the payment was cancelled or unsuccessful


FinDock updates the original installment with the status of the payment and stores a payment linked to the  installment with a payment profile containing the wallet details from Stripe. Since both debit and credit cards can be used with wallets, the type of card is stored in the ‘Funding Type’ field.

### Recurring Google Pay payments

If a recurring payment is set up with Google Pay, you collect future installments [using payment schedules](/docs/payments/using-payment-schedules).  Installments are automatically included in payment schedules with PaymentHub-Stripe as the payment processor and CreditCard as the payment method.

Payment collection follows the normal process with updates to installments coming automatically through regular notifications from Stripe.

## Setting up direct debits

You can use Stripe to create and collect direct debit payments use [Stripe's bank debit payment flows](https://docs.stripe.com/payments/bank-debits).

A new direct debit payment through Stripe can only be created online. That is, you need to use the FinDock Payment API, either through a custom front end, [Giving Pages](/docs/payments/configuring-giving-pages) or [PayLinks](/docs/payments/configuring-findock-paylinks).

The FinDock Core [mandate service](/docs/setup/configure-findock-core#configure-mandate-service) is not used to handle Stripe direct debit mandates. These mandates are fully managed by Stripe. The Mandate records in Salesforce only reflect the information FinDock receives through `mandate.updated` events from Stripe. Changes made directly to the records in Salesforce are not pushed to Stripe.

With PAD payments, the success confirmation from Stripe may arrive up to five days after the payment intent is created.

### ACH and PAD bank account validation

For ACH and PAD direct debits, Stripe offers two options to verify the bank details and ownership of the bank account:

* Instant Verification: the payer logs into their bank account on Stripe's hosted payment page. This also means the payer doesn't have to manually enter their bank details.
* Micro-deposits: the payer chooses "Enter bank details manually" on the Stripe hosted payment page and is sent two micro-deposits to their bank account by Stripe. Stripe sends the payer an email with instructions and a link to a Stripe page on which the customer can enter the micro-deposit amounts or code from the bank statement. The payer has a limited number of days to perform this action before the validation method expires.


#### Modify bank account validation methods

The bank account validation methods you offer to payers are determined by the target (merchant account) specific settings in FinDock Setup. By default, both instant and micro-deposition validation are enabled.

Bank account validation settings for Stripe target
#### Testing bank account validation

If you allow micro-deposits, we recommending testing your configuration.

To test verifying bank details with micro-deposits:

1. Set up a new payment through a custom payment form, FinDock Giving Pages or PayLinks.
2. Go to the Inbound Reports tab in your Salesforce environment.
3. Find the Inbound Report with Report Type = `PaymentHub-Stripe` and Report SubType = `setup_intent.requires_action`.
4. In the Raw Message field, find the `hosted_verification_url` and click the link.
5. Follow the instructions on the Stripe page. You can find test values in the [Stripe documentation on ACH Direct Debit](https://stripe.com/docs/payments/ach-debit#test-microdeposit-amounts-and-descriptor-codes).


It is not possible to receive the actual email your customer will receive from Stripe in test environments.

## Stripe refunds and installment status handling

You can refund payments processed through Stripe using the [Stipe Dashboard](https://docs.stripe.com/refunds). Refunds and other actions trigger events which FinDock automatically processes.

| Stripe event | Installment status | Payment record |
|  --- | --- | --- |
| charge.captured | Collected | Create payment |
| charge.failed | Failed | No payment |
| charge.pending | Pending | No payment |
| charge.refunded | Refunded | Create negative payment |
| charge.succeeded | Collected | Create payment |
| charge.dispute.funds_reinstated | Collected | Create payment |
| charge.dispute.funds_withdrawn | Refunded | Create negative payment |


Other Stripe events do not trigger changes to the installment status.

You can [modify Guided Matching for key events](/faq/how-can-i-find-the-installment-for-a-stripe-charge) like charge.captured to support custom business processes like payouts.

## Payment API messages

The following are example messages for single and recurrent payments using the Payment API.

The FinDock integration supports pre-filling the Stripe Checkout hosted payment page. This requires precise Salesforce deduplication rules. If you deduplicate a contact just based on name, for example, it can lead to incorrect pre-filling which may raise concerns with payers. *Also note that pre-filling the email address can only be done with the standard Email field on Contact or the PersonEmail field on Person Account.*

### Dynamic parameters on checkout

The FinDock integration with Stripe supports Stripe-specific parameters for line item name (`line_item.name`) and description (`line_item.description`). The default name is “Donation” if no name value is passed.

Please note that only one product line item can be shown. FinDock does not directly support Stripe products with multi-line transactions through these parameters. To learn more about how to API parameters, please see our [API reference](/api/payment-api-v2/payment-intent/paymentintent).

The description value is dynamic and mapped to bank statement description (`cpm__bank_statement_description__c`). For example, in the following checkout page screenshot:

* `PaymentMethod.Parameters.itemName` = “Donation”
* `PaymentMethod.Parameters.description` = “test 123
* `oneTime.Amount` = “50.00”


![Stripe checkout parameters example](/assets/stripe-checkout-new-parameters.bf6e85a79a2d52452b4a263205f0d6d23b325a8cedd5c0b4d578b5259c77e7d8.f78e0b2f.png)

To dynamically set these Stripe-specific values in the API call, you would use this sort of message:


```json
 "PaymentMethod": {
        "Name": "Creditcard",
        "Processor": "PaymentHub-Stripe",
        "Parameters": {
            "itemName": "Donation"
            "description": "test 123"
           }
    },
```

Be careful using special characters, such as % $ #, in the description. Not all special characters are supported and may be rejected by Stripe.

### One-time payment with credit card


```json
{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
                "FirstName": "Test",
                "LastName": "Payment",
                "Email": "testpayment@findock.com"
            }
        }
    },
    "OneTime": {
        "Amount": "36"
    },
    "PaymentMethod": {
        "Name": "Creditcard",
        "Processor": "PaymentHub-Stripe"
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}
```

### Recurring payment with credit card

The following message is for a recurring payment that does not have an initial payment.

Custom Payment API front-end integrations, as well as Giving Pages, can include [an optional initial payment](/api/initial-payments-for-recurring-payments).


```json
{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Account": {
            "SalesforceFields": {
                "Name": "Test Payment account",
                "BillingStreet": "1234 Some Street",
                "BillingCity": "Some City"

            }
        }
    },
     "Recurring": {
          "Amount": "25",
          "Frequency": "Monthly",
          "StartDate": "2021-04-01"
     },
    "PaymentMethod": {
        "Name": "CreditCard",
        "Processor": "PaymentHub-Stripe"
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}
```

## Troubleshooting

### Paying through FinDock Payment (MOTO)

`Error From Stripe: Sending credit card numbers directly to the Stripe API is generally unsafe. [...]`

This error appears if your Stripe merchant account is not fully configured to take MOTO payments. Please contact your Stripe representative and tell them you need to "Handle card information directly" for MOTO payments. You can also find this setting in your [Stripe Dashboard](https://dashboard.stripe.com/settings/integration).
Stripe can guide you through everything that needs to be configured if you have further questions.