Skip to main content

API guide

tip

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. Accounting partners use their accounting keys, and are not allowed to use the merchant's own API keys. Merchants can then simply give access to the accounting partner, without doing any development themselves.

The Report API provides accounting partners you with information about their merchant's payments. It's used to aggregate information across the API platform, and it can contain data for many payments at once.

If you are interested in becoming an accounting partner: See Become our partner and fill out the form there.

note

The information fetched from the Report API is asynchronous and trailing behind the other APIs. It is usually behind by a second or so, but if there are operational problems, it could, in the worst case, be behind by several hours. Therefore, you should always use other Vipps MobilePay APIs as the source of truth for the status of an operation.

Overview of the settlement process

Merchants using Vipps MobilePay receive the money for their sales in bulk bank transfers (settlements), usually one per day. It is therefore necessary to download a specification reports that explains the bulk bank transfer, so it can be correctly filed in the merchant's accounting system. Such reports can be fetched either on portal.vippsmobilepay.com or by using this API.

Usually, you will wish to implement a reconciliation process, where you download a report from Vipps MobilePay each day, and check that contents of the report match the data you have on your own side. We recommended that you do this by matching per transaction on transaction IDs.

This guide will focus on using this API, but may also be useful reading for those who rely on using reports from portal.vippsmobilepay.com for their reconciliation processes.

The exact details of the settlement process (e.g., the delay before the money is received) is subject to the agreement between the merchant and Vipps MobilePay. Please see the general Vipps MobilePay Settlements description for more information.

Ledger transactions and balances

We don't transfer money to/from the merchant for every payment made. Instead, all transactions are put on a ledger that tracks the funds that we owe the merchant. During the day, transactions occur that usually increase, and sometimes decrease, the balance the merchant has in Vipps MobilePay. Periodically (daily/weekly/monthly depending on configuration), the balance of the ledger is paid out to a configured account number and the balance is reset.

The following illustration shows an example day at a low-traffic merchant. Captures (sales) and refunds are added to the ledger, changing the balance of funds that Vipps MobilePay owes the merchant. At the end of the day, we deduct some fees and the remaining balance is paid out. The payout is itself an entry on the ledger, adjusting the balance down to zero. Funds account illustration

This example may look as follows if the data returned from GET:/report/v2/ledgers/12345/funds/dates/2022-10-01 is displayed as a table:

ledgerDateentryTypeamountreferencepspReferencerecipientHandletimebalanceBeforebalanceAfter
2022-10-01capture10000purchase-123343121302NO:578602022-10-01T16:33:00.824993+0200010000
2022-10-01capture10000purchase-123334234112NO:578602022-10-01T18:37:55.982497+02001000020000
2022-10-01capture20000purchase-143259823497NO:578602022-10-01T19:12:54.932428+02002000040000
2022-10-01refund-10000purchase-121154320987NO:578602022-10-01T23:47:59.984224+02004000030000
2022-10-01fees-retained-120001H7W7Q6Y5R-3G58CTAZX0MHKV22022-10-02T00:00:00.000000+02003000028800
2022-10-01payout-scheduled-28800Vipps utbet. 2000023 Vippsnr 5786012345-20000232022-10-02T00:00:00.000000+0200288000

Where the data is of these types:

  • ledgerDate - Date for which the transactions occurred, in YYYY-MM-DD format.
  • entryType - The type of transaction. See Entry type reference for a description.
  • amount- Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.
  • recipientHandle - Identification of the sales unit that this payment was made to/from. Contains a country code and ID, separated by a colon (':').
  • time - The date and time of the transaction. These are presented together with an offset (difference from UTC time in hours).
  • balanceBefore - Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.
  • balanceAfter - Amounts are specified in minor units. For Norwegian kroner (NOK) that means 1 kr = 100 øre. Example: 499 kr = 49900 øre.
  • reference - The merchant's reference for the entry (see Entry type reference for more details)
  • pspReference - Vipps MobilePay's reference for the entry (see Entry type reference for more details)
