Skip to main content
API docs by Redocly

PoS Integrator API (10.2.6)

MobilePay Developer Support: developer@vippsmobilepay.com URL: https://developer.mobilepay.dk/docs/pos

Change of PoS in 2024

Please notice that as part of the merger between MobilePay and Norwegian Vipps, we will consolidate products on one joint platform. In the beginning of 2024 we will therefore replace the current PoS API with a new and scalable version. We will update this page as soon as documentation for the new API is available. See more here

MobilePay PoS Integrator API v10

The API is split into 3 categories:

  • PointOfSales: Management of Point of Sales including creating, deleting and querying. Note that a Point of Sale is immutable and not editable.
  • Stores: Look up store information.
  • Payments: Everything needed in order to initiate and complete a payment.

For more information on working with the API, see the documentation.

Payment flows

Payments can be started in two ways:

  • as an initiated payment that is immediately ready for user approval, or
  • as a prepared payment that is not yet ready for user approval, and must be explicitly marked as ready later.

Once a payment is ready for user approval, it is issued to the user. Once the user accepts the payment request, and the payment amount has been reserved, the payment must be captured to complete the payment.

The API thus supports the following two payment flows:

  • Initiate payment (POST /pos/v10/payments)
  • Poll until reserved (GET /pos/v10/payments/{paymentid})
  • Capture (POST /pos/v10/payments/{paymentid}/capture)

or

  • Prepare payment (POST /pos/v10/payments/prepare)
  • Mark as ready (POST /pos/v10/payments/{paymentid}/ready)
  • Poll until reserved (GET /pos/v10/payments/{paymentid})
  • Capture (POST /pos/v10/payments/{paymentid}/capture)

For more information on payment flows, see the documentation.

Payments

Payments API makes it easy to initiate and complete a payment

Gets a single payment by its ID.

When polling this endpoint waiting for the payment state to change, please respect the pollDelayInMs response property as per the docs.

path Parameters
paymentid
required
string <uuid>

The payment ID to query

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "paymentId": "3974eae6-e36f-4148-b5ee-22689e528c75",
  • "posId": "c85916b1-8e17-4275-a388-551e16aa6293",
  • "orderId": "ORDER-12345",
  • "amount": 12.5,
  • "currencyCode": "DKK",
  • "restrictions": {
    },
  • "merchantPaymentLabel": "PaymentLabel",
  • "plannedCaptureDelay": "None",
  • "status": "Reserved",
  • "customerToken": "09bee223516e44000811ab0988b802b72a193c22",
  • "customerReceiptToken": "d0d0f8dc0adc4cec9398d82c93dad0d1",
  • "loyaltyIds": [
    ],
  • "paymentExpiresAt": "2022-10-17T06:07:45.4847176+00:00",
  • "partialCapturePossible": false,
  • "pollDelayInMs": 1000
}

Gets a list of active and reserved payments

Returns a list of active and reserved payments (ie. neither captured, rejected, cancelled, or reversed) if no paymentState is provided. Can also return only captured payments if the Captured paymentState is explicitly provided.

query Parameters
posId
string or null <uuid>

Filter payments to those carried out on this point of sale.

orderId
string or null

Filter payments to those with this order ID.

state
string or null
Value: "Captured"

Filter payments to those with this state.

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "paymentIds": [
    ]
}

Initiates a new payment.

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Idempotency-Key
required
string

Used to ensure retried calls are handled correctly. See Idempotency Keys.

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Request Body schema:

Information needed to initiate the payment

amount
required
number <decimal>

The monetary value of the payment, in the currency defined by CurrencyCode.

currencyCode
required
string
Enum: "DKK" "EUR"

The currency of the payments.

orderId
required
string

A merchant-provided order ID to associate with this payment.

Must be at most 36 characters long, and fit the valid character set.

plannedCaptureDelay
required
string
Enum: "None" "LessThan24Hours" "LessThan14Days"

When the payment is expected to be captured, see Specify planned capture delay.

posId
required
string <uuid>

The point of sale to initiate the payment on.

object or null

Restrictions to apply to the payment (eg. debit/credit card), or null if no restrictions should be applied.

