Stripe
The JustOn Self-Service Extension supports Stripe as a payment provider. It uses the Stripe Webhooks to implement the payment procedure. It uses Stripe Elements to securely accept the customer's payment details.
The payment provider implementation supports the following payment methods:
-
SEPA Direct Debit, with full support for future payments
Before using SEPA Direct Debit via Stripe, your Stripe account must regularly process credit card payments for 30 days. In addition, SEPA Direct Debit payments are subject to processing volume limits, and payments can fail if you exceed your limits. For details, see SEPA Direct Debit Payments in the Stripe documentation.
-
Credit card, with optional support for future payments
The future payment support depends on the credit card type and is not available with 3D Secure.
-
Alipay, without support for future payments
Stripe can use customers as a means to perform recurring charges without the need to prompt users for card or account numbers. The JustOn Self-Service Extension supports Stripe customers, exposing the feature as Future Payments option. For details about using customers for payment, see Saving Cards in the Stripe documentation.
Note
When using Stripe, be aware that the payment reference string (set in the field Payment Reference
on the invoice template) must include at least one letter.
Info
As opposed to the usual payment workflow (see Payment Page), the Stripe integration creates a payment balance when a payment becomes pending. This may be the case with payments that take a long time, like SEPA payments.
Consequently, the corresponding invoice is set Paid
without waiting for a success notification. If the payment processing fails, the Stripe integration triggers JustOn to delete the payment balance and to set the invoice Open
again.
Setting up Stripe as a payment provider involves the following tasks:
- Creating a Stripe account
- Enabling the Stripe webhook handler class
- Configuring the Stripe integration
Creating Stripe Account
In order to use Stripe as a payment provider, you need a valid Stripe account. Follow the instructions in Managing Your Account in the Stripe documentation.
Creating Stripe Webhook
In addition, you must create a webhook. The webhook configuration is also available in the Developers section of the Stripe Dashboard.
Info
The Stripe Dashboard makes a distinction between live and test data. Make sure to access the intended data by toggling the Dashboard's View test data option.
Use the following values to add a webhook endpoint:
-
URL to be called:
The URL is made up of the secure site URL of your Salesforce Site, the (optional) custom path component as defined as part of the site setup in
Default Web Address
, and the path/services/apexrest/ONBSE1/StripeWebhook
, likehttps://<instance>.secure.force.com[/<custom_path>]/services/apexrest/ONBSE1/StripeWebhook
or, if enhanced domains are enabled in your org, like
https://<mydomain>.my.salesforce-sites.com[/<custom_path>]/services/apexrest/ONBSE1/StripeWebhook
Make sure to use the secure site URL. Do not use the domain URL.
-
Webhook version: JustOn recommends to select
Your current version
. -
Filter event:
Select the following events
source.chargeable
charge.pending
charge.succeeded
charge.failed
charge.refunded
charge.refund.updated
payment_intent.succeeded
payment_intent.payment_failed
As of JustOn Self-Service Extension 1.52, the Stripe payment integration requires the
payment_intent
webhooks. If you upgrade from an earlier version, make sure to enable the corresponding filter eventspayment_intent.succeeded
andpayment_intent.payment_failed
after installing the new version.
After creating the webhook, click the webhook to reveal the signing secret (see also Check the webhook signatures). It is required for the configuring the Stripe integration.
Note
Make sure to enable the Apex class ONBSE1.StripeWebhookHandler in order to support the Stripe integration. For details, see Enabling Stripe Webhook Handler.
Required Information
For configuring the integration with the JustOn Self-Service Extension, you need the following information:
-
Publishable Key and Secret Key
The API keys are available in the Developers section of the Stripe Dashboard.
-
Webhook Secret
Click the webhook in the Stripe Dashboard to retrieve the secret.
Enabling Stripe Webhook Handler
As part of the payment-specific site setup, you must enable the specific Apex class ONBSE1.StripeWebhookHandler for your site in order to completely support the Stripe integration.
-
Open the Site Details of your site.
Type
Sites
in the Quick Find box, or navigate to User Interface > Sites and Domains > Sites. In the Sites list, click the label of the site to open its details. -
Click Public Access Settings to open the site profile.
-
In the Original Profile User Interface, scroll to the Enabled Apex Class Access section, and then click Edit.
If you use the Enhanced Profile User Interface, click Apex Class Access > Edit.
-
Add the Apex class ONBSE1.StripeWebhookHandler to the Enabled Apex Classes list.
- Click Save.
Configuring Stripe Integration
Note
The Stripe integration requires the Visualforce page ONBSE1.PaymentStripe added to your site. For details, see Assigning Payment-Specific Pages.
To configure the Stripe integration with the JustOn Self-Service Extension:
-
Open the Payment Provider Setup page.
Open the Payment Provider Setup page directly, or navigate to Custom Code > Visualforce Pages > PaymentProviderSetup in Setup, and open the preview.
-
Select the payment provider and click New to create a new setting, or click Edit next to an existing setting to modify it.
You can create one active payment provider setting per business entity and payment provider. Before creating a new setting for an entity/provider combination that already exists, you must deactivate the existing setting.
-
Select the business entities for which the setting is applicable.
If there is no business entity selected, this setting is used by default for all business entities.
-
Specify a name for this configuration setting.
Make sure to use a descriptive name that helps to unequivocally identify the configuration setting.
-
Specify the provider-specific configuration.
Field Required Notes Publishable Key The publishable key of the test or live universe of your account. Secret Key The secret key of the test or live universe of your account. Webhook Secret The signing secret of the Webhook. Enable Future Payments Select this checkbox if you want to enable the future payments feature. When checked, the future payment option is shown after confirming the Stripe payment form, allowing the user to opt for it. Future Payments Active Select this checkbox if you want to activate the future payments feature by default. This creates a corresponding payment instrument, which is saved on the account.
JustOn recommends to activate this setting in combination withFuture Payments Changeable
to allow users to opt out.Future Payments Changeable Select this checkbox if you want users to be able to override the Future Payments Active
value in the payment form.
Be aware that this setting has no effect once users have opted to use future payments. If required or on users' request, you deactivate individual payment instruments manually.Alipay Enables payments via Alipay.
Since Alipay does not support future payments, you must not select theEnable Future Payments
option for this payment method. You can, however, use future payments with other Stripe payment methods, and create a separate Stripe configuration for Alipay with future payments disabled.Credit Card Enables payments via credit card.
Enabled by default if no payment method is selected.SEPA Enables payments via SEPA direct debit. When editing existing configurations, key and secret values are not displayed. Key and secret values remain unchanged as long as you leave the corresponding fields empty.
-
Select the payment methods for which Stripe is to be used.
- Click Add for new settings or, respectively, Save for existing settings.
Stripe Refund Handling
Businesses can use JustOn's balance management functionality or the Stripe Dashboard to directly refund a payment made via Stripe. Based on the Apex Refund Interface, JustOn directly returns the specified amount to the customer and creates a balance record of the type Refund
for the account.
Enabling Payment Refund
To enable the refund functionality for Stripe payments in the JustOn user interface, you add the button Refund to the Balance detail page:
- Navigate to the object management settings of the Balance object.
- Click Page Layouts.
- Click Edit in the row of the Balance Layout.
-
Add the Refund button (API name
ONBSE1__Refund
) to the page layout.In Salesforce Lightning, drag the button from the Mobile & Lightning Actions palette to the Salesforce Mobile and Lightning Experience Actions section.
In Salesforce Classic, drag the button from the Buttons palette to the Custom Buttons area.
-
Click Save to save the modified page layout.
For help about modifying page layouts, see Managing Pages.
Successful Refund Handling
A successful refund handling with Stripe involves the following steps:
- Since the original payment may have been split into multiple payment balances, JustOn uses the
Transaction Number
of the original payment to create a list of all related payment balances. - The payment balance used to initiate the refund is the first in the list. The other payment balances are sorted by date, with the oldest first.
- A refund balance is created for each payment in the payment list until the refund amount is used up.
- A payment balance is always refunded by a related refund balance with the same amount.
- If the payment balance amount is larger than the remaining refund amount, the payment balance is split.
- The created refund balances are not linked to an invoice. A refund operation does not change the status of an involved invoice.
-
The created refund balances and the related payment balances are locked, applying the reason
Refund via payment provider
. Locked balances are exempt from business processes like balance assignment.Refund balances can, however, be assigned to open credits.
Info
Usually, you cannot refund an amount that is larger than the original payment amount. If the refund amount is still larger than the sum of the available payment balances, JustOn uses an overrefund to indicate a missing payment balance, and creates an additional payment balance to settle the refund amount. Note that the additional payment balance will not be linked to an invoice.
Failed Refunds
A refund via Stripe can fail if the customer's bank or card issuer has been unable to process the operation correctly, for example, if the bank account has been closed or there was a problem with the card. In the rare instance that a refund fails, JustOn creates a payment entry that includes all relevant information about the failed refund.
Example payment entry for a failed refund:
Field | Value |
---|---|
Payment Provider | Stripe |
Transaction No | ch_1ErOvCAL1H03srLS9txxki94 |
Payment Amount | -100,00 |
Last Error | Refund failed: expired_or_canceled_card |
Credit and Refund Workflows
The following sections illustrate likely business use cases that combine credit creation with payment refunds. The examples outline the involved steps and show their key results.
Refunding a payment without creating a credit
(1) Finalize invoice
(2) Register payment
(3) Refund payment
Refunding a registered payment
For additional examples of complete or partial refunds, see Refund Handling Examples.
Refunding a payment with a credit issued before payment receipt
(1) Finalize invoice
(2) Create (partial) credit
(3) Register payment
(4) Refund payment
Refunding a registered payment for a partially cleared (reduced) invoice amount
Refunding a payment with a credit issued after payment receipt
(1) Finalize invoice
(2) Register payment
(3) Create (partial) credit
(4) Refund credited amount
(5) Finalize credit
Refunding a registered payment after creating a (partial) credit
Refunding a payment with a credit issued after refund
(1) Finalize invoice
(2) Register payment
(3) (Partially) refund payment
(4) Create (partial) credit
(5) Finalize credit
Refunding a registered payment before creating a (partial) credit
Refund Handling Examples
The following section summarizes some examples for the successful refund handling, illustrating its behavior.
Completely refund a single payment
Payment balances
Amount | Selected for Refund |
---|---|
-100,00 |
Resulting refund and payment balances
Type | Amount | Locked |
---|---|---|
Payment | -100,00 |
|
Refund | 100,00 |
Partially refund a single payment
Payment balances
Amount | Selected for Refund |
---|---|
-100,00 |
Resulting refund and payment balances after refunding the amount of 25,00:
Type | Amount | Locked |
---|---|---|
Payment | -75,00 |
|
Payment | -25,00 |
|
Refund | 25,00 |
Completely refund a split payment
Payment balances
Amount | Selected for Refund |
---|---|
-75,00 |
|
-25,00 |
Resulting refund and payment balances after refunding the amount of 25,00;
Type | Amount | Locked |
---|---|---|
Payment | -75,00 |
|
Payment | -25,00 |
|
Refund | 25,00 |
Partially refund a split payment
Payment balances
Amount | Selected for Refund |
---|---|
-75,00 |
|
-25,00 |
Resulting refund and payment balances after refunding the amount of 40,00;
Type | Amount | Locked |
---|---|---|
Payment | -60,00 |
|
Payment | -15,00 |
|
Payment | -25,00 |
|
Refund | 25,00 |
|
Refund | 15,00 |
Refund amount is larger than original payment amount
Payment balances
Amount | Selected for Refund |
---|---|
-75,00 |
Resulting refund and payment balances after refunding the amount of 100,00;
Type | Amount | Locked |
---|---|---|
Payment | -75,00 |
|
Payment | -25,00 |
|
Refund | 75,00 |
|
Refund | 25,00 |