Skip to main content

Frequently asked questions

Here are the Report API FAQs. See the Report API guide for all the details.

For general information and questions, please check in the Knowledge base.

What are the benefits of the Report API over the SFTP service?​

The SFTP Report (deprecated) lets merchants and partners download settlement files by SFTP.

The Report API has several benefits over the SFTP service:

  • Accounting partners have one set of API keys for all their merchants: Accounting keys. The accounting keys can not be used to make payments.
  • Merchant can easily give access to an accounting partner on portal.vippsmobilepay.com with no coding by the merchant or the accounting partner.
    • The SFTP service required each merchant to enter the accounting partner's SSH key. Some merchants even shared their API keys, which enable the accounting partner to make payments, which is not allowed.
  • Data can be retrieved at any time, for any time period.
    • The SFTP service only offered daily data: One file per day.
  • Data is available regardless of whether the balance is positive or negative, so even if there have only been refunds, there will be data available.
    • The SFTP service only provided settlement data when the balance was positive.
  • It is possible to retrieve data for more than one day in a request, for example for an entire weekend, week, or month.
    • The SFTP service only provided one file per day.
  • The data is in JSON format, making it easy to use in different ways.
    • The SFTP service offered XML, XSLX, CSV and PDF, but most users now want JSON.

How to get access​

How can a merchant or partner get access to the API?​

See: Authenticating to the Report API.

Which API keys give access to the API?​

See: Authenticating to the Report API.

Why does a merchant need to log in on portal.vippsmobilepay.com to select accounting partner?​

An accounting partner gets access to the merchant's sales unit's data. We require the merchant to log in securely on portal.vippsmobilepay.com to provide this access and consent to sharing the data with the accounting partner.

Can a partner specify the accounting partner for a sales unit?​

No, please see Why does a merchant need to log in on portal.vippsmobilepay.com to select accounting partner?

Can one sales unit have multiple accounting partners?​

Yes. One sales unit may give access to several accounting partners, and the "accounting partner" may be a CRM systems vendor or something other than a pure accounting vendor.

As long as the external party has applied to become a partner, and is visible in the list of accounting partners, the merchant may give it access to one or more sales units.

Is the Report API available for the test environment?​

No. The test environment does not have the backend systems necessary to offer the Report API.

The only way to test the Report API is in the production environment.

Since the Report API is read-only, and the overall logic is very simple (first you ask for data, then you receive that data), developing and testing in the production environment is straight-forward.

Implementing the Report API in the test environment is a big effort, as there are no settlements being made in that environment. The data that the Report API needs is simply not available. It is unlikely that we'll be able to prioritize this over other development efforts.

What information can I get hold of?​

The Report API provides information about all payments that are processed by Vipps MobilePay.

Right now the only data that is available is the same data that is already available in the settlement reports on portal.vippsmobilepay.com, or on SFTP report (deprecated).

Match the reference on the transfer from your bank statement with the reference in the Report API. When you retrieve a series of payments (made by users in the app) with GET:/report/v2/ledgers/{ledgerId}/{topic}/feed in the Report API, each of those payments' pspReference is the reference for the bank payout.

The only difference is that the data can be fetched over a more modern REST API. We aim to provide more information through this API in the future.

tip
info

The Report API can only be used to fetch data for sales units that have API access. Therefore, it can't be used with Vippsnummer (a.k.a., Shopping Basket and Open Amount) sales units, because these don't have an API interface. See: Authenticating to the Report API.

See: A report for each payout?

Can I get data for "shopping basket"?​

No. The data about products bought with Shopping Basket is not available in the Report API.

Can I get data about order lines?​

No. The data about order lines is not available in the Report API, but is available in the Order Management API, if the data has previously been sent using that API.

Can I get data for payments processed by a PSP using the PSP API?​

No. The API does not provide data for payments made with the PSP API, as those payments are processed by the PSP, and the PSP then sends information to us about the status of the payment. The settlement data, etc. must be retrieved from the PSP.

See: PSP API: How can I get details for a payment?

How can I get the details for each payment?​

The Report API is primarily for accounting partners who will use the API to integrate with their accounting systems, allowing them to provide the accounting information to their merchants.

The Report API does provide information about individual payments made by users in the app, in the aggregated response to GET:/report/v2/ledgers/{ledgerId}/{topic}/feed. There is no dedicated endpoint to retrieve details for payments one-by-one, specified by ID, etc.

