PoS Integrator API (10.2.6)
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
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.
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
- 200
- 400
- 403
- 500
{- "paymentId": "3974eae6-e36f-4148-b5ee-22689e528c75",
- "posId": "c85916b1-8e17-4275-a388-551e16aa6293",
- "orderId": "ORDER-12345",
- "amount": 12.5,
- "currencyCode": "DKK",
- "restrictions": {
- "debitCardDisallowed": false,
- "creditCardDisallowed": false
}, - "merchantPaymentLabel": "PaymentLabel",
- "plannedCaptureDelay": "None",
- "status": "Reserved",
- "customerToken": "09bee223516e44000811ab0988b802b72a193c22",
- "customerReceiptToken": "d0d0f8dc0adc4cec9398d82c93dad0d1",
- "loyaltyIds": [
- "123456"
], - "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
- 200
- 400
- 500
{- "paymentIds": [
- "3974eae6-e36f-4148-b5ee-22689e528c75"
]
}
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 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 | |
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
- Payload
{- "posId": "c85916b1-8e17-4275-a388-551e16aa6293",
- "orderId": "ORDER-12345",
- "amount": 12.5,
- "currencyCode": "DKK",
- "restrictions": {
- "debitCardDisallowed": false,
- "creditCardDisallowed": false
}, - "merchantPaymentLabel": "PaymentLabel",
- "plannedCaptureDelay": "None"
}
Response samples
- 200
- 400
- 403
- 409
- 500
{- "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
- Payload
{- "posId": "c85916b1-8e17-4275-a388-551e16aa6293",
- "orderId": "ORDER-12345"
}
Response samples
- 200
- 400
- 403
- 409
- 500
{- "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 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 | |
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
- Payload
{- "currencyCode": "DKK",
- "amount": 12.5,
- "restrictions": {
- "debitCardDisallowed": false,
- "creditCardDisallowed": false
}, - "merchantPaymentLabel": "PaymentLabel",
- "plannedCaptureDelay": "None"
}
Response samples
- 400
- 403
- 409
- 500
{- "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
- Payload
{- "amount": 12.5
}
Response samples
- 400
- 403
- 409
- 500
{- "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
- 400
- 403
- 409
- 500
{- "code": "1234",
- "message": "Error message explaining the error that happened while processing the request",
- "correlationId": "113568d5-68fc-4434-ad80-6e67402a3f93"
}
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
- 200
- 400
- 403
- 500
{- "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": [
- "QR",
- "Bluetooth"
], - "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
- 400
- 403
- 500
{- "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
- 200
- 400
- 500
{- "posIds": [
- "c85916b1-8e17-4275-a388-551e16aa6293"
]
}
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 See Beacons. |
callbackAlias | string or null Callback alias, only for use with the Notification Service. |
requirePaymentBeforeCheckin | boolean When set to |
Responses
Request samples
- Payload
{- "merchantPosId": "My-Pos-1",
- "storeId": "401b5617-ae5e-4f1a-9a59-5a446dbb3caa",
- "name": "Cafeteria register #2",
- "beaconId": "a7b69d37-6753-4e94-afc3-ef5dab04b7f4",
- "callbackAlias": "Example Alias",
- "supportedBeaconTypes": [
- "QR",
- "Bluetooth"
], - "requirePaymentBeforeCheckin": false
}
Response samples
- 200
- 400
- 403
- 409
- 500
{- "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
- 200
- 400
- 403
- 500
{- "isUserCheckedIn": true,
- "loyaltyIds": [
- "123456"
], - "pollDelayInMs": 1000
}
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
- 200
- 400
- 500
{- "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
- 200
- 400
- 500
{- "storeIds": [
- "401b5617-ae5e-4f1a-9a59-5a446dbb3caa"
]
}
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
- 200
- 400
- 500
[- {
- "storeName": "MobilePay Finland HQ",
- "storeId": "401b5617-ae5e-4f1a-9a59-5a446dbb3caa",
- "storeStreet": "Keskuskatu 4",
- "storeZipCode": "00100",
- "storeCity": "Helsinki",
- "brandName": "MobilePay Offices",
- "merchantBrandId": "POSDK12345",
- "merchantLocationId": "10001"
}
]
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
- 200
- 400
- 403
- 500
{- "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
- 200
- 400
- 500
{- "refundIds": [
- "7f3a6f03-fcd4-4860-a795-138e7dcf948e"
]
}
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
- Payload
{- "paymentId": "fc4e7476-894e-4d84-a9c8-a063067aad3a",
- "refundOrderId": "REFUND-12345",
- "amount": 12.5,
- "currencyCode": "DKK"
}
Response samples
- 200
- 400
- 403
- 409
- 500
{- "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
- 400
- 403
- 409
- 500
{- "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
- 400
- 403
- 409
- 500
{- "code": "1234",
- "message": "Error message explaining the error that happened while processing the request",
- "correlationId": "bafb1a9a-7a5b-4949-8f43-b1ff7db4d65c",
- "origin": "PoS"
}
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
- Payload
{- "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
- Payload
{- "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
- Payload
{- "beaconId": "a7b69d37-6753-4e94-afc3-ef5dab04b7f4"
}