merchantPaymentLabel
string or null

Merchant-provided label tag for the payment. This is visible in the transaction reporting section on the MobilePay Portal.

Must be at most 36 characters long, and fit the valid character set.

Responses

Request samples

Content type
{
  • "posId": "c85916b1-8e17-4275-a388-551e16aa6293",
  • "orderId": "ORDER-12345",
  • "amount": 12.5,
  • "currencyCode": "DKK",
  • "restrictions": {
    },
  • "merchantPaymentLabel": "PaymentLabel",
  • "plannedCaptureDelay": "None"
}

Response samples

Content type
application/json
{
  • "paymentId": "3974eae6-e36f-4148-b5ee-22689e528c75"
}

Prepares a new payment that is not yet ready for user approval.

The payment will need to be marked as ready with a POST /payments/{paymentId}/ready. Information like the payment amount, currency code, potential restrictions, etc, needs to be provided later, when the ready request is sent.

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Idempotency-Key
required
string

Used to ensure retried calls are handled correctly. See Idempotency Keys.

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Request Body schema:

Information needed to prepare the payment

orderId
required
string

A merchant-provided order ID to associate with this payment.

Must be at most 36 characters long, and fit the valid character set.

posId
required
string <uuid>

The point of sale to initiate the payment on.

Responses

Request samples

Content type
{
  • "posId": "c85916b1-8e17-4275-a388-551e16aa6293",
  • "orderId": "ORDER-12345"
}

Response samples

Content type
application/json
{
  • "paymentId": "3974eae6-e36f-4148-b5ee-22689e528c75"
}

Marks a prepared payment as ready for approval by the user.

path Parameters
paymentid
required
string <uuid>

The payment to mark as ready

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Request Body schema:

Information needed to ready the payment

amount
required
number <double>

The monetary value of the payment, in the currency defined by CurrencyCode.

currencyCode
required
string
Enum: "DKK" "EUR"

The currency of the payments.

plannedCaptureDelay
required
string
Enum: "None" "LessThan24Hours" "LessThan14Days"

When the payment is expected to be captured, see Specify planned capture delay.

object or null

Restrictions to apply to the payment (eg. debit/credit card), or null if no restrictions should be applied.

merchantPaymentLabel
string or null

Merchant-provided label tag for the payment. This is visible in the transaction reporting section on the MobilePay Portal.

Must be at most 36 characters long, and fit the valid character set.

Responses

Request samples

Content type
{
  • "currencyCode": "DKK",
  • "amount": 12.5,
  • "restrictions": {
    },
  • "merchantPaymentLabel": "PaymentLabel",
  • "plannedCaptureDelay": "None"
}

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Error message explaining the error that happened while processing the request",
  • "correlationId": "113568d5-68fc-4434-ad80-6e67402a3f93"
}

Captures a payment. Only reserved payments can be captured.

path Parameters
paymentid
required
string <uuid>

The payment to capture

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Request Body schema:

Information needed to capture the payment

amount
required
number <decimal>

The monetary amount to capture, in the currency previously defined on the payment.

If partial capture is supported, this may be lower than the amount specified in the payment. In that case, only this amount will be captured. Otherwise, the amount should be the same as specified earlier in the payment flow. See Partial Capture.

Responses

Request samples

Content type
{
  • "amount": 12.5
}

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Error message explaining the error that happened while processing the request",
  • "correlationId": "113568d5-68fc-4434-ad80-6e67402a3f93"
}

Cancels a payment. A payment cannot be cancelled once it has been captured.

path Parameters
paymentid
required
string <uuid>

The payment to cancel

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Error message explaining the error that happened while processing the request",
  • "correlationId": "113568d5-68fc-4434-ad80-6e67402a3f93"
}

Point Of Sales

Point Of Sales (POS) API makes it easy to create a POS and associate it to a Store

Gets a single point of sale by its ID.

path Parameters
posid
required
string <uuid>