note

Monetary values returned from the endpoint are in cents/øre.

This example shows:

  • Three sales captures minus one refund brings the daily total to 300.00.
  • The sum of fees for the captures, 12.00, is retained by Vipps MobilePay.
  • The remaining balance of 288.00 being scheduled for payout. The actual payout may not happen after waiting some days, reflecting delays in the bank networks, and subject to the merchant's agreement with Vipps MobilePay. Once the payout is scheduled, the money is gone from the ledger balance.

Above, only the total fees for the settlement period are included. If you require further specification of the fees charged, these are available from the GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate} endpoint, where {topic} is fees.

Continuing on the example above, this may be the result of a call to GET:/report/v2/ledgers/12345/fees/dates/2022-10-01:

ledgerDateentryTypeamountreferencepspReferencerecipientHandletimebalanceBeforebalanceAfter
2022-10-01capture-fee-400purchase-123343121302NO:578602022-10-01T16:33:00.824993+02000-400
2022-10-01capture-fee-400purchase-123334234112NO:578602022-10-01T18:37:55.982497+0200-400-800
2022-10-01capture-fee-400purchase-143259823497NO:578602022-10-01T19:12:54.932428+0200-800-1200
2022-10-01fees-retained120012345-20003212022-10-02T00:00:00.000000+020012000

Note that:

  • pspReference can be used to correlate between funds and fees.
    • Note that, while each capture shown for the topic of funds has a unique pspReference, it is possible to have several fees on fees related to the same pspReference.
  • The fees-retained entry will always appear at the same time on both endpoints and have opposing signs (money is moved from the funds account and put on the fees account).
note

In general, for both fees and funds, it is important to be prepared for new entry types. The reference of entry types is at the bottom of this page, but new types can be added to the API later without prior warning.

Complicating factors and account diagram

While the above is a sufficient example of the "happy day" settlement process, there are some possible complicating factors.

Net vs gross settlements

Fees for the services from Vipps MobilePay can be charged in two ways:

  • Net settlements - The fees are retained from the settlement payouts. The fees-retained entry is used to settle the fees, as shown in the example above.
  • Gross settlements - The fees are invoiced. In this case, there is no mention of the fees in the funds account, while on the fees account, a fees-invoiced entry indicates that an invoice has been sent for the fees.

Payout delay

Settlement payouts are not done instantly, but after a certain delay. The length of this delay varies depending on the agreement between the merchant and Vipps MobilePay. For instance, if it is agreed to pay out money at "T+2", then assuming the capture/sale is done on Monday, the money is paid to the merchant on Wednesday. However, the report about what payout is planned on Wednesday is available already Tuesday morning. This is indicated by payout-scheduled in the example above.

The payout can in some cases be blocked. One example of this happening is if the merchant changes their bank account and they need to prove the ownership of the new bank account. In such cases executing the payouts is delayed until the problem blocking the payout is resolved; but payout-scheduled entries are still being generated. When the problem is resolved, all the transfers earlier scheduled will be executed, one by one.

Negative balance

If the sum of refunds and fees are larger than the sum of captures, the balance of the ledger can be become negative. For example, consider a concert that sells tickets months in advance, and that this money is continuously paid out on a daily basis. Then, if the concert is cancelled and all tickets refunded, all of that money is refunded at once, likely leading to a negative balance.

If a balance is negative for too long, an invoice will be sent to the merchant. This will lead to a top-up entry on the funds ledger (either when the invoice is sent or when it is paid; details may vary).

Account diagram

To correctly model these complicating factors, we can use the following account diagram: illustration of all accounts

