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.
- 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 Name | Field Reference | Description |
---|---|---|
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:
- Download the BankID security app from your respective mobile app store.
- Configure the app to use the BankID testing environment as instructed here.
- 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.
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.