The ID of the point of sale

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "posId": "22f8155d-4042-4439-825f-068dbca98857",
  • "merchantPosId": "My-Pos-1",
  • "storeId": "401b5617-ae5e-4f1a-9a59-5a446dbb3caa",
  • "name": "Cafeteria register #2",
  • "beaconId": "a7b69d37-6753-4e94-afc3-ef5dab04b7f4",
  • "callbackAlias": "Example Alias",
  • "supportedBeaconTypes": [
    ],
  • "requirePaymentBeforeCheckin": false
}

Deletes a point of sale.

path Parameters
posid
required
string <uuid>

The point of sale to delete

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Error message explaining the error that happened while processing the request",
  • "correlationId": "113568d5-68fc-4434-ad80-6e67402a3f93"
}

Gets a list of point of sale IDs corresponding to the given filters.

Multiple filters can be passed, and the returned PoSs will match all filters.

When passing a beacon ID or a merchant PoS ID, at most one result will be returned.

query Parameters
storeId
string or null <uuid>

Restricts query to PoSs belonging to this store ID

beaconId
string or null

Restricts query to PoSs with this beacon ID

merchantPosId
string or null

Restricts query to PoSs with this merchant PoS ID

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "posIds": [
    ]
}

Creates a point of sale.

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Idempotency-Key
required
string

Used to ensure retried calls are handled correctly. See Idempotency Keys.

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Request Body schema:

Parameters for creating the PoS

merchantPosId
required
string

Merchant-defined unique ID to associate with this point of sale; can be used for lookup. MerchantPosIds are unique for a given integrator and merchant.

Must be at most 36 characters long, and fit the valid character set.

name
required
string

Merchant-defined PoS name. This is shown to the user after check-in.

Must be at most 36 characters long, and fit the valid character set.

storeId
required
string <uuid>

The store to create this point of sale for.

supportedBeaconTypes
required
Array of strings unique
Items Enum: "QR" "NFC" "Bluetooth"

Beacon types this PoS supports for check-in (eg. QR, Bluetooth).

beaconId
string or null

Beacon ID associated with this point of sale.

This may either be a 15-digit number (eg. white-box QR codes) or a GUID. If null, a beacon ID will be generated for you.

See Beacons.

callbackAlias
string or null

Callback alias, only for use with the Notification Service.

requirePaymentBeforeCheckin
boolean

When set to true, a user will not be allowed to check-in before a payment is created on this PoS.

Responses

Request samples

Content type
{
  • "merchantPosId": "My-Pos-1",
  • "storeId": "401b5617-ae5e-4f1a-9a59-5a446dbb3caa",
  • "name": "Cafeteria register #2",
  • "beaconId": "a7b69d37-6753-4e94-afc3-ef5dab04b7f4",
  • "callbackAlias": "Example Alias",
  • "supportedBeaconTypes": [
    ],
  • "requirePaymentBeforeCheckin": false
}

Response samples

Content type
application/json
{
  • "posId": "c85916b1-8e17-4275-a388-551e16aa6293"
}

Looks up information about the user currently checked in at a point of sale.

This will return 200 OK whether or not a user is checked in; check the isUserCheckedIn response property.

When polling this endpoint waiting for a check-in, please respect the pollDelayInMs response property as per the docs.

path Parameters
posid
required
string <uuid>

The point of sale

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "isUserCheckedIn": true,
  • "loyaltyIds": [
    ],
  • "pollDelayInMs": 1000,
  • "customerToken": "09bee223516e44000811ab0988b802b72a193c22",
  • "customerReceiptToken": "d0d0f8dc0adc4cec9398d82c93dad0d1"
}

Stores

Stores API makes it easy for you query stores and get detailed information. Stores are created by merchants when onboarding as a MobilePay merchant.

Gets a store by its ID.

path Parameters
storeid
required
string <uuid>

The store ID

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "storeName": "MobilePay Finland HQ",
  • "storeId": "401b5617-ae5e-4f1a-9a59-5a446dbb3caa",
  • "storeStreet": "Keskuskatu 4",
  • "storeZipCode": "00100",
  • "storeCity": "Helsinki",
  • "brandName": "MobilePay Offices",
  • "merchantBrandId": "POSDK12345",
  • "merchantLocationId": "10001"
}

Gets a list of store IDs corresponding to the given filters.

query Parameters
merchantBrandId
string or null

Restricts query to stores with this merchant brand ID