Note that:

  • When sales (captures) happen, the balance of funds account is increased. Refunds decrease the balance of the funds account.
  • As fees are charged throughout the day, they are deducted from the fees account.
  • Fees are settled in one of two ways:
    • i) They are transferred from the funds account to the fees account, or
    • ii) They are invoiced from the merchant
  • Periodically, the funds account is packaged/batched and scheduled for payout. This is indicated in the figure with a transfer to the payouts account, where money is waiting to be paid out.
    • If there are any problems with paying the money out (such as, the bank account of the merchant was closed), the money will stay in the payouts account. In particular, the funds account will contain payout-scheduled even if the actual payout did not succeed. If money does not arrive within the agreed-upon delay, please contact customer service.

The topics available at the GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate} are described further:

  • The funds topic reports on the funds account.
  • The fees topic reports on the fees account.
  • There is currently no endpoint to report on payouts, but we hope to add this in the future.

We recommend that the merchant's accounting system reflects the structure above:

  • An account for fees owed to Vipps MobilePay.
  • An account for funds stored at Vipps MobilePay.
    • When sales are made, book the income towards this account.
  • A settlement payout from Vipps MobilePay is simply a transfer between two funds accounts, both belonging to the merchant.

Downloading reports

Retrieving the LedgerId

In order to call the endpoints containing settlement information, you will need a LedgerId. A ledger is an instance of the set of accounts described in the Account diagram. The ledger determines which payments are grouped together for settlement.

For the large majority of merchants, there is a direct correspondence between a Vippsnummer (a.k.a., Shopping Basket and Open Amount IDs) and eCom Merchant Serial Number (MSNs) to a ledger:

However, for merchants who require it, Vipps MobilePay has limited support for multiple Vippsnummer and eCom MSNs to be settled together. The payments to multiple different units are then combined in a single settlement payout:

The ledger has its own ledgerId, so the first step in using this API is to fetch the list of ledgers you have access to. If you are integrating a single merchant it may be enough to hit this endpoint once manually to identify the ledgerId. An example response from GET:/settlement/v1/ledgers is:

{
"items": [
{
"ledgerId": "302321",
"currency": "NOK",
"payoutBankAccount": {
"scheme": "BBAN:NO",
"id": "86011117947"
},
"owner": {
"scheme": "business:NO:ORG",
"id": "987654321"
},
"settlesForRecipientHandles": [ "api:123455" ]
}
],
"cursor": "eyJhZnRlckxlZGdlcklkIjoie"
}

A Vippsnummer will use the same settlesForRecipientHandles structure, but have a different prefix:

{
"settlesForRecipientHandles": [ "NO:123455" ]
}

Similarly, a MyShop instance will have a handle DK:123456 (Denmark) or FI:123456 (Finland).

If you only want to look up the ledgerId from an MSN or Vippsnummer, you may use the settlesForRecipientHandles argument:

GET:/settlement/v1/ledgers?settlesForRecipientHandles=DK:123456

If you are integrating an accounting system for many customers, it can be relevant to poll this endpoint many times as you will continue to see new ledgers appear for different customers as they grant your accounting system access to their data.

Paging and cursors

The GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate} endpoint has a response in this form:

{
"cursor": "eyJhZnRlckxlZGdlcklkIjoie",
"hasMore": true,
"items": [
{
"pspReference": "3343121302",
"time": "2020-10-05T00:00:00.000000Z",
"ledgerDate": "2020-10-05",
"entryType": "refund",
"reference": "acme-shop-123-order123abc",
"currency": "NOK",
"amount": -49900,
"balanceBefore": 49900,
"balanceAfter": 0,
"recipientHandle": "NO:123455"
},
{...},
{...}
]
}

There will be up to 1000 items returned in each response. If there are fewer than 1000 items, the cursor will not be included.

After storing or processing the items, a new request should be done where the value from cursor is passed in order to continue on the next page of data:

GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate}/?cursor=eyJhZnRlckxlZGdlcklkIjoie

Once the end of data is returned, the response will look like this:

