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.vipps.no 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.vipps.no 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.vipps.no 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.vipps.no 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.vipps.no, 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.

Please note:

  • The Report API has data from May 2020 for payments made on the Vipps platform.
  • The "Transactions" page on portal.vipps.no has the same limitation.
  • The "Reports" page on portal.vipps.no has all data.
  • For payments made with the Mobilepay APIs (and façades): See the Reporting API to Report API migration guide details.

Important: It is not possible to use the Report API to retrieve data for Vippsnummer or sales units. The Report API can only be used to fetch data for sales units that have API access (which Vippsnummer sales units do not have). See: Authenticating to the Report API.

See: A report for each payout?

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.

Can I get realtime data?

No. 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.

Why are the users' names, transaction texts, etc. not available in the Report API?

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 reports on portal.vipps.no provide more details. The users' names, transaction texts and other information may be regulated by GDPR and therefore require consent from the merchant. This consent may be given on portal.vipps.no, but not when using the Report API.

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 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.vipps.no, 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.vipps.no, 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.vipps.no, 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.vipps.no?

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.vipps.no in the future.

Bank payouts

What text is shown for the payouts in my bank?

We send text on this format to all banks: Utb. <settlement_number> Vippsnr <serial_no>.

Example: Utb. 2000810 Vippsnr 117703.

We have no control over, or information about, how banks handle this on their side, or how it is displayed in their reports online or in print.

The file format used to transfer information to the bank is the ISO 20022 PAIN (PAyment INitiation) format, which - among other things - has a limit of 35 characters for the payment text.

Where can I find the settlement ID?

The payout corresponds to the SettlementID from the XML files in the SFTP report (deprecated).

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

Please note: The payout from Vipps MobilePay to the merchant is the balance at the time of the payout. The sum in the payout, which is what the merchant sees in the bank, does not contain specific payments - it is simply the balance at the time the payout was made.

The Report API is designed to provide updated data independently of the bank payouts. There are several reasons for this, including:

  1. A merchant can have a negative balance and not get settlement payouts for a long time. Periodic checks of settlements would thus not make sense until the merchant has a positive again.
  2. Merchants have different risk profiles (or could have at least). If we deemed that we would hold back some of the balance from payouts to an airline company. Let's say they sell three tickets at 5000 NOK each, for a sum of 15,000 NOK. We then change their risk profile for the merchant, saying we need to hold back 7500 NOK, and then the settlement runs. We will then pay out only 7500 NOK of the 15,000 NOK (if there are no fees). Now: What captures will then be part of that settlement? It's simply not possible to say.
  3. We may, in rare cases, manually correct payouts.

The payout details for each payment can be found with these endpoints, where {topic} is funds:

Examples:

  • GET:/report/v2/ledgers/12345/dates/2023-31-12
  • GET:/report/v2/ledgers/12345/funds/feed

The response will contain information similar to this for each payment:

"items":[
{
"pspReference":"3343121302",
"time":"2020-10-05T10:21:54.141089+0200",
"ledgerDate":"2020-10-05",
"entryType":"refund",
"reference":"acme-shop-123-order123abc",
"currency":"NOK",
"amount":49900,
"balanceBefore":49900,
"balanceAfter":49900,
"recipientHandle":"NO:123455"
}
]

The pspReference is the same as the settlement ID shown in the bank.

Common problems

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

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

  • Check if your query-parameters is 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

Why is recipientHandle null?

This can be for two reasons:

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

Help us improve our documentation

Did you find what you were looking for?