merchantLocationId
string or null

Restricts query to stores with this merchant location ID

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "storeIds": [
    ]
}

Gets a list of stores corresponding to the given filters.

query Parameters
merchantBrandId
string or null

Restricts query to stores with this merchant brand ID

merchantLocationId
string or null

Restricts query to stores with this merchant location ID

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Refunds

Refunds API makes it easy for you to refund payments to your customers. You can refund only those payments that were created via payments API above.

Lookup a refund

path Parameters
refundid
required
string <uuid>

Refund identifier

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "refundId": "7f3a6f03-fcd4-4860-a795-138e7dcf948e",
  • "paymentId": "fc4e7476-894e-4d84-a9c8-a063067aad3a",
  • "refundOrderId": "REFUND-12345",
  • "amount": 12.5,
  • "currencyCode": "DKK",
  • "status": "Reserved",
  • "pollDelayInMs": 100
}

Lookup refunds for a given filter

query Parameters
paymentId
string or null <uuid>

Restricts refunds returned to those that belongs to this paymentId

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "refundIds": [
    ]
}

Create a refund (a payment can be refunded multiple times, the sum of the refunds cannot exceed the full amount of the payment)

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Idempotency-Key
required
string

Used to ensure retried calls are handled correctly

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Request Body schema:

Create refund request

amount
required
number <double>
currencyCode
required
string (CurrencyCode)
Enum: "DKK" "EUR"
paymentId
required
string <uuid>
refundOrderId
required
string

Responses

Request samples

Content type
{
  • "paymentId": "fc4e7476-894e-4d84-a9c8-a063067aad3a",
  • "refundOrderId": "REFUND-12345",
  • "amount": 12.5,
  • "currencyCode": "DKK"
}

Response samples

Content type
application/json
{
  • "refundId": "7f3a6f03-fcd4-4860-a795-138e7dcf948e"
}

Capture a refund

path Parameters
refundid
required
string <uuid>

Refund identifier

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Error message explaining the error that happened while processing the request",
  • "correlationId": "bafb1a9a-7a5b-4949-8f43-b1ff7db4d65c",
  • "origin": "PoS"
}

Cancel a refund

path Parameters
refundid
required
string <uuid>

Refund identifier

header Parameters
Authorization
required
string

Integrator's bearer token

X-MobilePay-Client-System-Version
required
string

Integrator's certified system version

X-MobilePay-Merchant-VAT-Number
string

Merchant's VAT number (including country code prefix)

Responses

Response samples

Content type
application/json
{
  • "code": "1234",
  • "message": "Error message explaining the error that happened while processing the request",
  • "correlationId": "bafb1a9a-7a5b-4949-8f43-b1ff7db4d65c",
  • "origin": "PoS"
}

User Simulation

This API is used to simulate app functionality for when integrators are testing their implementation of MobilePay PoS.

With this API you can simulate

  • checkin of user to a pos
  • accept of payment
  • cancel of payment

Please note that this API is only supported in the Sandbox environment

Checks in user at PoS.

Request Body schema:

The information needed to check in a user to a pos.

beaconId
required
string

The beacon Id of the PoS to check in to.

phoneNumber
required
string

The phone number of the user.

Responses

Request samples

Content type
{
  • "beaconId": "a7b69d37-6753-4e94-afc3-ef5dab04b7f4",
  • "phoneNumber": "+4520031801"
}

Accepts payment on behalf of a user.

Request Body schema:

The information needed to accept a payment on a users behalf.

beaconId
required
string

The beacon Id of the PoS that has a payment request ready to be accepted.

phoneNumber
required
string

The phone number of the user the payment request has been sent to.

Responses

Request samples

Content type
{
  • "beaconId": "a7b69d37-6753-4e94-afc3-ef5dab04b7f4",
  • "phoneNumber": "+4520031801"
}

Cancels active payment on behalf of a user.

Request Body schema:

The information needed to cancel a payment on a users behalf.

beaconId
required
string

The beacon Id of the PoS that has the payment to be cancelled

Responses

Request samples

Content type
{
  • "beaconId": "a7b69d37-6753-4e94-afc3-ef5dab04b7f4"
}