{
"hasMore": false,
"items": [
{
"pspReference": "3343121302",
"time": "2020-10-05T00:00:00.000000Z",
"ledgerDate": "2020-10-05",
"entryType": "refund",
"reference": "acme-shop-123-order123abc",
"currency": "NOK",
"amount": -49900,
"balanceBefore": 49900,
"balanceAfter": 0,
"recipientHandle": "NO:123455"
},
{...},
{...}
]
}

Retries of downloads and polling for new data

We recommend that users of this API implement a robust retry mechanism. Sometimes reports can be delayed, or there can be network issues or temporary downtime either at the integrator or at Vipps MobilePay. Rather than, e.g., scheduling a job to run at 08:00 every morning, we instead recommend a pattern where a job is run once every hour of every day. The job should then be programmed to download whatever data is available which has not yet been fetched. This pattern gracefully handles temporary downtime and delays.

If you set up a job every hour, please pick a random minute during the hour when your job runs. If one integrator runs their jobs at :14 after each hour and another at :48, they don't have to compete for resources from this API, and both get a better experience than if they both started their job on :00. Don't choose to run your time between :00 and :10, as that time integrators who did not read this paragraph will use the API.

Immutability of data

Regardless of which kind of report is fetched, once data is available and has been returned it will be immutable. The same report fetched at a later point will always contain the same data. If something needs to be corrected, this will be done by adding new correction entries, leaving the old incorrect entries unmodified.

Note however that through upgrades to the API, more types of data (more columns/JSON fields) may become available in historical reports. See: API Lifecycle.

Reporting periods

The synchronization process can happen in several ways, as visualized in the following diagram:

Settlement

Method 1: Fetching a complete report for each date

The GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate} endpoint offers a complete report per ledger date; indicated by blue in the diagram above.

Normally, a ledger date lasts from midnight to midnight in the timezone of the merchant, but it can be configured to other cutoffs such as 04:00 to 04:00. To configure the cutoff: Please contact your key account manager, partner manager, or use the contact us page. It is not (yet) possible for a merchant or partner to configure this.

On this endpoint, no data is available until the entire ledger date is complete. Your code should be written to periodically poll for a report for the next date you don't already have one. You will then initially receive a response indicating that the report is not yet ready.

Here is an example call:

GET:/report/v2/ledgers/{ledgerId}/funds/dates/2023-08-02

Response:

{
"items": [],
"tryLater": true
}

Eventually when the report is ready, you will receive a response with data, such as:

{
"cursor": "eyJhZnRlckxlZGdlcklkIjoie",
"hasMore": true,
"tryLater": false,
"items": [
{
"pspReference": "22342342342",
"time": "2023-09-27T14:11:12.640000Z",
"entryType": "capture",
"reference": "acme-shop-123-order123abc",
"currency": "NOK",
"amount": 10000,
"recipientHandle": "NO:12345",
"balanceAfter": 10000,
"balanceBefore": 0
},
{
"pspReference": "22342342342",
"time": "2023-09-27T14:11:12.640000Z",
"entryType": "refund",
"reference": "acme-shop-123-order123abc",
"currency": "NOK",
"amount": -10000,
"recipientHandle": "NO:12345",
"balanceAfter": 0,
"balanceBefore": 10000
}
],
}
note

In this example, hasMore is true and cursor is present. This indicates that the provided items is not the full list of data, and that you need to do another call to continue fetching more data. See the section on paging and cursors.

In the most typical scenario, the balance is zero at the start of a day, funds are accumulated, and the day ends with a payout-scheduled entry that pays out the balance and adjusts the balance back down to zero. There are however other cases:

  • If a weekly/monthly settlement has been configured, then the balance will keep accumulating from day to day until the payout is scheduled on the last day of the week/month.
  • If the balance is negative (the sum of refunds and fees is higher than the sum of captures), a negative balances is carried over to the next day.
  • The agreement with Vipps MobilePay may stipulate that a certain balance is always kept in the ledger to cover possible refunds (so-called "rolling reserve").

