Configuring Vipps
The Vipps mobile payment application is used throughout Norway. FinDock integrates with the Vipps service to initiate and collect payments.
When you sign up as a new Vipps merchant, select FinDock as your partner in the signup process for "Vipps på nett." The FinDock integration does not support direct capture payments.
Multi-merchant | Multi-currency |
---|---|
Payment Method | One-time | Recurring | Refunds |
---|---|---|---|
Vipps |
Prerequisites
- FinDock is installed and configured.
- WebHub is connected.
- You have a Vipps merchant account.
The FinDock integration with Vipps does not support direct capture payments.
Install the Vipps extension
Follow the standard procedure for installing payment processors to add the Vipps payment extension and activate the Vipps payment method.
Check and assign the required permissions. If you are using custom permission set groups, ensure the package-specific permission sets are assigned.
Configure Vipps extension
To up the Vipps extension is fairly straightforward. You just need to copy some details from your Vipps portal to the FinDock extension setup. We recommend having both the Vipps portal and FinDock open in different browser tabs so you can copy directly from one to the other.
Before you begin, determine if you are setting up a production or test environment. If you are testing, select the Test option in the portal before copying any information.
To configure Vipps for FinDock:
- Launch the FinDock app and click the FinDock Setup tab.
- Go to Payment Processors & Methods.
- Under Installed Processors, click the Vipps processor entry.
- Click Add account.
- For the merchant account you want to integrate, add the following details:
- Merchant Account Name: Enter a name for your Swish target (merchant account)
- Default Account: Enable on the account you want used when no account is specified in a payment intent call to the Payment API
- Test Account: Enable if you are setting up a test environment
- Merchant Serial Number: MSN from Vipps portal for the given account
- Client Key: API client key from Vipps portal
- Client Secret: API client secret from Vipps portal
- Ocp-Apim-Subscription-Key: API Subscription key from Vipps Portal (either primary or secondary)
- Product Name: Default name of Recurring Agreements setup in Vipps; can be overwritten via the Payment API
- Merchant Agreement Url: Default URL for setting up recurring agreements. Visible to end users in their Vipps app. Can be overwritten via the Payment API
- Retry Days: How many days Vipps should retry a failed recurring payment. Recommended to be at least 3, to ensure success.
- Click Save.
Reconciling Vipps Payments
Vipps payments can originate from different sources. Next to one-time and recurring online payments, it is also possible to transfer money directly to a merchant via a Vipps number.
FinDock reconciles all payments to your Vipps account using a daily, automated import of transactions from your Vipps ledger. These transactions contain refunds, confirmed payments and payouts from Vipps.
To enable this reconciliation, you need to adjust the Vipps extension general settings.
- Launch the FinDock app and click the FinDock Setup tab.
- Go to Payment Processors & Methods.
- Under Installed Processors, click the Vipps processor entry.
- Under General Settings, toggle on Enable Reconciliation Incoming Payments.
- Add a date for Initial Ledger Date to tell FinDock from which date to start fetching ledger entries.
- Click Save.
Take particular care with defining the Initial Ledger Date. From that date onwards, FinDock starts fetching transaction data from your [Vipps ledger]. If you have previously used some other integration setup, this date can be considered the official switchover to FinDock handling of Vipps payments.
Once these settings are in place, FinDock begins process Vipps ledger entries as follows:
- Daily heartbeat job checks if there are payments that need to be retrieved from Vipps.
- If there are new payments, FinDock retrieves all new payments by creating a message record for each retrieval job and an individual message for each transaction.
- Individual Inbound Reports are created to process the Vipps payments and reconcile them via Guided Matching against installments.
Currently the Vipps Reporting API does not retrieve payments made via Vipps numbers. If you want to process these payments, you can use Guided Matching to reconcile them.
Vipps data mapping
The table below summarizes the payment data FinDock captures to manage Vipps transactions.
Vipps data | Object | Field | Value |
---|---|---|---|
N/A | Payment Profile | Record Type | Wallet |
Vipps | Payment Profile | Wallet Type | Vipps |
Agreement ID | Mandate | Mandate Id | E.g. agr_123456 |
Product Name | N/A | Product Name | API parameter ProductName |
Bank Statement Description | Installment | Product | API parameter description |
Order ID | Installment | Payment Reference | E.g. pi-123456789 |
Transaction Text | Installment | Bank Statement Description | E.g. Invoice #1234 |
Vipps mobile phone number handling
With the Vipps payment method, the payer’s mobile phone number plays a central role in the transaction.
When using Vipps through FinDock Giving Pages or Paylinks, you can:
- Use a URL query to pre-fill the payment form with a phone number from Contact or Account. If the payer enters a different number, FinDock uses the value entered by the payer.
- Set the default value of the API Parameter using default values. This enables you to use any phone number field to send to Vipps.
When using Vipps through a custom front-end for the FinDock Payment API:
- Make the phone number API parameter visible for the payer. FinDock uses the value entered by the payer in the Vipps redirect.
Vipps can only be used with Norwegian Krone.
Managing a recurring agreement
When setting up a recurring payment in Vipps, the payer will see the agreement in the Vipps app. If a payer wants to cancel their agreement, it is highly recommended to also cancel the agreement in Vipps. FinDock allows you to integrate canceling the Vipps Agreement into your own processes via an Invocable Action. For more information on how an invocable action can be used, see the Salesforce documentation.
The Cancel Vipps Agreement invocable action is an Apex Action with 2 input parameters. You can either supply the Apex action with a Mandate Record ID or the Vipps Agreement ID.
You can use the following combination to cancel a Vipps agreement:
- In a Flow, for instance, when cancelling recurring payments: Apex Action (recommended): use
Cancel Vipps Agreement
. This is the recommended way of integrating with a Flow. - Use the Global class.
Using Vipps Cancel Agreement in a Flow
To use the invocable in a Flow:
- In your Flow add an Apex Action.
- Search for
Cancel Vipps Agreement
Under Set Input Values, toggle the parameters to “Include”. Note: Please make sure to either toggle Mandate Id OR Agreement Id depending on what input variable you wish to use. - Either manually assign your own variables to the output parameters under “Advanced” or use the default
[api_name_of_your_action].isvalid
and[api_name_of_your_action].message
.
Setting | Description | Example values | API name |
---|---|---|---|
Is Success | Whether the cancellation performed in Vipps was successful | True or False | [your_apex_action].isSucces |
Message | Return message from Vipps if available | Agreement is already cancelled | [your_apex_action].message |
When executed, the Apex Action sets two variables that indicate whether the provided combination was valid or not. If the combination is not valid, a message with more information is returned if available. If the cancellation is successful, FinDock will also deactivate the Mandate and set the status to cancelled.
Testing with the Payment API
You can use the following example messages to test if the Vipps configuration is working as expected.
{
"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": "Vipps",
"Processor": "FinDock-Vipps",
"Parameters": {
"mobileNumber": "[Vippstestnumber]"
}
}
}