The API used to initiate the payment may be used to get the details for the payment. See:

If you use the Order Management API you can retrieve details from there too: Fetch Category and Receipt. This includes all the receipt details with all the order lines.

The Report API may be extended to contain more information later, and this FAQ will be updated if there are any changes. There are no specific plans to do this yet.

How often is data made available in the Report API?​

This can vary, and we can not guarantee specific times.

See: Settlements: Settlement flow.

Can I get real-time data?​

In Denmark and Finland: Yes. There may be a delay of 5-30 seconds. To receive real-time data, please use the endpoint GET/report/v2/ledgers/{ledgerId}/{topic}/feed. The endpoint for retrieving daily reports only does so after the end of the day.

In Norway: No. The Report API may be extended to contain real-time information later, and this FAQ will be updated if there are any changes.

How can I get a sum of all payments made on one date or for a date interval?​

The Report API does not provide a sum of payments. It is possible to add together all the amounts for all payments in the list of payments in the response from GET/report/v2/ledgers/{ledgerId}/{topic}/feed (using funds for topic).

The API used to initiate the payment may be used to get the details for the payment, and if the payment was successful:

The Report API may be extended to contain more information later, and this FAQ will be updated if there are any changes. There are no specific plans to do this yet.

See How can I get the details for each payment?

How can I get the data for VM-number sales units with shopping basket?​

This is only available on portal.vippsmobilepay.com, but we may extend the Report API top include more details. There are no specific plans to do this yet.

How can I get the details for my shopping basket products and their different VAT rates?​

This is only available on portal.vippsmobilepay.com, but we may extend the Report API top include more details. There are no specific plans to do this yet.

How can I get details about my customers' tax deductions?​

This is used for fundraising, where users may give consent to share their national identity number and automatically get tax deductions.

This is only available on portal.vippsmobilepay.com, but we may extend the Report API top include more details. There are no specific plans to do this yet.

How do I get the settlements for multiple MSNs in the same ledger?​

Joint settlement for multiple MSNs is supported, and may be relevant in cases such as:

  • You are changing the technical integration and getting a new MSN for this purpose, but you do not want to disrupt the settlement series.
  • You are launching a Point of Sale system in many physical distinct stores that should have different MSNs, but want to have combined settlements for these.

In practice, this feature is little used in a few pilot cases, and configuration is not yet generally available. However, accounting partners should take into account that this feature could see more use in the future when integrations are developed.

If a ledger is used for two MSN: MSN 1 and MSN 2. What happens when MSN 2 gets its own ledger?​

Once a transaction has appeared on a ledger, it belongs to that ledger forever.

When an MSN is moved to another ledger, it means that future transactions will appear on the new ledger. The old transactions appear on the old ledger, since they contributed to joint settlement payouts of both MSN 1 and MSN 2.

Can a merchant find the Ledger ID for an MSN on portal.vippsmobilepay.com?​

No. For now, the only way to get the Ledger ID is to call GET:settlement/v1/ledgers.

The Ledger ID does not (in general) change, so you may store it in configuration in the same way that you store the MSN. We may add display of the Ledger ID on portal.vippsmobilepay.com in the future.

Bank payouts​

What text is shown for the payouts in my bank?​

Denmark and Finland​

In Denmark and Finland, the default format is 02{Recipient:08}001{DD}{MM}{YY}{C}.

The payout text can be up to 20 characters, and include letters, digits or/and the following variables:

  • {YY} or {YYYY} for year, {MM} for month, {DD} for day.
  • {Recipient} for sales unit number (five to eight digits)
  • {Recipient:08} for sales unit number, zero-padded to eight digits
  • {C} at the end for a control digit, or checksum.

Merchants can change the format of the text on portal.vippsmobilepay.com, on the details page for the sales unit, where the details of the fields are also explained.

note

The checksum in the reference number is computed using the Finnish control digit standard and is present for compatibility with specific Finnish banking/accounting systems. The Finnish control digit is also used in Denmark, but serves no purpose there. When using this API, the reference number and checksum are managed electronically and there is no need for you to implement the checksum algorithm. For details: Finance Finland: The Finnish reference number.

Norway​

In Norway, the reference format is: Utb. {Recipient} Vippsnr {PayoutNumber}, for example: Utb. 2000810 Vippsnr 117703. This format is not configurable.