By fetching daily reports, you will always get more data every day, even if payouts are scheduled on a weekly/monthly basis, or if the balance is negative. The balanceAfter field represents the balance the merchant owns that is sitting at Vipps MobilePay at any time.

Method 2: Continuous feed of data

The other option is to continuously stream data as it becomes available. You would normally use this to synchronize the data from Vipps MobilePay to your own database, and then it is your own responsibility to do any periodization, if desired. We recommend this way of fetching data in general. Just be aware that it may require some more sophistication in the logic for fetching reports.

The GET:/report/v2/ledgers/{ledgerId}/{topic}/feed endpoint indicates single "infinite" report, the "feed":

GET:/report/v2/ledgers/{ledgerId}/funds/feed

The big difference from the other access methods is that the cursor will never become empty. Once you have read to the end of the feed and there will be no more data available, you will receive:

  1. the same cursor over again
  2. the tryLater field will be set to true

It may or may not be that the items list is empty when hitting the end of the feed in this manner. If you get a response where tryLater is true, please wait some time (seconds or minutes or hours depending on your traffic level) and then retry using the same cursor. If tryLater is false more data is immediately available if you pass in the provided cursor.

If you poll the endpoint too often, and unless you represent a very high volume merchant, you will end up downloading either 0 or 1 entries each time you call the endpoint, effectively downloading the entries one by one. This is inefficient for both you and Vipps MobilePay; so, unless you need the data with low latency, we recommend just downloading new data relatively seldom (e.g. once per minute or once per hour).

A report for each payout?

What about a specification for the payout to the bank account of the merchant?

We don't recommend relying on such a report because it will lead to sudden "radio silence" if there is negative balance for an extended period of time. However, if you need such a specification anyway, it is easy enough to do yourself using the GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate} endpoint.

Each payout (settlement bank transfer) will always consist of a whole number of ledger dates. And, the payout-scheduled entry will always be the last entry on the ledger date, if a payout is made. So:

  • Look up the last date for which you do not have a report
  • Fetch data for that date from GET:/report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate}, where {topic} is funds.
  • Does the funds report for that date end with a payout-scheduled entry?
    • If yes, stop.
    • If no, no payout was made at the end of the day (e.g., negative balance, weekly/monthly settlement, etc.) Proceed to the next date and include this in the same report.

Using the example figure above, these steps will produce:

  • Report for payout 2000101:
    • .../dates/2022-09-01/funds
  • Report for payout 2000102:
    • .../dates/2022-09-02/funds
    • .../dates/2022-09-03/funds

GDPR data

If the parameter includeGDPRSensitiveData is set to true, each payment will contain the additional fields message, name and maskedPhoneNo.

This is considered user sensitive data and is regulated by GDPR.

Examples

  • GET:/report/v2/ledgers/12345/dates/2023-12-31?includeGDPRSensitiveData=true
  • GET:/report/v2/ledgers/12345/funds/fees?includeGDPRSensitiveData=true

Example response:

"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",
"message": "Payment for order 123abc",
"name": "John Doe",
"maskedPhoneNo": "xxxx 5678"
}
]

Entry type reference

note

You should be prepared to receive a new entry type that you do not already know about. The introduction of a new entry type will not be considered an API change. The important thing is always the contribution that the amount makes to the balance of a given fees or funds account.

Funds entry types

The following are entry types returned for the funds ledgers:

capture

Captures represent money being transferred from the customer, through Vipps MobilePay, to the merchant. Captures increase the ledger balance in the funds account.

In some other APIs, we distinguish between two types of payment flows: The sale flow for an immediate purchase, and the reserve/capture flow for cases when one first receives a reservation, and then captures it fully or partially at a later point. In the Report API, both of these are denoted with an entry type of capture.

  • pspReference is an ID generated by Vipps MobilePay to refer to this specific capture. The same pspReference will be used for all fees related to this capture. In the event that there are several captures for the same payment, pspReference will be different.
  • reference is the same for all entries relating to the same payment. Normally it is provided by the integration, but this depends on the Vipps MobilePay product used.

