MobilePay PoS

Introduction

Authentication

Detecting MobilePay

User Activation

BLE 2-way Communication

Notification Service

Payment Flows

Payment Flow

Prepared Payment Flow

Payment Flow Error Handling

Refunds

Cancel Flows

Partial Capture

PoS Management

Notification Service

Best Practices

API Principles

Security Model

Client Versioning

API Responses

Error Handling

Call Throttling

Self Certification

API Errors

Input and Output Formats

Changes in V10

Release notes

Glossary

API Errors

This page contains information regarding all the non-successful status-codes and different error-codes that can occur in the V10 API. The first section contains all combinations of StatusCodes and ErrorCodes that can occur in all endpoints, and then follows sections for the individual endpoints.

Common for all endpoints

ALL Endpoints
StatusCode ErrorCodes Description
400 1099
1151
1152
1153
1155
1156
1157
1159
1160
1161
1182
Unknown BadRequest error
Missing x-mobilepay-merchant-vat-number header
Missing x-mobilepay-client-system-name header
Missing x-mobilepay-client-system-version header
Duplicated x-mobilepay-merchant-vat-number header
Duplicated x-mobilepay-client-system-name header
Duplicated x-mobilepay-client-system-version header
Invalid x-mobilepay-merchant-vat-number header
Invalid x-mobilepay-client-system-name header
Invalid x-mobilepay-client-system-version header
Invalid merchant_vat claim in access token
401 - Unauthorized
500 2000 - 2999 Internal server error - Please attach error code when communicating with MobilePay for quicker support

Payments

GET /v10/payments/{paymentid} - Query a Payment
StatusCode ErrorCodes Description
403 1401
1411
Cannot query payments created by a different integrator
Cannot query payments created on behalf of a different merchant
404 - Payment not found

GET /v10/payments - Query Payments by a filter
StatusCode ErrorCodes Description
400 1109 Payment filter not specific enough

POST /v10/payments - Initiate a Payment
StatusCode ErrorCodes Description
400 1102
1113
1117
1162
1163
1164
Invalid Amount
Invalid OrderId
Invalid MerchantPaymentLabel
Invalid x-mobilepay-idempotency-key header
Duplicated x-mobilepay-idempotency-key header
Missing x-mobilepay-idempotency-key header
403 1400 Cannot initiate payments on a point of sale created by a different integrator
409 1000
1301
1306

Point of Sale not found
A payment is already active. Cancel it before starting a new one
x-mobilepay-idempotency-key header has to be unique per request unless the request is a retry of a previous request

POST /v10/payments/prepare - Prepare a Payment
StatusCode ErrorCodes Description
400 1113
1162
1163
1164
Invalid OrderId
Invalid x-mobilepay-idempotency-key header
Duplicated x-mobilepay-idempotency-key header
Missing x-mobilepay-idempotency-key header
403 1400 Cannot prepare payments on a point of sale created by a different integrator
409 1000
1301
1306

Point of sale not found
A payment is already active. Cancel it before starting a new one
x-mobilepay-idempotency-key header has to be unique per request unless the request is a retry of a previous request

POST /v10/payments/{paymentid}/ready - Ready a Payment
StatusCode ErrorCodes Description
400 1102
1117
Invalid Amount
Invalid MerchantPaymentLabel
403 1401
1406
Cannot ready payments prepared by a different integrator
Cannot ready payments prepared on behalf of a different merchant
404 - Payment not found
409 1303 Payment needs to be prepared before it can be marked as ready

POST /v10/payments/{paymentid}/capture - Capture a Payment
StatusCode ErrorCodes Description
400 1102 Invalid Amount
403 1401
1407
Cannot capture payments created by a different integrator
Cannot capture payments created on behalf of a different merchant
404 - Payment not found
409 1304
1305
1307
1308
Cannot capture payment when payment is not reserved
Capture Amount cannot exceed the reserved amount
Payment has already been captured with a different amount
Partial capture not possible on this payment