note

While these are the references we send to the banks, we have no control over or information about how banks make use of these in their reports online or in print.

How can I get the details for a payment I see in my bank?​

The payment to the merchant's bank account should be considered a balance transfer, not a sum of payments. We recommend to reconcile the payments in the way described in the API guide. The details of the funds that are transferred is available using either of these endpoints, where {topic} is funds:

The result is all changes to your ledger balance. Within these entries, the ones with entryType set to payout-scheduled describe that we have done a transfer to your bank account. In Denmark and Finland, the reference field of the payout-scheduled entry contains the same reference as we put on the payment to the merchant's bank account. (We hope to provide this capability in Norway as well soon.)

The following example shows a payout-scheduled entry representing 8000 DKK being paid out to the merchant's bank account:

    {
      "pspReference": "453243-2000002",
      "time": "2024-04-05T22:00:00Z",
      "ledgerDate": "2024-04-05",
      "entryType": "payout-scheduled",
      "reference": "02023452430010504243",
      "currency": "DKK",
      "amount": -800000,
      "recipientHandle": null,
      "balanceAfter": 200000,
      "balanceBefore": 1000000
    }
  • The reference field, in this case 02023452430010504243, can be found in the merchant's bank transcript once the payment has been completed.
  • The entry is named payout-scheduled because this represents a decision to pay the money out. It is not a confirmation that payout has been done yet. See Payout delay for more details.
  • While this balance may correspond to the sum of a given set of sales, exceptions to this can occur. In the sample above this can be seen as the total on the ledger is 10 000 DKK; but still only 8 000 DKK was paid out (this could for instance be due to the configuration of a rolling reserve of 2 000 DKK).

How can I extend my reported data with the users name, masked phone number and the text that the user entered when paying?​

See: GDPR data.

See also: Knowledge base: Why are the customer names not shown on the transaction overview?

Common problems​

Why do I not get the ledgers I expect?​

If you, as an accounting partner, make a request to GET:/settlement/v1/ledgers, but don't get a response containing the ledgers you expect, the most common reason is that the merchant has not granted you access. The merchant needs to give access to an accounting partner. We need the consent of the merchant in order to grant you access to their data, so they need to perform this step.

Why do I get an empty list in response when calling one of the endpoints?​

If there is no settlement data, you will get an empty list from GET:/report/v2/ledgers/{ledgerId}/{topic}/feed. The same applies to other endpoints: If there is no data, you may get an empty list. This is not an error.

If you keep getting an empty list in a response where you expect data to be available, you should first check these things:

  • Check if your query-parameters are correct. Are you filtering on the correct date?
  • Do you have access to the resource you are trying to retrieve? If you are trying to retrieve the transactions connected to a ledger you do not have access to, you will be given an empty list. The merchant needs to give access to an accounting partner.
  • If you think there is an error in the data provided by the Report API: Log in on portal.vippsmobilepay.com and manually check the settlement data there.

Why is recipientHandle null?​

This can be for two reasons:

  • Not all entry types have this property. For instance payout-scheduled and fees-retained do not have it.
  • For older data (from before 2022), some payment metadata is missing from our API, including recipientHandle.

Why is tryLater returned as true for many days in Norway?​

For Denmark and Finland, data should be available within a few hours after midnight and tryLater will be set to false.

Currently, for Norwegian data, the way Report API works internally is that new data is made available only when a settlement payout is done to the merchant (a payment to the merchant's bank account), or, in rare cases, an invoice is sent for negative balance.

There are some cases this can lead to tryLater being true for a long time:

  • Merchants on monthly settlements will have tryLater set to true for all days of the month, until after the end of the month
  • Merchants can get negative balance if they have more refunds than captures. The balance can stay negative until Vipps MobilePay sends an invoice (this delay can be 60 days or more).
  • If merchants do not have any traffic at all, tryLater will then be true until there is again traffic.

To successfully deal with this case:

  • Internally in your system, track a lastLedgerDate for each ledgerId
    • Importantly, this will be different for each ledgerId
  • Each day, in a loop, ask for data from lastLedgerDate + 1 and until today
  • Gracefully handle the case where tryLater is true by simply waiting until the next day

At some point in the future, Norway should work in the same way as Denmark and Finland, but we have no estimates for when this will happen yet.

Help us improve our documentation

Did you find what you were looking for?