refund

Refunds represent transfers from the funds account back to the customer. These are initiated by the merchant, either by using the API or on portal.vippsmobilepay.com. Refunds are always deducted from the next settlement payout, even if you have a gross settlement setup. Currently, refunds always have zero fees.

  • pspReference is an ID generated by Vipps MobilePay to refer to this specific refund.
  • reference is the same for all entries relating to the same payment. Normally it is provided by the integration, but this depends on the Vipps MobilePay product used.

fees-retained

Entry type of fees-retained indicates that money was retained to cover fees to Vipps MobilePay (i.e., net settlements). This entry type is present in both the funds reports (as a negative value) and the fees report (as a positive value).

  • pspReference is a unique value generated by Vipps MobilePay. The same value is used on fees-retained entry on the fees-ledger
  • reference is empty

payout-scheduled

Entry type of payout-scheduled indicates that a payout has been scheduled from the ledger. This is described under Payout delay.

  • pspReference is a unique value generated by Vipps MobilePay, generated as <ledgerId>-<payoutNumber>. The payoutNumber is sequentially increasing with each payout.
  • reference has the text that will be attached to the bank transfer when the payout is executed; this can be used to identify the transfer in the merchant's bank.
    • Denmark/Finland: The generated reference. The format of this is configurable by the merchant in the portal.
    • Norway: Currently this field is missing in Norway and will not correspond to the reference on the payout. We hope to have fixed this problem at some point in the future.

payout-aborted

Entry type of payout-aborted indicates that a payout was aborted, and the money put back on the ledger. This can happen in some extraordinary circumstances if a payout can never be executed (despite retries), or the payout is aborted in order to cover a negative balance on the subsequent day.

retained-disputed-capture

If a capture (sale) that has been previously added to the ledger is disputed by the issuer (e.g., suspicion of fraud, damaged goods), Vipps MobilePay may deduct the capture from the ledger.

  • Both pspReference and reference are identical to the capture being disputed

returned-disputed-capture

In the event that the merchant wins the dispute process, money previously captured is returned. The retained/returned cycle may in theory occur several times for the same capture.

  • Both pspReference and reference are identical to the capture being disputed

correction

A correction entry type indicates a fully manual adjustment of the balance to resolve some unexpected problem. Normally, you should expect to have received communication about the nature of the incident if this is ever present. Feel free to contact Vipps MobilePay support for further details if you see this and don't know why.

top-up

This represents a deposit ("top-up") of the account, by the merchant directly transferring funds to it. For instance, if the merchant's balance on the ledger is negative for a while, an invoice can be sent prompting the merchant to pay money to Vipps MobilePay (i.e., topping up their account so that the balance becomes positive).

Fees entry types

The following are entry types returned for the fees ledgers:

capture-fee

A fee charged for a capture.

Both pspReference and reference are identical to the corresponding fields for the capture entry for which a fee is being charged. Please note that in some circumstances there may be more than one capture-fee entry for a single capture; this represents several fees being charge for the same capture. This means that pspReference is unique for the capture entry type on the funds ledger, but is not unique for the capture-fee entry on the fees ledger.

fees-retained

Indicates that money was retained to cover fees to Vipps MobilePay ("net settlements"). This entry type is present both on the funds reports (negative) and the fees report (positive).

  • pspReference is a unique value generated by Vipps MobilePay. The same value is used on fees-retained entry on the funds ledger
  • reference is empty

fees-invoiced

If gross/non-retained settlements has been configured, then the fees are invoiced on a monthly basis, and the fees balance is adjusted using this entry type.

Further reading

See:

Help us improve our documentation

Did you find what you were looking for?