Mollie
The JustOn Self-Service Extension can integrate with Mollie as a payment provider. It uses Mollie Checkout and Mollie Webhooks to implement the payment procedure.
Be aware of the following specifics:
- The Checkout page supports all payment methods that are enabled in the Mollie Dashboard. Payment methods that are not allowed for a given payment operation, like due to an amount limit or an unsupported currency, are not shown.
- JustOn passes the same language code that is used for the payment page to Mollie Checkout. Mollie supports a subset of ISO 15897 locales. If the current language is not supported, the language code is not passed to Mollie.
Future payments with Mollie
When using future payments, the invoice field Email Contact
must be set.
The payment will fail if future payment is selected but the field Email Contact
is not set on the invoice. In this case, JustOn creates a Payment Entry record that holds the information about the failure in the field Provider Specific Data
.
With the first executed payment, the Mollie integration creates a Mollie customer. The ID of the customer is stored in the contact field Mollie Customer Id
. The Mollie customer ID will be used for all subsequent payments. This way, a payment is always assigned to the same Mollie customer. If you delete the customer in the Mollie Dashboard, JustOn automatically creates a new customer when future payment is selected.
JustOn uses the following billing information fields on the invoice when creating a Mollie customer for future payments: Email First Name
, Email Last Name
, Email
.
JustOn recommends to make these fields editable and mandatory. This forces the user to specify missing data.
This data is passed to Mollie Checkout. Its application depends on the selected payment method. For example, Mollie uses the email address with bank transfers to send payment information to the customer.
If you intend to use direct debit for recurring payments, you must enable at least two payment methods in Mollie:
- For the first payment, enable one of the first payment methods that create a direct debit mandate, currently including Bancontact, Belfius Payment Button, EPS, Giropay, iDEAL, ING Home'Pay, KBC/CBC Payment Button and SOFORT Banking. For details, see Setting up the first payment in the Mollie documentation.
- For the subsequent payments, enable SEPA Direct Debit.
Mollie webhook URL
The JustOn Self-Service Extension automatically builds the webhook URL to be called. It is transferred with every payment request.
The URL is composed of
- the secure site URL of your Salesforce Site,
- the path
/services/apexrest/ONBSE1/MollieWebhook
, and - your Mollie profile ID, like
https://<instance>.secure.force.com/services/apexrest/ONBSE1/MollieWebhook/<profileID>
or, if enhanced domains are enabled in your org, like
https://<mydomain>.my.salesforce-sites.com/services/apexrest/ONBSE1/MollieWebhook/<profileID>
The payment records in your Mollie Dashboard show the webhook URL.
Info
As opposed to the usual payment workflow (see Payment Page), the Mollie integration creates a payment balance, setting the corresponding invoice Paid
, upon issuing the payment request without waiting for a success notification. If the payment processing fails, the Mollie integration triggers JustOn to delete the payment balance and to set the invoice Open
again.
Setting up Mollie as a payment provider involves the following tasks:
- Creating a Mollie account
- Enabling the Mollie webhook handler class
- Configuring the Mollie integration
Creating Mollie Account
In order to use Mollie as a payment provider, you need a valid Mollie account. To create it, navigate to the Mollie website, click Sign up and follow Mollie's instructions.
To configure the integration with the JustOn Self-Service Extension, you need the API key and Profile ID. Find these values in your Mollie Dashboard.
Enabling Mollie Webhook Handler
As part of the payment-specific site setup, you must enable the specific Apex class ONBSE1.MollieWebhookHandler for your site in order to completely support the Mollie 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.MollieWebhookHandler to the Enabled Apex Classes list.
- Click Save.
Configuring Mollie Integration
Note
The Mollie integration requires the Visualforce page ONBSE1.PaymentMollie added to your site. For details, see Assigning Payment-Specific Pages.
To configure the Mollie 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 API Key The secret API key of the test or live environment. Can be obtained from the Mollie profile. Profile ID The Mollie profile ID. A payment provider setting with this profile ID must exist. Site Hostname The secure site URL of your Salesforce Site without trailing slash, like https://<instance>.secure.force.com
orhttps://<mydomain>.my.salesforce-sites.com
.
Make sure to use the site URL, not the domain URL.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 Mollie 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.When editing existing configurations,
API Key
andProfile ID
values are not displayed. The values remain unchanged as long as you leave the corresponding fields empty. -
Click Add for new settings or, respectively, Save for existing settings.
Using Future Payments Without Initial Payment
Your business may require to create payment balances with Mollie during the payment run without an initial payment. This requires payment instruments to be available.
Info
The payment instrument creation is project-specific and therefore not covered with this documentation. Generally, you can
- Create payment instruments manually,
- Use automation tools like Salesforce processes to have payment instruments created automatically, or
- Use a Salesforce API (REST, SOAP, Dataloader, Apex) to insert Payment Instrument records
The following payment instrument fields must be set:
Field Label | API Name | Description | Value |
---|---|---|---|
Account | ONB2__Account__c | The associated Salesforce account ID of this payment instrument. | Salesforce account ID, like 0011t000007Lk1xAAC |
Payment Provider | ONB2__PaymentProvider__c | The payment provider that handles this payment instrument. | Mollie |
Provider Specific Data | ONB2__ProviderSpecificData__c | JSON encoded values needed for the specific payment provider. | Mollie customer ID Mollie mandate ID Mollie profile ID |
Type | ONB2__Type__c | The payment instrument type. | Mollie |
The field Provider Specific Data
must contain the following JSON keys:
Key | Description |
---|---|
customerId | The ID of the customer for whom the payment is being created. |
mandateId | The ID of a specific mandate must be supplied to indicate which of the consumer's accounts are to be credited. |
profileId | The Mollie profile ID. A payment provider setting with this profile ID must exist. |
Example for Provider Specific Data
:
{
"customerId": "cst_kEn1PlbGa",
"mandateId": "mdt_h3gAaD5zP",
"profileId": "pfl_beqeERw3jM"
}
Mollie Refund Handling
Businesses can use the Mollie Dashboard to refund a payment made via Mollie. 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.
Refund or chargeback?
Some use cases require merchants or service providers to return money to their customers. Depending on who initiates the return and why, this operation is either a refund or a chargeback.
- Refund: Suppliers refund a received payment – partially or completely – usually as the result of an invoice correction involving cancellations or credits.
- Chargeback: In the course of a dispute, for example, a customer may reject a debit from their bank account that is based on a direct debit, which produces a chargeback on the supplier's bank account.
Successful Refund Handling
A successful refund handling with Mollie 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 Mollie 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 | Mollie |
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 |
Mollie Chargeback Handling
A customer may reject a debit from their bank account that is based on a direct debit, which produces a chargeback on the supplier's bank account.
Refund or chargeback?
Some use cases require merchants or service providers to return money to their customers. Depending on who initiates the return and why, this operation is either a refund or a chargeback.
- Refund: Suppliers refund a received payment – partially or completely – usually as the result of an invoice correction involving cancellations or credits.
- Chargeback: In the course of a dispute, for example, a customer may reject a debit from their bank account that is based on a direct debit, which produces a chargeback on the supplier's bank account.
For payments made via Mollie, JustOn can handle ordered chargebacks. It directly returns the corresponding payment originally made via the payment page of the JustOn Self-Service Extension.
Doing so
- Creates a balance of the type
Chargeback
with the reversed amount of the original payment balance on the invoice, - Relates the original payment balance with the chargeback balance,
- With the payment balance and the chargeback balance offsetting each other, resets the original invoice to the status
Open
.
Example: Complete chargeback
(1) Original invoice balances → invoice is Paid
Type | Amount |
---|---|
Invoice | 100,00 |
Payment | -100,00 |
(2) Resulting balances after executing a complete chargeback:
Type | Amount | Notes |
---|---|---|
Invoice | 100,00 | |
Payment | -100,00 | unassigned from the invoice |
Chargeback | 100,00 | not assigned to the invoice |
The invoice is reset Open
with an open amount of 100,00.
Example: Partial chargeback
(1) Original invoice balances → invoice is Paid
Type | Amount |
---|---|
Invoice | 100,00 |
Payment | -100,00 |
(2) Resulting balances after executing a partial chargeback of 25,00:
Type | Amount | Notes |
---|---|---|
Invoice | 100,00 | |
Payment | -75,00 | assigned to the invoice |
Payment | -25,00 | unassigned from the invoice |
Chargeback | 25,00 | not assigned to the invoice |
The invoice is reset Open
with an open amount of 25,00.