FinDock e-mandates

ย ย ย FinDock e-mandates is in beta.

FinDock e-mandates is an optional paid feature that enables organizations to leverage the growing popularity of electronic identification (eID).

For many payment methods, payer authorization requires an explicit signature from the payer. Through the e-mandate service, FinDock offers a simple, seamless process for creating and storing digitally signed electronic mandates (e-mandates).

Availability

What counts as a legally binding eID varies from country to country, and payment method to payment method.

Currently, the FinDock e-mandate feature supports Autogiro direct debit payments in Sweden where the eID for online mandate signup uses the payer's BankID app for verification.

Prerequisites

  • FinDock contract includes the e-mandate feature

  • FinDock with the FinDock for Sweden fully configured

  • A Bankgirot contract allowing online mandate signup

Permissions for e-mandates

Make sure that your integration user is assigned the FinDock Integration User permission set group. If you are using custom permission set groups, ensure the Nordic permission sets are included.

ย ย ย Extra attention required for Visualforce permissions.

The e-mandate PDF generation uses Visualforce with the Apex class NPFF.MandatePDF. There are two ways to handle this depending on your integration user profile:

  • For the API-only user profile, enable the profile in the MandatePDF Visualforce page security settings.
  • For other user profiles, add NPFF.MandatePDF to the Apex Class Access settings of a permission set assigned to the user.

How the e-mandate service works

The e-mandate service can be initiated for direct debit payments accepted online through Giving Pages or a custom front-end integrated to the Payment API.

FinDock e-mandate flow

  • Step 1 - When a new payment is set up, FinDock creates a mandate for the one-time installment or recurring payment and sets the status to Pending signature while the online signature process proceeds.
  • Step 2 - The payer is redirected to the FinDock e-mandate service and prompted to sign the mandate with the BankID app.
  • Step 3 - The payer uses the BankID app to digitally sign the mandate. (This can be done on the same device or another device by scanning a QR code.)
  • Step 4 & 5 - FinDock generates and stores a digitally signed PDF of the payerโ€™s authorization on a Mandate record and sets the record status to Pending registration.

Mandates with status Pending registration are picked up by the next mandate schedule run and sent to Bankgirot for registration. Once the mandate schedule is completed and the records sent to Bankgirot for registration, the mandate status is changed to Pending registration acceptance.

When FinDock receives confirmation of the registration, the mandate status is set to Success and the record is marked as active (Is Active set to true). At this point, payments against the mandate can be collected.

Configure e-mandate service

Signed mandates are needed for both one-time and recurring Autogiro payments. Once the e-mandate feature is activated, you need to ensure the company information fields on the Target configuration, like city, street and postal code, are correctly completed. These fields are required for e-mandates. They are used on the generated e-mandate form and must be present for the signed e-mandate to be compliant.

Customize e-mandate PDF

FinDock uses Visualforce to generate a PDF of the signed e-mandate. You can replace the default template with your own Visualforce template to add custom terms, adjust branding, and so forth.

The template is defined under the general settings for the FinDock for Sweden processor. There you can enter the name of your page in the Custom e-mandate PDF setting to direct FinDock to use the custom template.

The available fields for custom e-mandate PDFs are outlined in the table below. You can use the baseline page at FinDock Labs to get started.

Field NameField ReferenceDescription
signDate{!signDate}Signature date provided by eID service
amount{!amount}Amount of the one-time or recurring payment
frequency{!frequency}Frequency of the recurring payment
startDate{!startDate}Start date of the recurring payment
payerSSN{!payerSSN}Payer's civic identity number (personnummer)
payername{!payerName}Payer's name from the payment intent message
payerIpaddress{!payerIpaddress}Signature IP address provided by eID service
payerSignatureHash{!payerSignatureHash}Unique signature hash generated by the eID service
payerBankAccount{!payerBankAccount}Bank account from the payer's Payment Profile record
payerBranchCode{!payerBranchCode}Bank branch code (clearing number) from the payer's Payment Profile record
payerBankName{!payerBankName}Bank name from the payer's Payment Profile record
payerNumber{!payerNumber}Mandate Id from the payer's Mandate record for the payment intent
payeeBankgiroNumber{!payeeBankgiroNumber}Bankgirot account number of your organization from the target used for e-mandates
payeeOrganisationNumber{!payeeOrganisationNumber}Business registration number from the target used for e-mandates
payeeName{!payeeName}Company name from the target used for e-mandates
payeeStreet{!payeeStreet}Street from the target used for e-mandates
payeeCity{!payeeCity}City from the target used for e-mandates
payeePostalCode{!payeePostalCode}Postal code from the target used for e-mandates

Special testing considerations

When testing the e-mandate service, you should use a target that is configured as a test account. In addition, you need to set up a special test variant of the BankID app.

To set up a BankID app for testing:

  1. Download the BankID security app from your respective mobile app store.
  2. Configure the app to use the BankID testing environment as instructed here.
  3. Create a test account according to the test BankID instructions, using the "order personal code" option to register.

Once the test app is configured, you can start testing e-mandates, for example, by setting up a Giving Page as described in the next section.

E-mandate service with Giving Pages and PayLinks

For orgs with FinDock for Sweden and the e-mandate feature activated, e-mandates are a built-in step for new Autogiro payments made through Giving Pages and PayLinks.

When configuring the Payment Form component, you see as part of the payment methods configuration an additional required parameter for the Autogiro method with FinDock as processor. The appDevice parameter gives payers three signature options: use the BankID app on their current device, use the app on another device, or chose to provide a signature on paper.

Autogiro payment method parameters

New mandates get the status Pending Digital Signature or Pending Paper Signature depending on the payer's selection.

E-mandate service via Payment API

For custom front-end integrations to the Payment API, it is important to ensure the paymentIntent message includes all required parameters for Autogiro. If FinDock e-mandates are used, this means including the required appDevice parameter amongst others (see above).

Mandate archiving

Autogiro mandates need to be archived and available to payers on request as outlined in the Bankgirot user manual. The digitally signed PDFs stored on Mandate records in Salesforce can service as your archive if data retention and access policies permit.

Was this page helpful?