POST /v10/payments/{paymentid}/cancel - Cancel a Payment
StatusCode ErrorCodes Description
403 1401
1408
Cannot cancel payments created by a different integrator
Cannot cancel payments created on behalf of a different merchant
404 - Payment not found
409 1300 The payment cannot be cancelled in the current state

Point of Sales

GET /v10/pointofsales/{posid} - Query a Point of Sale
StatusCode ErrorCodes Description
403 1400
1410
Cannot query point of sales created by a different integrator
Cannot query point of sales created on behalf of a different merchant
404 - Point of sale not found

GET /v10/pointofsales - Query Point of Sales by a filter
StatusCode ErrorCodes Description
400 1121 Point of sale filter not specific enough

GET /v10/pointofsales/{posid}/checkin - Query a checkin on a Point of Sale
StatusCode ErrorCodes Description
403 1400 Cannot query checkin on a point of sale created by a different integrator
404 - Point of sale not found

POST /v10/pointofsales - Create a Point of Sale
StatusCode ErrorCodes Description
400 1100
1111
1112
1116
1118
1162
1163
1164
Invalid BeaconId
Invalid MerchantPosId
Invalid PosName
Invalid CallbackAlias
Invalid CalibrationType
Invalid x-mobilepay-idempotency-key header
Duplicated x-mobilepay-idempotency-key header
Missing x-mobilepay-idempotency-key header
403 1403 Cannot create point of sale on store that does not belong to the merchant
409 1002
1200
1202
1306

Store not found
A point of sale with that MerchantPosId already exist
A point of sale with that BeaconId already exist
x-mobilepay-idempotency-key header has to be unique per request unless the request is a retry of a previous request

DELETE /v10/pointofsales/{posid} - Delete a Point of Sale
StatusCode ErrorCodes Description
403 1400
1409
Cannot delete point of sales created by a different integrator
Cannot delete point of sales created on behalf of a different merchant
404 - Point of sale not found

Refunds

GET /v10/refunds/{refundid} - Query a Refund
StatusCode ErrorCodes Description
403 1402 Cannot query refunds created by a different integrator
404 - Refund not found

GET /v10/refunds - Query Refunds by a filter
StatusCode ErrorCodes Description
400 1110 Refund filter not specific enough

POST /v10/refunds - Create a Refund
StatusCode ErrorCodes Description
400 1102
1114
1162
1163
1164
Invalid Amount
Invalid RefundOrderId
Invalid x-mobilepay-idempotency-key header
Duplicated x-mobilepay-idempotency-key header
Missing x-mobilepay-idempotency-key header
403 1401 Cannot refund payments created by a different integrator
409 1001
1306

1354
1365
1366
1367
Payment not found
x-mobilepay-idempotency-key header has to be unique per request unless the request is a retry of a previous request
Refund of payment not possible when payment is not captured
Refund CurrencyCode is different than payment CurrencyCode
Payment is too old
Refund Amount is too high

POST /v10/refunds/{refundid}/capture - Capture a reserved Refund
StatusCode ErrorCodes Description
403 1402 Cannot capture refunds created by a different integrator
404 1004 Refund not found
409 1351 Cannot capture refund when refund is not reserved

POST /v10/refunds/{refundid}/cancel - Cancel a reserved Refund
StatusCode ErrorCodes Description
403 1402 Cannot cancel refunds created by a different integrator
404 - Refund not found
409 1352 The refund cannot be cancelled in the current state

Stores

GET /v10/stores/{storeid} - Query a Store
StatusCode ErrorCodes Description
404 - Store not found

GET /v10/stores - Query a Store by MerchantBrandId and MerchantLocationId
StatusCode ErrorCodes Description
400 1122
1119
1120
Store filter not specific enough
Invalid MerchantBrandId
Invalid MerchantLocationId