diff --git a/docs/pos/_category_.json b/docs/pos/_category_.json deleted file mode 100644 index 7dbb98d27..000000000 --- a/docs/pos/_category_.json +++ /dev/null @@ -1 +0,0 @@ -{ "label": "Point of Sale", "position": 4 } diff --git a/docs/pos/api-errors.mdx b/docs/pos/api-errors.mdx deleted file mode 100644 index 6c720fed4..000000000 --- a/docs/pos/api-errors.mdx +++ /dev/null @@ -1,527 +0,0 @@ ---- -sidebar_position: 10 ---- - -# 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 - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001099
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
5002000 - 2999Internal server error - Please attach error code when communicating with MobilePay for quicker support
-
- -## Payments - -
- GET /v10/payments/paymentid - Query a Payment - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4031401
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 - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001109Payment filter not specific enough
-
- -
- POST /v10/payments - Initiate a Payment - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001102
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
4031400Cannot initiate payments on a point of sale created by a different integrator
4091000
1204
1301
1306
Point of Sale not found
The store for the given point of sale is not activated. Please activate the store before starting a payment
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 - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001113
1162
1163
1164
Invalid OrderId
Invalid x-mobilepay-idempotency-key header
Duplicated x-mobilepay-idempotency-key header
Missing x-mobilepay-idempotency-key header
4031400Cannot prepare payments on a point of sale created by a different integrator
4091000
1204
1301
1306
Point of sale not found
The store for the given point of sale is not activated. Please activate the store before starting a payment
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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001102
1117
Invalid Amount
Invalid MerchantPaymentLabel
4031401
1406
Cannot ready payments prepared by a different integrator
Cannot ready payments prepared on behalf of a different merchant
404-Payment not found
4091303Payment needs to be prepared before it can be marked as ready
-
- -
- POST /v10/payments/paymentid/capture - Capture a Payment - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001102Invalid Amount
4031401
1407
Cannot capture payments created by a different integrator
Cannot capture payments created on behalf of a different merchant
404-Payment not found
4091304
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 - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4031401
1408
Cannot cancel payments created by a different integrator
Cannot cancel payments created on behalf of a different merchant
404-Payment not found
4091300The payment cannot be cancelled in the current state
-
- -## Point of Sales - -
- GET /v10/pointofsales/posid - Query a Point of Sale - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4031400
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 - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001121Point of sale filter not specific enough
-
- -
- GET /v10/pointofsales/posid/checkin - Query a checkin on a Point of Sale - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4031400Cannot 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 - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001100
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
4031403Cannot create point of sale on store that does not belong to the merchant
4091002
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 - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4031400
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 - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4031402Cannot query refunds created by a different integrator
404-Refund not found
-
- -
- GET /v10/refunds - Query Refunds by a filter - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001110Refund filter not specific enough
-
- -
- POST /v10/refunds - Create a Refund - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001102
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
4031401Cannot refund payments created by a different integrator
4091001
1306

1354
1365
1366
1367
1368
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
Cannot refund Amount as it exceeds the available balance on the store
-
- -
- POST /v10/refunds/refundid/capture - Capture a reserved Refund - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4031402Cannot capture refunds created by a different integrator
4041004Refund not found
4091351Cannot capture refund when refund is not reserved
-
- -
- POST /v10/refunds/refundid/cancel - Cancel a reserved Refund - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4031402Cannot cancel refunds created by a different integrator
404-Refund not found
4091352The refund cannot be cancelled in the current state
-
- -## Stores - -
- GET /v10/stores/storeid - Query a Store - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
404-Store not found
-
- -
- GET /v10/stores - Query a Store by MerchantBrandId and MerchantLocationId - - - - - - - - - - - - - - - - - - - - - - - -
StatusCodeErrorCodesDescription
4001122
1119
1120
Store filter not specific enough
Invalid MerchantBrandId
Invalid MerchantLocationId
-
diff --git a/docs/pos/api-principles.md b/docs/pos/api-principles.md deleted file mode 100644 index bde2cd7fc..000000000 --- a/docs/pos/api-principles.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -sidebar_position: 8 ---- - -# API Principles - -This is a preliminary list of architectural principles. - -## Backend Has the Truth - -One of the architectural principles in MobilePay PoS is that the backend has the truth. This means that in a situation where certainty is required, for instance whether the payment has been approved, the app and client will have to wait for confirmation from the backend. - -## API Versus Implementation - -The API does not describe the abstractions of the underlying backend or client implementations. Instead the API serves as the joint interface for backend and frontend. The ramification for this is that both frontend and backend can move independently from the API. However, they must always support the API specification and not only support perceived details of current implementations. Any valid HTTP request must be handled appropriately by the backend and produce a useful informative HTTP response. Any valid HTTP response received in the client must be handled appropriately by the client. - -## RESTful API - -The API is defined using the RESTful principles. - -## Security Model - -The MobilePay PoS V10 API uses TLS for communication security and data integrity (secure channel between the client and the backend). The API currently uses TLS 1.2. It is the integrator's responsibility to plan for an upgrade to TLS 1.3, when TLS 1.2 is deprecated. The MobilePay PoS V10 API uses access tokens to authenticate calls from clients. After [obtaining an access token](/docs/pos/authentication), the client must send the access token in an Authorization header along with the -`client_id` as follows in all calls to the MobilePay PoS V10 API: - -````json ---header 'x-ibm-client-id: {client_id}' ---header 'Authorization: Bearer {access_token}' -```` - -## Client Versioning - -In addition to the access token which identifies the client calling the MobilePay PoS V10 API, all calls must also include the `x-mobilepay-client-system-version` header to identify the version of the client software. The Client Version (`x-mobilepay-client-system-version`) is a 3 dimensional number Major.Minor.Build. It is recommended that when the client software is updated, the client version is updated accordingly. The client version will be used by MobilePay to block versions of clients that are not [certified](/docs/pos/development-guide/verification) and/or are misbehaving. An example of misbehavior is spamming irrelevant HTTP calls that endanger fast response times for other clients. - -The three parts of the Client Version is defined as described below. - -* Major version represents major changes to the client version, perhaps representing breaking changes on the clients interfaces or representing major changes communicated to merchants. A major change requires recertification. -* Minor version represents minor changes to the client version, changes that introduces new features or a change in the way internal logic is handled. Minor version changes are perhaps not communicated to merchants. A minor change requires recertification. -* Build version represents a new build of the client, including minor bug-fixes and changes of the lowest magnitude. A new build version does not require recertification. - -Certification requirements in regard to changes to Client Version are as follows - -* Changes in major version or minor version require a new Certification. -* Changes in Build version do not require a new Certification. - -The Client Version should be added in all calls as shown below. - -````json ---header 'x-mobilepay-client-system-version: 2.1.1' -```` - -## API Responses - -The MobilePay PoS V10 API uses HTTP 2XX status codes for successful requests, HTTP 4XX status codes for failed requests that failed due to a client error and HTTP 5XX status codes for failed requests that failed due to a server error. An overview of error codes used in the V10 API is given below. - -| Status code | Description | -|-----------------------------|-------------------------------------------------------------------------------------------| -| `200 OK` | The request succeeded. | -| `204 No Content` | The request succeeded but no response was returned. | -| `400 Bad Request` | The request is syntactically ill-formed or violates [validation rules](/docs/pos/input-and-output-formats). | -| `401 Unauthorized` | [Authentication](/docs/pos/api-principles#security-model) of the caller failed. | -| `403 Forbidden` | The call was rejected due to insufficient permissions of the caller. | -| `404 Not Found` | The specified resource does not exist. | -| `409 Conflict` | The request was rejected due to the state of the underlying resource. | -| `500 Internal Server Error` | An unrecoverable internal server error occurred. | - -For most errors, the V10 API returns an error response body that includes an error code and an error description. The error response has the following structure: - -```javascript -{ - "code": "19999", - "message": "Tiny elves have invaded V10; we surrender", - "CorrelationId": "197b2e31-787d-423f-ba00-0bd1f19291df" -} -``` - -## Error Handling - -Clients integrating against the MobilePay PoS V10 API should expect intermittent errors and **must** implement suitable error handling. Errors can generally be classified into three categories: *network errors*, *server errors* and *client errors*. Network and server errors should be handled by retrying requests, while client errors should be handled by fixing the client request. - -### Network and server errors - -Network errors typically present themselves as timeouts or connections that are closed prematurely. Network errors and server errors (HTTP 5XX responses) should initially be handled by retrying requests. If errors persist despite retries, the flow should be cleaned up e.g. by cancelling. The PoS V10 API uses *idempotency* to ensure that requests can always be safely retried. Idempotency ensures that performing the same call multiple times will not cause additional state changes beyond those caused by the first call. - -For instance, if a capture call on a payment is successful on the backend, but the connection to the client is closed before the client receives the response, then it is safe for the client to retry the capture call. The second capture call will immediately return with a `200 OK` response as the capture was already completed on the first capture call. - -### Idempotency keys - -In the case of `POST` endpoints that create new resources (e.g., initiating a payment or a refund) the backend cannot determine on its own whether two requests with identical request bodies is due to a retry or a request to create two resources. The PoS V10 API thus requires the client to set an *idempotency-key* header (`X-MobilePay-Idempotency-Key`) on each request when calling the following endpoints, to allow the backend to identify retried calls: - -````json -POST /v10/payments -POST /v10/payments/prepare -POST /v10/refunds -POST /v10/pointofsales -```` - -For each call to the endpoints above, the client must generate a unique idempotency key for the given call. In case the client decides to retry a call due to a failure, the client **must** use the same idempotency key, to allow the backend to identify it as a retried call. We recommend using a client-generated *GUID* as the idempotency key. - -For instance, if a client calls to initiate a payment with a unique idempotency key, *key1*, and the initiate call is successful but the client never receives the response due to an intermittent network issue, then it is safe to retry the initiate payment call with the same idempotency key, *key1*. Because the idempotency key is the same, the second call will not initiate a new payment, but rather return the `paymentId` of the already initiated payment. - -All other endpoints in the PoS V10 API are naturally idempotent and do not require explicit idempotency keys to be set by the client. - -The PoS V10 API stores idempotency keys for at least 24 hours. If a call is retried with the same idempotency key more than 24 hours after the original call, then the PoS V10 API does not guarantee that it will be handled as a retried call. - -### Retrying requests - -We recommend retrying failed requests due to network and server errors using one of these strategies: - -* Retrying requests up to a fixed number of times with a constant delay between each call. -* Retrying requests up to a fixed number of times using an exponential backoff with jitter strategy (i.e. doubling the delay between each retried call and adding some randomness to the delay to avoid overloading the backend). - -We suggest retrying a failed request **2** times (which results in 3 requests including the first one). - -You may at **max** retry **5** times (which results in 6 requests). - -### Client errors - -Client errors (HTTP 4XX) indicate a problem with the client request and can typically not be resolved by retrying the request. HTTP 409 errors typically indicate that the client and the PoS backend is out-of-sync about the state of a given resource (e.g. trying to capture a reservation that is not yet reserved or initiating -a payment on a PoS that already has an active payment). If possible, the client should try to query the given resource to fix any inconsistencies between the client and the PoS backend. - -### Handling Timeouts - -For requests that are slow to produce responses, the client has to set a timeout on the request using one of the following rules: - -* For POST, DELETE, PUT requests set the timeout to 2 seconds using a suitable retry strategy from section [Retrying requests](/docs/pos/api-principles#retrying-requests). Remember to use the idempotency key for the POST requests that create a ressource. -* For non-polling GET requests set the timeout to 0.5 seconds using a suitable retry strategy from section [Retrying requests](/docs/pos/api-principles#retrying-requests) -* For polling GET requests set the timeout to 0.5 seconds and continue polling using the polling delay from the last received response. - -## Call Throttling - -Several flows in the PoS V10 API require the client to poll the PoS backend for state changes. To help protect against excessive polling, all endpoints used for polling in the PoS V10 API include a poll delay field to allow the backend to throttle polling calls from clients. The following polling endpoints include a `pollDelayInMs` field in the response body: - -````json -GET /v10/payments/{paymentId} -GET /v10/refunds/{refundId} -GET /v10/pointofsales/{posId}/checkin -```` - -If a response includes a `pollDelayInMs` of 1000, the client **must** wait at least 1000ms (i.e. 1 second) before polling the same endpoint. - -:::note -We recommend that clients directly use the `pollDelayInMs` response since a low polling delay can ensure a faster payment flow. -::: - -In case no response is received when querying one of the above polling endpoints, then clients should either: - -* Use the `pollDelayInMs` from the last successful call to the given endpoint. -* Continue polling using an exponential backoff with jitter strategy (i.e. doubling the delay between each retried call and adding some randomness to the delay to avoid overloading the backend). diff --git a/docs/pos/authentication.md b/docs/pos/authentication.md deleted file mode 100644 index 11fcaa25a..000000000 --- a/docs/pos/authentication.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Authentication - -The PoS V10 API uses access tokens to authenticate calls from integrator clients. In order for an integrator client to use the PoS V10 API, it must first obtain an access token using the Integrator Authentication API. The access tokens used in the PoS V10 solution identifies both an integrator client and the integrator and may optionally identify the merchant on which the client is calling on behalf of. - -## Credentials Flow - -The Integrator Authentication solution is based on the OpenID/OAuth 2.0 specification. By following the OpenID Connect protocol, MobilePay makes it easy for integrators to integrate with MobilePay. Currently, the flow supported is the Client Credentials grant type. In the Credentials Flow (defined in OAuth 2.0 RFC 6749, section 4.4), integrators pass along their `client_id` and `client_secret` (received in Step 5 above) to authenticate themselves and obtain an access token. The Credentials Flow is illustrated in the diagram below. - -[![PoS sekvens diagram](/img/pos-sekvensdiagram.png)](/img/pos-sekvensdiagram.png) - - 1. The client app authenticates with the Authorization Server using its `client_id` and `client_secret` using the token endpoint. - 2. The Authorization Server validates the `client_id` and `client_secret`. - 3. The Authorization Server responds with an `access_token`. - 4. The Client application can use the `access_token` to call the PoS V10 API. - 5. The PoS V10 API responds. - -:::note -Oauth2 client secrets should not be stored in a way, where they can be accessed by someone from outside the integrator organisation. -::: - -## Obtaining an access token - -This document only describes the token endpoint used to request an access token. A complete specification of the endpoints, responses and response codes for the Integrator Authentication API can be found in the [APIs section](https://sandbox-developer.mobilepay.dk/product). - -The token endpoint (`POST /connect/token`) is used when requesting an access token for an onboarded integrator client. The following -headers must be set: - -```json title="Headers" -Content-Type: x-www-urlencoded -Authorization: Basic (client_id:client_secret).toBase64EncodedString(). -``` - -The OAuth `client_id`and `client_secret` will be sent to the integrator in a closed zip file from [developer@vippsmobilepay.com](mailto:developer@vippsmobilepay.com) to integrators e-mail (step 4 in the [Client onboarding guide](/docs/pos/development-guide/getting-started#step-4---receive-security-credentials)). - -In addition, the `grant_type` parameter must be set and a `merchant_vat` parameter may optionally be set as described below: - -| Parameter | Value | Description | -| --- | --- | --- | -| `grant_type` | client_credentials | The Client Credentials grant type is used by clients to obtain an `access_token` outside of the context of a user. | -| `merchant_vat` | DK12345678 or FI12345678 | VAT number of the merchant the integrator client is calling on behalf of. The VAT number consists of country prefix (either FI or DK) and 8 digits. | - -If the `merchant_vat` parameter is supplied, the VAT number will be added as a claim on the access token, and it will only be possible to use the access token to perform calls on behalf of the given merchant. If it is not supplied, the access token will not be restricted to a fixed merchant. Instead, clients will have to include a header on all calls to the PoS V10 API that includes the VAT number of the merchant the client is acting on behalf of, for the given call. - -Example of response body from SandBox environment: - -```json title="Response body" -{ - "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", - "expires_in": 3700, - "token_type": "Bearer", - "scope": "integrator_scope" -} -``` - -### Expected status codes - -You might encounter the following status codes : - -* `200 - OK` -* `401 - Unauthorized` if the client is not authorized/authenticated through the API Gateway - -### cURL example - -```json title="Example" -curl --location --request POST 'https://api.sandbox.mobilepay.dk/integrator-authentication/connect/token' \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Authorization: Basic ({YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET}).toBase64EncodedString()' \ ---data-urlencode 'grant_type=client_credentials' \ ---data-urlencode 'merchant_vat=DK12345678' -``` - - **Environments:** -The following URLs are the environment routes for the Integrator Authentication API - -* SandBox: `https://api.sandbox.mobilepay.dk/integrator-authentication` -* Production: `https://api.mobilepay.dk/integrator-authentication` diff --git a/docs/pos/best-practices.md b/docs/pos/best-practices.md deleted file mode 100644 index feabceb6c..000000000 --- a/docs/pos/best-practices.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -sidebar_position: 7 ---- - -# Best Practices - -This section is an overview over best practices when integrating to MobilePay PoS. The purpose of these best practices is to optimize the customer and merchant experience, to reduce errors and to keep the integration as simple as possible without reducing customer and merchant experience. - -## Check-in before or after payment has been initiated - -While the system supports customers checking in both before or after a payment has been initiated, best practice is to urge customers to check in before. -As an example: In a supermarket a customer can check in and then start bagging their groceries. When all the groceries have been scanned the cash register will initiate the payment and allow the customer to swipe. -This is an advantage over both cash and card payments, as the customer has no need to go back to the terminal/payment area again. This results in a faster transaction for all involved parties. - -## Payment and loyalty payment flows - -There are two main payment flows in the V10 API. -Initiating a payment followed by a capture (the [Payment Flow](/docs/pos/payment-flows/payment-flow)), and a flow where initiate payment is split into two parts: Prepare-Ready and then followed by a capture (the [Prepared Payment Flow](/docs/pos/payment-flows/prepared-payment-flow)). -The recommendation is to use the Payment Flow if there is no need for knowing the customer before setting the amount. -Using the Payment Flow will save a call to the API and in the end improve the overall time it takes to complete a payment. -Cases in which knowing the customer before setting the amount includes loyalty payments where a discount is based on the customer's loyalty ID. - -## Specify planned capture delay - -It is required to specify when the payment is expected to be captured. The values are either *None*, *LessThan24Hours*, and *LessThan14Days*. These are values that control how payments are handled by MobilePay Support and it is therefore beneficial that these values are set as accurate as possible. -The three values differ in the following way: - -* **None**: If payments with this value are not captured **the following day** it is possible for MobilePay Support to reach out to make sure the payments are handled (either cancelled or captured) although this is not guaranteed. -* **LessThan24Hours**: If payments with this value are not captured **the following 2-3 days** it is possible for MobilePay Support to reach out to make sure the payments are handled (either cancelled or captured) although this is not guaranteed. -* **LessThan14Days**: If payments with this value are not captured MobilePay Support cannot help since the reservation will be expired and, hence, cannot be captured. Make sure this value is only used when appropriate. - -## Order IDs - -Order IDs are not required to be unique however this is highly recommended. -In error cases where the `paymentId` is lost it can be retrieved based on the `posId` and the `orderId` by calling the `GET /v10/payments` endpoint. If the `orderId` is unique the endpoint will return the expected `paymentId`. However, if the `orderId` is not unique the mapping is overwritten and the endpoint will return the latest `paymentId` that was associated with the specified `orderId`. - -## Capture or cancellation of old payments - -All payments in *Reserved* state should be captured or cancelled as soon as practically possible. If an error occurs that makes it temporarily impossible to neither cancel or capture the payment, the PoS client is responsible for persisting which payments should be captured and which should be cancelled at a later stage. Later when processing old payments in *Reserved* state it is important that only payments that should be captured are captured and the same in regards to payments that should be cancelled. -It is bad practice to poll for every outstanding payments that are in the *Reserved* state, since that could lead to payments being captured which should have been cancelled and vice versa. - -## Polling - -It is possible to get information on a payment using `GET /v10/payments/{paymentId}`, and it is possible to get information about an active check-in using `GET /v10/pointofsales/{posId}/checkin`. -For both of these endpoints, it is allowed to do polling at most once per second. Polling times are controlled by the backend. The response will always contain a time interval that specifies, when the endpoint should at the earliest be polled again. The recommendation is to poll as fast as allowed by the backend to ensure maximal merchant and customer experience. - -## Payment restrictions - -It is possible to restrict which card types can be used for a payment. This restriction is available in order to support that some countries have restrictions on which cards can be used for certain products. -The recommendation is to only set restrictions on payments where it is required to do so by the law or in case there are some business related reasons for restricting the payment. You can put restrictions when starting payments with either `POST /v10/payments/` or `POST /v10/payments/{paymentId}/ready`. See [Restrictions formatting](/docs/pos/input-and-output-formats#payment-restrictions) for how to provide restrictions. - -## Merchant onboarding - -When a PoS client needs to onboard a merchant to the MobilePay V10 API, the Pos client needs to know the ``storeId`` for the store they will do payments on behalf of. There are two possible ways to obtain the ``storeId`` needed. - -* **Merchant VAT number**: If the merchant that needs onboarding is a new customer for the PoS Integrator, then Merchant VAT number should be used to obtain storeIds. The PoS integrator can call ``GET /v10/stores`` and the MobilePay backend will use the VAT number to return all storeIds for that merchant. To get details about each store you can then call the endpoint ``GET /v10/stores/{storeId}`` for each ``storeId``. -* **MerchantBrandId + MerchantLocationId**: If the merchant that needs onboarding is already a customer of the PoS Integrator, then ``MerchantBrandId`` and ``MerchantLocationId`` can be used to obtain storeIds. The PoS client can call ``GET /v10/stores/?merchantBrandId={merchantBrandId}&merchantLocationId={merchantLocationId}`` for each location to get a list of storeIds that only contains the ``storeId`` for that location. This way the PoS client can avoid the process of looking up specific store data to determine which ``storeId`` represents which store. - -## Choosing a BeaconId - -There are three principles for choosing a BeaconId. - -1. If you have received a 15-digit Id from MobilePay - use that as your Id. -2. If you have an earlier GUID that you need to use because you have it printed or similar - then use that GUID. -3. Otherwise let MobilePay generate a new GUID for you everytime you create a PoS. - -Following this approach will lead to fewer issues with collisions for everyone. - -## Optimal flow - -To ensure the best costumer experience, the payment flow from a costumers point of view, ends when the payment has reached Reserved state. At this stage the customer is allowed to leave the store. diff --git a/docs/pos/create-qr-codes.md b/docs/pos/create-qr-codes.md deleted file mode 100644 index f8ce3dd7b..000000000 --- a/docs/pos/create-qr-codes.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_position: 12 ---- - -# Create QR codes - -The correct format for creating a QR code for Point of Sale is: mobilepaypos://pos?id=``beaconId``&source=qr - -## Examples - -- mobilepaypos://pos?id=123456789012345&source=qr -- mobilepaypos://pos?id=cd851cd7-8398-4a03-83c1-391a2f5cb71c&source=qr - -Note: It is the `beaconId` and **NOT** the `posId` that should be used in the URL - -Please be aware that it is all lowercase. The PoS ``beaconId`` is either a 15 digit number (no letters) or a GUID. -The format is both for sandbox and production environment. - -If you want to print the QR code we have a template for MobilePay stickers on the [MobilePay website](https://mobilepay.dk/materialebank/marketingmateriale/skilte/skiltning-til-pos) diff --git a/docs/pos/detecting-mobilepay.md b/docs/pos/detecting-mobilepay.md deleted file mode 100644 index 8d243be06..000000000 --- a/docs/pos/detecting-mobilepay.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Detecting MobilePay - -There are two ways in MobilePay PoS for a terminal/client to become aware that MobilePay has been chosen by the customer as the payment option: User activation and Notification service. - -## User activation - -This is the default way of detecting MobilePay presence. In a supermarket, this can be a button on the ECR (Electronic Cash Register) that sends the payment request to MobilePay. For example, the cashier will ask the customer or infer from the customer's actions which payment option the customer wants to choose and then push the MobilePay button. Another example of user activation is when the customer can choose MobilePay themselves on a keypad placed on a vending machine. Some vending machines only allow MobilePay to be used and therefore any request for the vending machine product would be inferred as a payment request to MobilePay. - -[MobilePay button](/img/pos-MobilepayButton.png) - -A last example of a user activation is in the case of a QR code being displayed in a terminal. Once the QR code is displayed, -the terminal may start polling the endpoint `GET /v10/pointofsales/{posId}/checkin` to determine if a customer has checked in. The terminal may only poll for a check-in while the QR code is displayed on the terminal to ensure the check-in endpoint is not overloaded with requests. - -[Polling](/img/pos-polling.png) - -## Notification service - -Some interfaces do not include a possibility for user activation. In these cases an endpoint can be exposed by the MobilePay PoS integrator. This endpoint will be called with a check-in notification when a customer checks in. After receiving a notification the client can poll the `GET /v10/pointofsales/{posId}/checkin` endpoint for that PoS. For more details see [Notification Service](/docs/pos/notification-service). - -[Beacon](/img/pos-BeaconIDRead.png) diff --git a/docs/pos/development-guide/_category_.json b/docs/pos/development-guide/_category_.json deleted file mode 100644 index 7d1a58a2b..000000000 --- a/docs/pos/development-guide/_category_.json +++ /dev/null @@ -1 +0,0 @@ -{ "label": "Development Guide", "position": 1 } diff --git a/docs/pos/development-guide/development-guide.md b/docs/pos/development-guide/development-guide.md deleted file mode 100644 index f395b2f54..000000000 --- a/docs/pos/development-guide/development-guide.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Development Guide - - diff --git a/docs/pos/development-guide/getting-started.md b/docs/pos/development-guide/getting-started.md deleted file mode 100644 index c8f48cf4c..000000000 --- a/docs/pos/development-guide/getting-started.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -sidebar_position: 1 ---- - -:::caution Closed - -It is no longer possible to onboard MobilePay PoS. The product have been replaced with [ePayments API](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/) -::: diff --git a/docs/pos/development-guide/production.md b/docs/pos/development-guide/production.md deleted file mode 100644 index c00d7eaec..000000000 --- a/docs/pos/development-guide/production.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Production - -After certification you will be able to use the production API and start onboarding your merchants to PoS. In this section you will find guidance and recommendations for production. - -## Onboard production merchants - -In order to start using the production API two things must be in place: - -* Completed self-certification with production clientId -* Received production security credentials - -For more information about this please visit the [self-certification site](/docs/pos/development-guide/verification). - -When above topics are completed you can start to onboard your first merchant in production. We recommend that you select a pilot merchant to ensure that the integration is functional. Afterwards you can continue with a gradual role out. -If you are migrating from an earlier PoS version we also recommend to start the migration with a test merchant and then gradually migrate the remaining merchant base. We strongly recommend that you enable a roll back option to the former version in case of issues. - -In the GitHub documentation you can find a section on how to onboard merchants under [Point-of-Sale management](/docs/pos/pos-management). If your merchants does not yet have a PoS solution use the 'No existing solution'. If your merchants already have an existing PoS solution use the 'Existing solution'. - -## Merchant support - -We distinguish between two types of support: business support and solution/technical support. Below defines who is responsible for what. - -* **Business support**: If a merchant needs support during the business onboarding to MobilePay or afterwards needs support in regards to business related topics such as change of bank account, transfers etc. they can contact our Business Support. Contact information can be found [here](https://mobilepay.dk/hjaelp/mobilepay-til-erhverv#kontakt). -If merchant needs assistance in regards to business onboarding to your solution they should contact integrator. - -:::tip -Be sure to inform and train your sales and support team on the onboarding process for your system. Our business support will assist the merchants with the MobilePay onboarding, but they cannot support the merchants when onboarding your system. Therefore it is important that your sales and support team are properly trained to do so. -::: - -* **Solution/technical support**: If a merchant needs support or encounter issue with the PoS solution integrator is responsible for 1st level support. If integrators investigation shows and issue with MobilePay services they can contact Developer Support at developer@vippsmobilepay.com with relevant information and we will investigate the issue. -Please do not advise merchants to contact us directly as they cannot provide the needed details and are usually not familiar with the technical integration. This also applies to subcontractors and resellers. The support communication must be handled directly between MobilePay Developer Support and integrator. - -## Integrator support - -For ongoing technical support, technical questions or feature requests integrators can always contact Developer Support at developer@vippsmobilepay.com. The Developer Support team will review the request and respond as soon as possible, usually within a business day. - -When contacting Developer Support please include as many details as possible relevant to the request. If it concerns a specific issue or bug please include the following and any other details that can be relevant: - -* Merchant vat number -* StoreId -* posId -* BeaconId -* PaymentId -* Timestamp for error -* Error responses -* Screenshot if error in app -* Any logs that can be relevant to the issue - -:::tip -Sign up for our operational mail list to be informed about any operational issues concerning PoS v10. Just contact developer@vippsmobilepay.com in order to be added to the mail list. -::: - -## Confirmation screen - -Details on the confirmation screen is important in order to ensure a good user experience and improve conversion rate. We highly recommend to use input that is recognisable by the user to avoid any uncertainties in the checkout experience. - -PoS confirmation screen - -* Logo: Is highly important as this is the most recognisable by the user. The logo is used for all stores under this the brand. This is uploaded by the merchant in our self-service portal -* Merchant brand name: This is the name of the brand used when creating the store. The brand name is shown for all stores using this brand. It is set by the merchant in our self-service portal -* Store: This is the name of the store. The name is only used on this specific store. It is set by the merchant in our self-service portal -* PoS name: This is the name of the specific PoS set when integrator created the posId through the API: POST /v10/pointofsales - "name" - -Self-service portal: [DK](https://admin.mobilepay.dk/) | [FI](https://admin.mobilepay.fi/) - -## Design guidelines - -We want to make it easy for you to ensure that the right MobilePay buttons and logo's are used by the merchants. Proper use of our logo and buttons will ensure better user experience and conversion rate. -Please visit our [Design page](https://developer.mobilepay.dk/design) for more information and ressources. - -We also have guidelines and templates for signs and stickers which can be found [here](https://www.mobilepay.dk/materialebank/marketingmateriale/skilte/skiltning-til-pos). diff --git a/docs/pos/development-guide/test.mdx b/docs/pos/development-guide/test.mdx deleted file mode 100644 index 3bcdefe85..000000000 --- a/docs/pos/development-guide/test.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -sidebar_position: 2 ---- - -import Tabs from "@theme/Tabs" -import TabItem from "@theme/TabItem" -import TestApp from '/docs/shared-blocks/_test-app.mdx'; - -# Test - -In this section, you can find information on testing, and our test ressources. To ensure a good user experience, we recommend you to test your solution thoroughly before certification and launch. - -## MobilePay PoS Sandbox Environment - -We have provisioned a sandbox environment for integration purposes The environment is the same bits and bytes as the production environment, with a few exceptions: - -* No actual payments and reservations are made. The payment backend have been mocked, and the transactions are kept in sandbox storage. This means that transactions won’t be visible in the test app activity list, and no app notifications are sent. -* Loyalty card system is also mocked, and static loyalty card information is returned when applicable - -**Audience**: The test environment is meant for PoS integrators to be able to test integrations against the MobilePay PoS platform. It is an isolated environment that behaves as in live production, thus enabling PoS integrators to fully test the PoS API and business logic. - -**Background**: The environment is strictly meant for carrying out tests and development tasks towards certification. - -**The API**: The Merchant API in the sandprod environment is identical to the live production API. - -To complete a payment flow in the sandprod environment you will need to make user actions. To do so you have to options: - -* User simulation API: The API mimick the actions of a user and allows you to check in on a beaconId, accept and cancel a payment. -* Test app: This version of the MobilePay app is similar to the live version, but only supports payments in the sandprod environment. - -## Test app - - - -## User simulation API - -To complete a payment flow in the sandprod environment you will need to make user actions. We have made an API that can mimick the actions of a user. You find it in the [API documentation](/api/pos#tag/User-Simulation). - -With the API you can do the following: - -* Perform a check in on a beaconId -* Accept a payment -* Cancel a payment - -You must subscribe to the User simulation API, before you can use it. When calling the API, you must supply: - -|Input| Source| -|--|--| -|**BeaconId**|Created through the PoS API| -|**Phonenumber**|See below list of test users| - -### How to use the User simulation API - -1. Perform a check in on a beaconId: `POST /app/usersimulation/checkin` -2. Initiate a payment through the PoS API: `POST /api/v10/payments` - * Accept the payment: `POST /app/usersimulation/acceptpayment` - * Cancel payment: `POST /app/usersimulation/cancelpaymentbyuser` - -To perform a check in and payment accept, you must supply a phone number for a test user. Below you find a list of test users with different features. - -## Test user - -When using the test app or user simulation API, you must use a test user. Below you can find a list of user ids for Denmark and Finland. If there is an issue with a test user please contact us. These test users are only to be used for for MobilePay PoS test. If you need a test user for a different product please visit the relevant product pages for more information or contact us at developer@vippsmobilepay.com - -:::caution -Below users are shared amongst all PoS integrators and receipts for all test transactions are visible in the activity list. Please note that the PoS name (defined in CreatePosRequest) is visible on the receipt. Therefore do not include any sensitive or confidential data in the PoS name. -::: - - - - - -|Phone number|PaymentSource|Feature| -|--|--|--| -|+45 20031801|Credit|Credit card| -|+45 20031802|Debit|Debit card| -|+45 20031803|Credit|Credit card| -|+45 20031804|Credit|Loyalty| -|+45 20031805|Credit|Partial capture| - - - - - -|Phone number| PaymentSource|Feature| -|--|--|--| -|+358 200318001|Credit|Credit card| -|+358 200318002|Debit|Debit card| -|+358 200318003|Credit|Credit card| -|+358 200318004|Credit|Loyalty| -|+358 200318005|Credit|Partial capture| - - - diff --git a/docs/pos/development-guide/verification.md b/docs/pos/development-guide/verification.md deleted file mode 100644 index 3cc6ceb22..000000000 --- a/docs/pos/development-guide/verification.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Self-certification - -After your test is complete you must complete a self-certification in order to get access to the production API and go live with your integration. MobilePay provides an automatic certification process where it is possible for most integrators to create a fully automated self-certification. The certification concludes with an automated report on how the certification went. For the PoS API all Major and Minor versions of clients must be certified. - -## Access to self-certification - -Before you can start self-certification you must have a signed agreement with MobilePay and receive a production clientId. -When your test is completed and you wish to start self-certification please [contact Developer support](mailto:developer@vippsmobilepay.com) to request production security credentials that will include the production clientId needed for the certification. - -:::info Note -Production security credentials are not to be used for self-certification because this is performed in sandbox. Therefore you must use your security credentials from sandbox. The production security credentials should be used for production after self-certification. -::: - -## Self-certification process - -The Self Certification process has four steps: Identification, Selection, Certification and Approval. - -:::note -The bottom of this page contains configuration details for your client. You will need to use our self certification store, merchant and URL instead of your test credentials. -::: - -### Identification Step - -In the first step the Integrator identifies themselves in the tool. The following information is needed: - -* Client IDs for Sandproduction and Production - ID created on the MobilePay Developer Portal which identifies the client to be certified. Each Integrator is allowed to create multiple Client IDs, however it is also acceptable to have just one Client ID. -* Version numbering - The three dimensional number that defines the version of the Client that needs to be certified. See [Client Identification](/docs/pos/api-principles#client-versioning) -* Client system name - the name of the software being certified. - -[![Identification step](/img/pos-identificationstep.png)](/img/pos-identificationstep.png) - -### Selection Step - -In the second step the Integrator selects which major features to certify. There are the following major features in MobilePay PoS API v10: - -* Onboarding - The mandatory proces of creating a Point-of-Sale on the MobilePay backend. -* Payments - Certification in sections of the API necessary for doing a simple payment. -* Prepared payments - Certification in sections of the API necessary for doing a prepared payment. -* Payments with restrictions - Certification in sections of the API necessary for handling restrictions to payments. -* Prepared payments with restrictions - Certification in sections of the API necessary for handling restrictions to prepared payments. -* Refunds - Certification in sections of the API necessary for handling refunds. - -[![Categories step](/img/pos-categories_step.png)](/img/pos-categories_step.png) - -### Certification Step - -In the third step the integrator goes through all the different certification cases necessary using their client. In this step it might be necessary to operate the client to go through the different steps of a certification case. - -[![Onboarding cases](/img/pos-onboarding-cases.png)](/img/pos-onboarding-cases.png) - -### Approval step - -In the fourth and final step the Integrator gets a certificate proving that the client is certified. It is now possible for the client to access production. - -In general, we urge all integrators to use this tool to do continuous testing. It is a requirement to re-certify when upgrading major or minor versions. We also recommended to use the tool when making new build versions. The tool will never retract a certification from a client version that has already been certified. Retraction of a certification will only be done after an individual evaluation by MobilePay based on input from production. - -[![Approval step](/img/pos-approvalstep.PNG)](/img/pos-approvalstep.PNG) - -### Configuration details - -Please use the following data for configuring your client before commencing self certification. - -| Self Certification info | | -|---|---| -| Website link | [https://pos-certification.mobilepay.dk/mobilepay-pos-selfcertification-website/index.html](https://pos-certification.mobilepay.dk/mobilepay-pos-selfcertification-website/index.html) | -| PoS self-certification API base URL | [https://api.sandbox.mobilepay.dk/pos-self-certification-api/pos/v10](https://api.sandbox.mobilepay.dk/pos-self-certification-api/pos/v10) | -| Integrator Authentication API base URL | [https://api.sandbox.mobilepay.dk/integrator-authentication](https://api.sandbox.mobilepay.dk/integrator-authentication) -| merchantLocationId | 00001 | -| merchantBrandId | MPPOSCERT1 | -| VAT number DK | 90000028 | -| VAT number FI | 90000040 | diff --git a/docs/pos/glossary.md b/docs/pos/glossary.md deleted file mode 100644 index 1355b575d..000000000 --- a/docs/pos/glossary.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -sidebar_position: 14 ---- - -# Glossary of Terms - -| Term | Description | -|------|-------------| -| Client | Client and terminal are used interchangeably for the application that calls the MobilePay PoS API. Client is often used when only discussing the software.| -| Terminal | Terminal and client are used interchangeably for the application that calls the MobilePay PoS API. Terminal refers to the setup where the application is running on a dedicated payment terminal.| -| Customer | The customer is the user who wants to pay for goods and services with MobilePay. | -| ECR | The electronic cash register is an application running on hardware in a shop. The ECR is an application that calls the MobilePay PoS client. | -| Integrator | The company that develops the client and calls the MobilePay PoS API on behalf of the merchant. Sometimes the merchant acts as integrator. Used interchangeably with PoS vendor.| -| Merchant | The merchant is the company that wants to receive payments for goods and services from MobliePay users.| -| Payment | A payment request from the merchant.| -| Prepared payment | A payment request from the merchant, where the merchant has the opportunity, to provide information to the user and/or to receive information about the user, before providing the final amount.| -| Reservation | A reservation is a pre-authorization which guarantees that the user has sufficient funds to pay for the given transaction. | -| Capture | Capture is the process by which payments are secured once the payment has been authorized, i.e. a reservation has been made.| -| PoS | In common language a point-of-sale might mean an Electronic Cash Register. In MobilePay PoS, a point-of-sale is an abstraction that describes a place where a payment can occur and therefore NOT a synonym for ECR. The distinction is subtle but important.| -|Check-in| Customer action performed in order to initiate payment. This could be scanning a QR code or connecting to a terminal.| -| PoS vendor | The company that develops the client and calls the MobilePay PoS API on behalf of the merchant. Sometimes the merchant acts as vendor. Used interchangeably with integrator.| -| VAT-number | In Denmark, this is the CVR-number. In Finland, this is the Y-tunnus. Both refer to the official business ID.| diff --git a/docs/pos/input-and-output-formats.md b/docs/pos/input-and-output-formats.md deleted file mode 100644 index 15f900195..000000000 --- a/docs/pos/input-and-output-formats.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -sidebar_position: 11 ---- - -# Input and Output Formats - -This page gives an overview of the format and length restrictions for all input parameters used in the PoS V10 API. - -## HTTP Headers - -For more information about the http headers, see [API principles](/docs/pos/api-principles). - -| Name | Format | Description | -|------|-------------|-------------| -| `x-ibm-client-id` | Guid | Identifies an application created through MobilePay Developer Portal. | -| `x-mobilepay-merchant-vat-number` | Valid VAT number: IsoCountryCodeVATNumber - Example: DK12345678 | Identifies the merchant the integrator is calling on behalf of | -| `x-mobilepay-client-system-version` | Valid Client-Version: Major.Minor.Build - Example: 1.2.1 | Identifies the [version of the integrator system](/docs/pos/api-principles#client-versioning) calling the API. | -| `x-mobilepay-idempotency-key` | String with at most 36 valid characters | Used to allow calls to be [safely retried](/docs/pos/api-principles#error-handling) in case of errors. | - -## Brands - -For more information about brands, see [PoS Management](/docs/pos/pos-management). - -| Name | Format | Description | -|------|-------------|-------------| -| `merchantBrandId` | MPPOSXXXXX
POSDKXXXXX
POSFIXXXXX | Identifies a Brand in MobilePay. | -| `brandName` | String | The name of the brand. | - -## Stores - -For more information about stores, see [PoS Management](/docs/pos/pos-management). - -| Name | Format | Description | -|------|-------------|-------------| -| `storeId` | Guid | Identifies a Store in MobilePay. | -| `merchantLocationId` | String with exactly 5 valid characters | MobilePay location ID. Together with a `merchantBrandId`, this identifies a Store in MobilePay. | - -## Point-of-Sales - -For more information about a PoS, see [PoS Management](/docs/pos/pos-management). - -| Name | Format | Description | -|------|-------------|-------------| -| `posId` | Guid | Identifies a PoS in MobilePay. | -| `merchantPosId` | String with at most 36 valid characters | Merchant defined PoS ID. There can be at most one active PoS with a given `merchantPosId` for a given integrator and merchant. | -| `posName` | String with at most 36 valid characters | Merchant defined PoS name.< The name is visible in the app, after the customer has checked in on the PoS. | -| `callbackAlias` | String with at most 36 valid characters | Only for clients that use the [notification service](/docs/pos/notification-service) to detect MobilePay payments. The `callbackAlias` is a key that identifies which notification endpoint to call for the given PoS. | -| `beaconId` | A GUID or 15 digits | ID of the Beacon. In case of physical device such as the MobilePay WhiteBox or a terminal the `beaconId` is a 15 digit string. In case of no physical device (QR) the `beaconId` is not provided during PoS creation. MobilePay will generate a string containing a random GUID as the `beaconId`. | -| `requirePaymentBeforeCheckin` | Boolean | When set to `true`, a user will not be allowed to check-in before a payment is created on this PoS. See [Preventing checkin before payment](/docs/pos/pos-management#preventing-checkin-before-payment). -| `supportedBeaconTypes` | `QR` / `NFC` / `Bluetooth`| Beacon broadcast type. Identifies an option for how a customer can check in on a PoS. During the creation of a PoS, a list of Beacon Types has to be provided. | - -## Payments - -For more information about payments, see [Payment Flows](/docs/pos/payment-flows). - -| Name | Format | Description | -|------|-------------|-------------| -| `paymentId` | GUID | MobilePay defined Payment ID. | -| `orderId` | String with at most 36 valid characters | Merchant defined payment order ID. There is no uniqueness requirement for the `orderId`, but it is highly recommended to use unique order IDs. | -| `amount` | Valid positive amount | Total amount of the payment. | -| `currencyCode` | `DKK` / `EUR` | Currency code for the currency of the payment. | -| `merchantPaymentLabel` | String with at most 36 valid characters| Label for the payment. This is a way for the merchant to tag a payment with a label that will be visible in the transaction reporting section on the MobilePay Portal | -| `plannedCaptureDelay` | `None` / `LessThan24Hours` / `LessThan14Days`| How long time the client expects to wait after receiving a reservation before capturing. See [Specify planned capture delay](/docs/pos/best-practices#specify-planned-capture-delay). | -| `restrictions` | Json object with one or more parameters | A way to define restrictions on how a payment can be completed. See [Payment Restrictions](/docs/pos/input-and-output-formats#payment-restrictions) for possible restriction parameters | - -### Payment Restrictions - -| Name | Format | Description | -|------|-------------|-------------| -| `debitCardDisallowed` | Boolean | When `debitCardDisallowed` is set to true, debit cards cannot be used for this payment | -| `creditCardDisallowed` | Boolean | When `creditCardDisallowed` is set to true, credit cards cannot be used for this payment | - -## Valid characters - -Valid characters for PoS V10 API request fields are: - -* 0 - 9 -* a-zA-Z -* æÆøØåÅ -* äÄöÖšŠžŽâÂàÀáÁãÃéÉêÊëËèÈíÍîÎïÏìÌüÜûÛùÙúÚôÔòÒóÓõÕÿýÝñÑ -* !"#$%&'()*+,-./":;<=>?@[\]^_\`{\|}~¦¯¨´× -* «»ðþçߤǵÐÞ±°ªº©§¶¼½¾¬®¢£¥¡¿¹²³ -* (space) diff --git a/docs/pos/notification-service.md b/docs/pos/notification-service.md deleted file mode 100644 index e4803d4da..000000000 --- a/docs/pos/notification-service.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Notification Service - -Clients that are unable to detect whether a customer has checked in by [user activation](/docs/pos/detecting-mobilepay#user-activation) can use the notification service. To be able to use the notification service, the integrator needs to implement an endpoint that MobilePay will call, when a client should query the active check-in on a PoS. - -When the endpoint is implemented the URL has to be communicated to MobilePay in order to validate and whitelist it in the firewalls. This is done by sending an email to [developer@vippsmobilepay.com](mailto:developer@vippsmobilepay.com). When the URL is whitelisted the integrator will receive a reference to that URL called a ``CallbackAlias``. The client will use this alias when [creating a PoS](/docs/pos/pos-management#pos-creation) to indicate which notification endpoint to call. - -## Notification endpoint - -The requirements for a notification endpoint are as follows: - -* It must be an HTTPS POST endpoint. -* It must accept a JSON body that has the following format: - -```javascript -{ - "MerchantId" : "622d3369-f940-4921-93eb-c8fca0c081b4", - "MerchantBrandId" : "MPPOS12345", - "MerchantLocationId" : "12345", - "MerchantPosId" : "MobilePay Merchant Pos Id" - "PosId" : "7e6acbde-345e-4641-b2f4-d8df0f3a5147" -} -``` - -* The format of the different fields can be found [here](/docs/pos/input-and-output-formats). - -* The notification endpoint must respond with status code `200 OK` when the notification is processed successfully. The MobilePay notification service will retry notification calls in case of any other response than `200 OK`. The service will retry the call 3 times. - -## Migrating to a different notification endpoint - -In case an existing PoS has to be migrated to use a different notification, the integrator will have to contact MobilePay by writing an email to [developer@vippsmobilepay.com](mailto:developer@vippsmobilepay.com) asking for the change. The new URL will have to go through validation and whitelisting as described above. -This included changing the mapping between the URL and the existing `CallbackAlias`. Close collaboration on the time of switching the URL is important to make sure the new endpoint is ready to receive notifications at the time of the change. diff --git a/docs/pos/payment-flows/_category_.json b/docs/pos/payment-flows/_category_.json deleted file mode 100644 index 5d197a923..000000000 --- a/docs/pos/payment-flows/_category_.json +++ /dev/null @@ -1 +0,0 @@ -{ "label": "Payment Flows", "position": 4 } diff --git a/docs/pos/payment-flows/cancel-flows.md b/docs/pos/payment-flows/cancel-flows.md deleted file mode 100644 index afb0d14e3..000000000 --- a/docs/pos/payment-flows/cancel-flows.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Cancel Flows - -The V10 API supports cancelling of payments and refunds. - -## Cancelling Payments - -A payment is cancellable by the client until the state has changed to *Captured* or *ExpiredAndCancelled*. Furthermore, a payment can be cancelled by the customer when the payment is in state *Paired* or *IssuedToUser*. -Payments can be cancelled by calling the endpoint `POST /v10/payments/{paymentId}/cancel`. It requires the `paymentId` of the payment to be cancelled. When the payment has been cancelled the state transitions to *CancelledByClient*. -If the customer cancels the payment the state will transition to *CancelledByUser*. - -The diagrams below show the sunshine scenarios for a payment cancelled by the client and a payment cancelled by the customer, respectively. -When the client cancels the payment a notification is sent to the app. The app returns to the pay screen with a message saying that the payment was cancelled by the shop. - -Cancel by client - -When the customer cancels the payment the app will show a message saying that the payment was cancelled. The status of the payment when queried will be *CancelledByUser*. - -Cancel by user - -The cancel funtionality can be used in various scenarios. It could be that the customer changed their mind about paying with MobilePay or that something in the request was not correct (maybe the customer added another item after the payment was initiated). In these cases the cancelling of the payment is straight forward and as shown in the diagrams above. - -The cancel functionality can also be used in case of non-sunshine scenarios. -It could be if the call to initiate a payment is faulty or if the client never receives the response. In this case the client should either retry the call (as described in [Error Handling](/docs/pos/api-principles#error-handling)) or the client could try to get the `paymentId` by the `orderId` and cancel afterwards. - -## Cancelling Refunds - -A client can end up in situations, where the status of a refund is not known e.g. in cases, where parts of the solution is down, or there are network issues. In these cases, it is important, that the client retains information about refunds, that have been requested. It is then possible for the client to follow up on whether the refund should be cancelled or captured. Examples for either cancel or capture could be: In the case of cancel - the customer has received refund in cash instead. In the case of capture - the customer has left the store with information that the payment will be refunded. - -A refund is cancellable until it reaches one of the states *CancelledByMobilePay*, *Captured* or *ExpiredAndCapturred*. Refunds can only be cancelled by the client since there is no customer involved in the process. A refund can be cancelled by calling the endpoint `POST /v10/refunds/{refundId}/cancel`. It requires the id of the refund that was returned when the refund was initiated. -When the refund has been cancelled the state transitions to *CancelledByClient*. - -Cancel refund by client \ No newline at end of file diff --git a/docs/pos/payment-flows/partial-capture.md b/docs/pos/payment-flows/partial-capture.md deleted file mode 100644 index 41eb6554a..000000000 --- a/docs/pos/payment-flows/partial-capture.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Partial Capture - -It is possible for all merchants to capture partial amounts in the API. MobilePay do however have to comply with card scheme rules which means that when a payment is done using an underlying card, some payments will not be possible to partially capture. To solve this every payment in *Reserved* state will contain information about whether or not it is possible to capture a partial amount on the payment. The information is presented in a flag `PartialCapturePossible` that will be set to either `true` or `false`. -Based on the value of this flag, a mechant/integrator must choose to proceed with or cancel the payment before delivering the goods to the customer. - -Here is the flow where partial capture is possible. - -Partial capture - -Here is the flow where partial capture is not possible and hence the payment needs to be cancelled. - -Partial capture cancel \ No newline at end of file diff --git a/docs/pos/payment-flows/payment-flow-error-handling.md b/docs/pos/payment-flows/payment-flow-error-handling.md deleted file mode 100644 index 7b2fb301d..000000000 --- a/docs/pos/payment-flows/payment-flow-error-handling.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Payment Flow Error Handling - -Of all the ways a payment flow can fail, there are some error scenarios related to initiating payment flows that the client needs to focus on. The following sections describes how to handle payment-in-progress errors and how to handle payments hanging in the *Reserved* state. - -## Payment in progress error handling - -In the case of an unexpected restart of the client where the payment flow cannot be continued it might be necessary to cancel the active payment since there can be only one active payment on a PoS. If the ``paymentId`` of the active payment is lost it can be retrieved by calling ``GET /v10/payments`` using the ``posId`` and `orderId`. When the `paymentId` is retrieved the payment can be cancelled and the PoS is now ready for a new payment flow. A sequence diagram showing how to handle a payment-in-progress error is shown below. - -Initiate payment error - -## Hanging payments in reserved state - -The client is responsible for persisting if a reserved payment should be cancelled or captured. In case the client gets a timeout (or other errors resulting in failed calls) trying to either call capture or cancel on a payment, it is crucial that they persist whether the payment should be captured or cancelled so they can try again later. - -It is required of the client to implement a periodically scheduled job of running through all their payments left in *Reserved* state, and try to either cancel or capture it. A sequence diagram of this flow is shown below. It is the responsibility of the client to keep track of the payments left in *Reserved* state. - -Payment capture cancel diff --git a/docs/pos/payment-flows/payment-flow.md b/docs/pos/payment-flows/payment-flow.md deleted file mode 100644 index 9f39d63e0..000000000 --- a/docs/pos/payment-flows/payment-flow.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Payment Flow - -The payment flow makes the payment ready for customer approval immediately upon creation. The sequence diagram below illustrates a sunshine scenario for a payment flow. - -The customer checks in on the PoS and receives information about the store on his device. Then, the client initiates a payment on the PoS which is immediately ready for approval and issued to the customer. The payment is now in the *IssuedToUser* state and will remain there until the customer accepts the payment and the payment amount has been reserved. At that point the payment will transition to the *Reserved* state. In this state, the payment can be cancelled or captured by the client resulting in the payment state transitioning to either the *Cancelled* or *Captured* state, respectively. - -[![PaymentAfterCheckIn](/img/pos-PaymentFlow-PaymentAfterCheckIn.png)](/img/pos-PaymentFlow-PaymentAfterCheckIn.png) - -It is also possible to initiate a payment on a PoS without an active check-in, as shown in the sequence diagram below. In this case the payment state starts out as *Initiated* and remains in that state until a customer is paired with the payment through a check-in. At that point the payment request is immediately issued to the customer and the state of the payment transitions to *IssuedToUser*. The rest of the flow proceeds in the same way as the scenario above. - -[![PaymentBeforeCheckIn](/img/pos-PaymentFlow-PaymentBeforeCheckIn.png)](/img/pos-PaymentFlow-PaymentBeforeCheckIn.png) - -## Payment States for the Payment Flow - -The diagram below shows all the possible states and transitions for a Payment flow. A payment can be cancelled by the customer until the customer has accepted the payment and the payment amount has been reserved. A payment can be cancelled by the client until it is captured or expires. After a payment has been captured, it can be [refunded](#refunds), but can no longer be cancelled. A payment expires if it is neither cancelled nor captured within the lifetime of the reservation which is 7 days. If a payment expires, the state transitions to *ExpiredAndCancelled*. -A payment in the *Initiated* or *IssuedToUser* state can also be cancelled by MobilePay if it has been inactive for too long or an error occurs while reserving the payment amount on the customer's card or account. If a payment is -cancelled by MobilePay the state transitions to *CancelledByMobilePay*. The Payment states *Initiated* and *IssuedToUser* are called *active* states and will block further payments on the same Point-of-Sale. - -PoS confirmation screen diff --git a/docs/pos/payment-flows/payment-flows.md b/docs/pos/payment-flows/payment-flows.md deleted file mode 100644 index 0183b6756..000000000 --- a/docs/pos/payment-flows/payment-flows.md +++ /dev/null @@ -1,10 +0,0 @@ -# Payment overview - -The MobilePay PoS API exposes two separate flows for payments which are documented in this section: - -* [Payment flow](/docs/pos/payment-flows/payment-flow) -* [Prepared payment flow](/docs/pos/payment-flows/prepared-payment-flow) - -All payments must be explicitly captured by the client after the customer has approved the payment. The capture amount can be for the full or a partial amount (if allowed on the payment). - -For a client to start a payment flow, the client first has to detect that a customer is present, ready and willing to pay. In the following descriptions of payment flows it is assumed that the client has already detected a customer. How to detect a customer wanting to pay with MobilePay is described in the [Detecting MobilePay](/docs/pos/detecting-mobilepay) section. diff --git a/docs/pos/payment-flows/prepared-payment-flow.md b/docs/pos/payment-flows/prepared-payment-flow.md deleted file mode 100644 index 8a53f7a1b..000000000 --- a/docs/pos/payment-flows/prepared-payment-flow.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Prepared Payment Flow - -The prepared payment flow makes the payment accessible to the customer on creation, pending an amount. Only when the payment is readied will the customer be able to make the approval. - -As an example, this flow could be used to start a payment before the payment amount is known. This could for instance be because goods are still being scanned at a cash register or to support loyalty flows. - -The sequence diagram below illustrates a sunshine scenario for a prepared payment flow. - -A prepared payment starts out in state *Prepared* and remains in this state until the payment is paired with a customer through a check-in. Once paired, the state transitions to *Paired*. Subsequently, polling of the payment can be done to retrieve a potential loyalty token. Once the payment is ready for customer approval, the client marks the payment as *Ready* and provides the payment amount. The payment is then issued to the customer and the payment state changes to *IssuedToUser*. Once the customer accepts the payment request and the payment amount has been reserved, the payment state transitions to the *Reserved* state. In this state, the payment can be cancelled or captured by the client resulting in the payment state transitioning to either the *CancelledByClient* or *Captured* state, respectively. - -[![ReservationPrepareFlow](/img/pos-ReservationPrepareFlow.png)](/img/pos-ReservationPrepareFlow.png) - -## Payment States for the Prepared Payment Flow - -The diagram below shows all the possible states and transitions for a prepared payment flow. The "Prepared Payment Flow" state diagram expands upon the ["Payment Flow" state diagram](/docs/pos/payment-flows#payment-states-for-the-payment-flow) by adding two additional states, *Prepared* and *Paired*. The client and MobilePay can cancel a prepared payment. The customer can cancel a paired payment. The Payment states *Initiated*, *Prepared*, *Paired* and *IssuedToUser* are called *active* states and will block further payments on the same Point-of-Sale. - -[PoS confirmation screen](/img/pos-prepared-payment-states.png) diff --git a/docs/pos/payment-flows/refunds.md b/docs/pos/payment-flows/refunds.md deleted file mode 100644 index ac61501e0..000000000 --- a/docs/pos/payment-flows/refunds.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Refunds - -Once a payment is captured, the payment amount is immediately charged from the customer. Therefore, the payment can no longer be cancelled. Instead, the payment amount can be transferred back to the customer, by performing *refunds*. Each captured payment can be refunded multiple times with the restriction that the sum of the refunds cannot exceed the captured payment amount. A payment can be refunded up to 90 days after the payment was captured. After 90 days a refund is no longer possible with MobilePay. - -A refund can be executed if the store payment balance contains enough money to cover the refund. If the balance doesn’t cover the amount of the refund, the refund will fail with error code 1368 - -The sequence diagram below shows a sunshine scenario for a refund. Initiating a refund yields a `refundId` that can be used to capture the refund. A refund starts out in the *Initiated* state and transitions to the *Reserved* state when the refund has been reserved as shown in the state diagram below. Once a refund has been reserved, the client can choose to capture the refund, transitioning the state to *Captured*. When a refund is captured, the refunded amount is immediately transferred to the customer and the customer will be able to see the refund in the activity list. -A refund reservation will expire and be automatically captured after 24 hours. - -Refund flow - -Until the refund has been captured, the client can also choose to cancel the refund. The diagram below shows the possible states and transitions for a refund. - -Refund states - -To refund a payment, the client needs to provide the paymentId of the payment to be refunded. In case the paymentId has been lost it can be retrieved by calling `GET /v10/payments?orderId={orderId}&state=Captured` with the orderId from the payment to be refunded. diff --git a/docs/pos/pos-management.md b/docs/pos/pos-management.md deleted file mode 100644 index d62440380..000000000 --- a/docs/pos/pos-management.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -sidebar_position: 5 ---- - -# Point-of-Sale Management - -The Point-of-Sale (PoS) represents the contact point between a customer wanting to pay with MobilePay and the merchant. -To initiate a MobilePay payment it is necessary to first create a PoS. - -## Onboarding - -Each PoS belongs to a *Store* which belongs to a *Brand*. A brand can be thought of as a combination of a name and a logo. An example of a brand could be 7-Eleven in Denmark or K-Market in Finland. Each brand consists of one or more stores. A store is the representation of a merchant's shop. It contains a `storeId` as well as the name and the address of the shop. When a MobilePay customer checks in on a PoS they will see the brand logo and name as well as the shop name in the app, which helps the customer confirm that they have in fact checked in where they intended. -When an integrator needs to onboard a PoS they need the `storeId` to create all the PoSes on that store. The `storeId` will therefore have to be persisted in an application configuration file for subsequent calls to the V10 API. There are generally two ways to acquire the `storeId`. The recommended option depends on the merchant being a migrated merchant or not. The two different approaches are described below. - -### No existing solution - -When an integrator is building a new integration for a merchant they need to know the store to which the PoS should be created. The goal is to get a list of all the stores that belongs to a merchant and then use the `storeId` from the appropriate store to create the PoS. First the integrator needs to call `GET /v10/stores` without any query parameters and the endpoint will return all the `storeId`s based on the Merchant VAT either provided in the `x-mobilepay-merchant-vat-number` header or provided in the access token (see [Authentication](/docs/pos/authentication#obtaining-an-access-token)). Then the integrator will loop through the list and for each `storeId` call `GET /v10/stores/{storeid}` that will return the store information for that specific store. In the end the integrator have a list of all the stores the merchant has and then the integrator knows which ``storeId`` for each store to use when creating a PoS. Below diagram illustrates a flow to get all merchant stores. - -Get Stores by VAT - -### Existing solution - -A brand is identified by a `merchantBrandId`. A `merchantLocationId` together with a `merchantBrandId` identifies a store within a brand. -If the merchant already has a MobilePay PoS solution with integration to either API V06, V07 or V08 then an integrator can use the already known `merchantBrandId` and `merchantLocationId` to get the `StoreId`, If the `merchantBrandId` and ``merchantLocationId`` is not known the process from the above paragraph will be the most efficient. To get the `StoreId` the integrator will have to call `GET /v10/stores` with the two ids, and in return they will receive the `storeId`. Below diagram illustrates a flow for getting the ``storeId`` using `GET /v10/stores`. - -Get Store - -## PoS Creation - -A PoS is created using the `POST /v10/pointofsales` endpoint. A PoS is identified in the PoS V10 API by a `posId` that is assigned by MobilePay upon creation of the PoS. Clients can provide their own internal identifier as a `merchantPosId` upon creation and use the `GET /v10/pointofsales` endpoint to lookup a `posId` based on a `merchantPosId`. The `merchantPosId` field is required, so if no internal identifier is applicable, the client should generate and supply a random string (eg. a fresh GUID) instead. - -### Beacons - -The first thing to consider when creating a PoS is what beacon(s) will be used to connect MobilePay users to the given PoS. -This can range from an unmanned vending machine that has no payment hardware at all and hence only shows a QR code on a screen, to a full fledged super market ECR with a 2-way bluetooth capable terminal that also can show a QR code. To create a PoS, the client needs to provide a list of possible ways to detect the PoS. The more accurate the list is, the better MobilePay will be able to detect errors (if bluetooth is provided as a beacon type but we detect that no user ever checks in via bluetooth something is likely wrong). It is recommended to keep the list of supported beacon types in an application configuration and then edit the list in case the setup changes. - -Each beacon, whether through a MobilePay QR code or a bluetooth/NFC signal, encodes a `beaconId` that can be read by the MobilePay app. It is the `beaconId` that is used to connect a MobilePay user to a specific PoS. `beaconId`s are globally unique across all merchants in MobilePay PoS and each `beaconId` can refer to at most one active PoS at any given time. - -Depending on the client setup, there are different use cases for handling `beaconId`s in API V10 - -#### Client that only supports dynamic QR codes - -In case the client only allows QR beacons (no physical device) and can create a QR code dynamically (i.e generate a QR code and show it on a screen in opposition to printing a physical QR code), then the client can choose to let MobilePay create a GUID to use as `beaconId`. The client then omits to provide a `beaconId` on PoS creation and afterwards queries the PoS to get the `beaconId`. The client can then store the `beaconId` in memory for QR code generation. Everytime the client reboots the client then has to query the PoS and grab the `beaconId`. This way the client is not required to store a `beaconId` in a configuration file since they can rely on querying it dynamically. - -#### Client that only supports static QR codes - -In case the client only allows QR beacons but is not able to generate a QR code dynamically, the client needs the ````beaconId```` for the PoS creation. The following options are available: - -1. The client can generate the `beaconId` and provide it on PoS creation -2. An arbitrary `beaconId` can be produced outside the client and be inputted to the client for instance using readers, scanners or inputted using a keyboard. MobilePay can generate the `beaconId` automatically as part of the production of stickers, if stickers are needed as the “acceptance device”. - -If stickers are needed as the acceptance device, we suggest that you use MobilePay to help deliver QR-code stickers to your merchants using option 2. - -:::note -The easiest way of handling stickers is if the client is set up to support activation and deactivation of QR codes directly from the merchant location. -You can order the stickers directly from MobilePay’s print supplier’s sticker webshop, and the Beacon IDs and QR codes will automatically be generated. The BeaconId will be printed on the sticker, so that it can be added by the merchant, or the merchant can report to you, which Beacon IDs the merchant uses. -[Sticker Webshop](https://mp.bordingcentral.dk) -::: - -The `beaconId` should then be stored locally in a configuration file so that it can be used if the PoS needs to be updated (i.e. deleted and re-created. See [PoS Update and Deletion](/docs/pos/pos-management#pos-updating-and-deletion)). To avoid clashes, the client must use a GUID as the `beaconId`. - -#### Client that supports physical devices (terminals, MobilePay white boxes) - -In cases where the client uses a physical device then that device will have a MobilePay `beaconId` associated with it. On PoS creation this `beaconId` has to be provided. Some devices allows a client to read the `beaconId` from it. If that is the case we recommend to read the `beaconId` when the client reboots and query the PoS to see if the `beaconId`s match. If not delete the PoS and re-create it with the new `beaconId`. This will make it possible to replace the device if its broken, and only have to reboot the system to propagate the changes. -If reading the `beaconId` from the device is not possible, we recommend to store the `beaconId` locally in a configuration file so that it persists through reboots. - -### Preventing checkin before payment - -Normally, a user is allowed to check in on a point of sale before a payment is created. Then, once the payment is created, the payment will pop up on the user's phone for them to pay. However, in some cases, this is not what you want. - -For example, in a self-service solution, a user could check in on a point of sale, walk away, and then they'll get paired to the next user's payment if the next user does not take over the check-in in time. - -When creating a PoS, the client can set the `requirePaymentBeforeCheckin` property to `true` (by default it is `false`), and then users are not allowed to check in to a point of sale before a payment is created on the point of sale. This ensures that no users are checked in when the payment is created, so you can ensure the correct user gets paired. - -### Callback - -If the client system cannot detect when a MobilePay user wants to pay and therefore needs to use the [Notification service](/docs/pos/detecting-mobilepay#notification-service), the client should set the callback parameter accordingly when calling `POST /v10/pointofsales`. -It is recommended to store the callback alias in the config file of the application. - -### Naming - -The last thing to keep in mind when creating a PoS is to consider the name. When a MobilePay user checks in on the PoS they will in the app see, in sequence: The name of the brand, the name of the store and the name of the PoS. We recommend naming the PoS so that the MobilePay user can verify that they in fact have checked in the right place. So in a supermarket scenario a good name for the PoS would be "Check-out 1" for the first check-out counter in that supermarket. - -## PoS Updating and Deletion - -A PoS can be deleted using the `DELETE /v10/pointofsales/{posId}` endpoint. - -We recommend only deleting a PoS if it is either not going to be used anymore, or you need to update it to reflect changes like a new callback alias, new name, new `beaconId` etc. - -When a PoS is deleted it is no longer possible to issue payments. However it will still be possible to capture or cancel payments that are in the reserved state. It is best practice to delay the deletion of a PoS until all payments have either been cancelled or captured. - -## Keeping in sync with MobilePay - -### When PoS reboots - -When the client reboots it is good practice to query the PoS with `GET /v10/pointofsales` with the `merchantPosId` and persist the `posId` in memory to use for initiating payments. If no PoS is returned, the client will have to re-create it. Here is the flow described: - -PoS onboarding - -We recommend the client to store the following in a configuration file to be able to create the PoS when needed: - -* `StoreId` -* `MerchantPosId` -* Name of PoS -* `BeaconId` (unless it can be read from the device itself. See [Beacons](/docs/pos/pos-management#beacons) ) -* Callback (If the client is dependent on the notification service. See [Callback](/docs/pos/pos-management#callback)) -* Supported beacon types - -## Master Data - -A PoS belongs to a store which in turn belongs to a merchant and associated with a brand. A PoS is identified by a `posId`, but it is also possible to refer to a PoS by its `beaconId` or `merchantPosId`. There can be at most one active PoS with a given `beaconId` at any given time. There can be at most one active PoS with a given `merchantPosId` at any given time, for a given integrator and merchant. - -A store is identified by a `storeId`, but it is also possible to refer to a store by the combination of `merchantBrandId` and `merchantLocationId`. Two stores with the same `merchantLocationId` but different `merchantBrandId`s are not related in any way. The `merchantBrandId`, `merchantLocationId` and `storeId` are supplied by MobilePay when the Merchant/Store is onboarded. diff --git a/docs/pos/pos.md b/docs/pos/pos.md deleted file mode 100644 index 1cc4c1c54..000000000 --- a/docs/pos/pos.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -pagination_prev: null -pagination_next: null ---- - -# MobilePay Point of Sale - -:::caution Change of Point of Sale 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 Point of Sale API with a new and scalable version. -[See more here](/docs/pos/transition-to-one-platform) - -::: - -MobilePay PoS is a solution for customers to pay through their mobile via a QR code or the white MobilePay box. - -In order to use MobilePay PoS, the checkout system must be online, and the PoS integrator must support MobilePay. - -Our MobilePay PoS REST api is intended for software developers implementing MobilePay payments in a PoS system - -The MobilePay PoS API exposes two separate flows for payments which are documented in this section. All payments must be explicitly captured by the client after the customer has approved the payment. The capture amount can be for the full or a partial amount. - -![PoS hero](/img/Hero_POS.png) - -Our MobilePay Point of Sale (PoS) REST API is intended for integrators implementing MobilePay payments in a PoS system. - -This document will explain in more detail how to implement the different payment flows, how to manage the PoS, how the Security model is built and what is needed from the integrator. - -This document does not include detailed specification of the endpoints, responses and response codes. This information can be found in the [API section](/api/pos). - -## Payment experience - -MobilePay PoS is an API for setting up a merchant's transaction requests on customers' MobilePay apps in a store. MobilePay PoS does not require the customer to manually enter any information in the MobilePay app pertaining to the transaction. A transaction request can typically be obtained by the customer by holding the mobile device near a merchant device (Terminal, BLE beacon, etc.) or scanning a QR code. - -Currently MobilePay PoS uses BLE one-way and two-way beacons and QR-codes to set up the transaction requests - the technology choices are not important for the API - however the concept of a beacon ID is central to allow matching of the customer willing to pay and the merchant's transaction request. diff --git a/docs/pos/release-notes.md b/docs/pos/release-notes.md deleted file mode 100644 index ae99b3204..000000000 --- a/docs/pos/release-notes.md +++ /dev/null @@ -1,293 +0,0 @@ ---- -sidebar_position: 13 ---- - -# PoS API Release Notes - -The Point of Sale API V10 is now in production. - -## Changelog - -#### 2022-08-12 - -- Introduced error code 1368 to [API Errors](/docs/pos/api-errors) and edited description on refundflow in [Refund Flow](/docs/pos/payment-flows/refunds) - ---- - -#### 2022-07-28 - -- Introduced error code 1204 to [API Errors](/docs/pos/api-errors) - ---- - -#### 2022-05-25 - -- Made it clear that directly using the `pollDelayInMs` response can improve payment flow completion time in [API Principles](/docs/pos/api-principles). - ---- - -#### 2022-05-03 - -- Removed information regarding a now decomissioned migration endpoint. - ---- - -#### 2022-04-08 - -- Created optimal flow section under [Best practices](/docs/pos/best-practices). - ---- - -#### 2021-08-11 - -- Made it clear that it is the `beaconId` that should be used in [QR code generation](/docs/pos/create-qr-codes) instead of `posId`. - ---- - -#### 2021-08-04 - -- Made it clear that Integrator's notification endpoint must return 200 on success in [Notification Service](/docs/pos/notification-service#notification-endpoint) - ---- - -#### 2021-05-25 - -- Expanded list of valid characters in [Input Formats](/docs/pos/input-and-output-formats#valid-characters) - ---- - -#### 2021-03-23 - -- Added `requirePaymentBeforeCheckin` documentation to [PoS management](/docs/pos/pos-management#preventing-checkin-before-payment) - ---- - -#### 2021-03-22 - -- Added explicit retry suggestions and rules in [Retrying requests](/docs/pos/api-principles#retrying-requests) - ---- - -#### 2021-03-16 - -- Removed CalibrationType property from [Input Formats](/docs/pos/input-and-output-formats#point-of-sales) since it has been removed from the V10 API. -- Made the [Detecting MobilePay by notification service](/docs/pos/detecting-mobilepay#notification-service) section more clear by adding the call ``GET /pointofsales/{posid}/checkin`` to the flow diagram - ---- - -#### 2021-03-09 - -- Re-wrote the [Onboarding](/docs/pos/pos-management#onboarding) section of the Point-of-Sale Management page. The section now contains a description on how to acquire store information needed for integrators when onboarding a merchant, which does not have a MobilePay PoS solution using an older version of the MobilePay PoS API. - ---- - -#### 2021-01-29 - -- Added guide to [Create QR Codes](/docs/pos/create-qr-codes) - ---- - -#### 2020-12-15 - -- Added section to [Refund Flow](/docs/pos/payment-flows/refunds) regarding how to get a `paymentId` for a refund if the `paymentId` is not known. - ---- - -#### 2020-10-23 - -- Clarified language in the network and server errors paragraph of [API principles](/docs/pos/api-principles#error-handling). -- Added desciption of why it is important to either capture or cancel a refund in error situations in [Cancelling refunds](/docs/pos/payment-flows/cancel-flows). -- Removed age validation from documentation since this is not possible to do. - ---- - -#### 2020-10-20 - -- Added error codes 1406, 1407, 1408, 1409, 1410, and 1411 to [API Errors](/docs/pos/api-errors). - ---- - -#### 2020-10-13 - -- Refund functionality now ready and live in prod. See [Refund Flow](/docs/pos/payment-flows/refunds) for documentation on how to implement the functionality. An integrator needs to be certified in the new Refund section on the self certification website, to use the refund endpoints in the production environment. Also see the MobilePay developer portal to check out the API documentation. - ---- - -#### 2020-09-18 - -- Removed the following supportedBeaconTypes: `BluetoothOther`, `BluetoothMP1`, `BluetoothMP2`, `BluetoothMP3`, `BluetoothMP4` and replaced them with one `Bluetooth` in [Input Formats](/docs/pos/input-and-output-formats). During certification when calling ``POST /pointofsales`` the request will now fail if supportedBeaconTypes contains any of the removed mentioned values above. If you already have a client that is certified and is using the old values, they will continue to work in production. - ---- - -#### 2020-09-14 - -- Added 1365, 1366, 1367 error codes to [Api Errors](/docs/pos/api-errors) - ---- - -#### 2020-09-08 - -- Removed Integrator ID from [Self Certification](/docs/pos/development-guide/verification) -- Updated screenshots in [Self Certification](/docs/pos/development-guide/verification) - ---- - -#### 2020-09-02 - -- Changed and updated how Refunds is planned to work. See description in [Payment Flows](/docs/pos/payment-flows/refunds). Release of Refunds are planned to Ultimo September. -- Clarified how to choose a beaconId in [Best Practices](/docs/pos/best-practices#choosing-a-beaconid) - ---- - -#### 2020-08-19 - -- Clarified the requirements for using long lived access tokens in [Authentication](/docs/pos/authentication) -- Reduced the number of test cases in Self Certification by e.g. having more than one error or timeout scenario in one test case. Categories remain the same and this does not require a re-certification since this has not changed what is being tested. -- Updated picture of Onboarding cases in [Self Certification](/docs/pos/development-guide/verification) -- Removed x-mobilepay-client-system-name header from table in [Input Formats](/docs/pos/input-and-output-formats) -- Please do not hesitate to provide feedback - ---- - -#### 2020-08-07 - -- Added a section on [Best Practices](/docs/pos/best-practices) regarding Merchant onboarding. -- Moved information regarding Partial Capture from [Best Practices](/docs/pos/best-practices) to [Payment Flows](/docs/pos/payment-flows/partial-capture) and added some diagrams describing the flow. -- Removed the 403 forbidden statuscode when calling ``POST /payments/{paymentId}/capture`` from [API ERRORS](/docs/pos/api-errors) -- Added a 409 conflict statuscode when calling ``POST /payments/{paymentId}/capture`` from [API ERRORS](/docs/pos/api-errors) that descibes if a partial capture is attempted on a payment where that is not possible. - ---- - -#### 2020-07-13 - -- Added a 403 error code for payments/{payid}/capture in [API ERRORS](/docs/pos/api-errors) which is returned when trying to make a partial capture which is still not supported. When it will be possible to do partial captures it will be listed here in the release notes. - ---- - -#### 2020-07-10 - -- Clarify handling timeout for POST/DELETE/PUT in [API principles](/docs/pos/api-principles#error-handling) - ---- - -#### 2020-06-29 - -- Updated payment lifetime in [Payment Flow](/docs/pos/payment-flows/payment-flow) - ---- - -#### 2020-06-24 - -- Updated description and added configuration details in [Self Certification](/docs/pos/development-guide/verification) - ---- - -#### 2020-05-14 - -- Added error 1182 in [API ERRORS](/docs/pos/api-principles) - ---- - -#### 2020-05-13 - -- Added a note on partial capture handling in [Best Practices](/docs/pos/best-practices) - ---- - -#### 2020-04-28 - -- Added a note on the possibility of long-lived access tokens for PoS devices - ---- - -#### 2020-04-21 - -- Added 403 in the API Errors section as a possible non-successful status-code when creating a Point of Sale. -- Added a conflict case to the capture payment endpoint in the API Errors section when trying to capture an already captured payment with a different amount. - ---- - -#### 2020-03-27 - -- Dropped the `x-ibm-client-system-name` header and modified the [API principles](/docs/pos/api-principles) page to explain how the `x-ibm-client-system-version` header will be used for client versioning. - -- Renamed all `X-IBM-*` and `X-MobilePay-*` headers to be lowercase in the documentation (the actual headers are case-insensitive). - ---- - -#### 2020-03-26 - -- Renamed `vat_number` parameter to `merchant_vat` for [Authentication](/docs/pos/authentication) endpoint and changed the format to remove the dash between country code and VAT (e.g., "DK12345678" instead of "DK-12345678"). - -- Removed 'api/' as part of the endpoint route for all endpoints. - ---- - -#### 2020-03-25 - -- Added a *RejectedByMobilePayDueToAgeRestrictions* [payment state](/docs/pos/payment-flows/payment-flow), to indicate that a payment could not be completed because of age restrictions on the payment. - -- Added section Authentication [Authentication](/docs/pos/authentication) section so Integrators can use MobilePay APIs, as they'll have to obtain an access_token from the Integrator Authentication service. This way, MobilePay knows who is calling our service. - ---- - -#### 2020-03-04 - -- Added section Handling Timeouts in [API Principles](/docs/pos/api-principles) section. - -- Removed a 409 errorcode from POST /api/v10/refunds regarding refund amount in the [API Errors](/docs/pos/api-errors) section and added an extra one regarding call to POST /api/v10/refunds if payment is not captured. - ---- - -#### 2020-03-03 - -- Renamed header from X-MobilePay-MerchantVatNumber to X-MobilePay-Merchant-VAT-Number in the [Input Formats](/docs/pos/input-and-output-formats) section. - -- Rewrote parameters to camelCase instead of PascalCase in the [Input Formats](/docs/pos/input-and-output-formats) section to reflect the right casing in the API - ---- - -#### 2020-02-27 - -- Added HTTP StatusCodes and ErrorCodes pr. endpoint in the API. Response codes have also slightly changed in the API on the basis of this documentation so be aware of minor changes to the API as well. See more at [API Errors](/docs/pos/api-errors). - -- Added header to all endpoints in the API called X-MobilePay-MerchantVatNumber. For more information see [Input Formats](/docs/pos/input-and-output-formats#http-headers) - -- Fixed wrong header name from X-IBM-ClientId to X-IBM-Client-Id. See [Input Formats](/docs/pos/input-and-output-formats#http-headers) - ---- - -#### 2020-02-07 - -- Added documentation on payment restrictions under [Input Formats](/docs/pos/input-and-output-formats#payment-restrictions) and expanded on best practices regarding payment restrictions [Best Practices](/docs/pos/best-practices) - ---- - -#### 2020-02-04 - -- Specified expiration length of Refund reservations to 24 hours. [Refunds](/docs/pos/payment-flows/refunds) - ---- - -#### 2020-01-31 - -- Added a description of Self-Certification to the documention under [Self Certification](/docs/pos/development-guide/verification) - ---- - -#### 2019-12-23 - -- Changed the month that news will come out regarding self-certification from December 2019 to January 2020 - ---- - -#### 2019-12-10 - -- Added `BrandName` to the subpage **Input and Output Formats** in the Brand section -- Renamed subpage **Input Formats** to **Input and Output Formats**. -- Adjusted content of subpage **Input and Output Formats** - - **HTTP Headers** - - Renamed from `X-MP-\*` to `X-MobilePay-\*`. - - Removed `X-MP-IntegratorId`. - - **Payments** - - Added `PlannedCaptureDelay`, `CustomerToken` and `CustomerReceiptToken`. diff --git a/docs/pos/resources.md b/docs/pos/resources.md deleted file mode 100644 index e7d5dd92c..000000000 --- a/docs/pos/resources.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -sidebar_position: 16 -pagination_next: null ---- - -# Resources - -[API documentation](/api/pos): The API reference documentation for PoS - -[Partner site](https://www.mobilepaygroup.com/partner/point-of-sale): Integrator onboarding and business information - -MobilePay site [DK](https://www.mobilepay.dk/erhverv/fysiske-butikker/mobilepay-point-of-sale) | [FI](https://mobilepay.fi/yrityksille/myyntipisteet/mobilepay-point-of-sale): Product information and support for merchants - -[Design Guidelines](https://www.mobilepaygroup.com/design): Find MobilePay buttons, logos, banners etc. - -Order PoS stickers and signs in the [web shop](https://mp.bordingcentral.dk/user/Login.aspx) - -Templates for creating PoS signs can be found here: - -* DK: [Materialebank](https://mobilepay.dk/materialebank/marketingmateriale/skilte/skiltning-til-pos) -* FI: Please contact business.support@mobilepay.fi - -# Migration - -Information about the [new integration](https://www.mobilepaygroup.com/partner/new-platform) - -[Migration guide](https://developer.vippsmobilepay.com/docs/mp-migration-guide/pos/) covering the technical details of the new migration - -As a merchant - Requst access to [test environment](https://www.mobilepaygroup.com/partner/merchant-test) diff --git a/docs/pos/transition-to-one-platform.md b/docs/pos/transition-to-one-platform.md deleted file mode 100644 index 6832ef57e..000000000 --- a/docs/pos/transition-to-one-platform.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_position: 15 ---- -import Launch from '/docs/shared-blocks/_launch.mdx'; - -# Transition to One Platform - -**One platform – more reach** - -On November 1st 2022 the merger between MobilePay and Norwegian Vipps was approved. We have now set full speed on the transition towards having one joint platform to become the best and most used payment wallet in the Nordics for you as customers and partners and for our users. -Early 2024, the ambition is to have one app, branded locally as MobilePay in Denmark and Finland and Vipps in Norway, and one platform with more than 11 million users and more than 400.000 merchants across the Nordics. - -## Shift to a new API early 2024 - -To allow for the flexibility and reach that we aim for, we will have to replace the current MobilePay Point of Sale API with new APIs on the new joint platform by early of 2024. This will require a new integration. - -**Nordic Wallet Launch 🚀** - this will be the the day when all MobilePay users will get new, updaraded app version. On the same date Invoice APIs will stop working and you will have to switch your trafic to ePayments APIs. -- **March 12th** we will launch the new platform in **Denmark** and migrate all Danish merchants. - -## New integration - -We will continually send out information to all existing integrators about the new integration. To read more about the solution replacing MobilePay PoS please find details [here](https://www.mobilepaygroup.com/partner/new-platform). On this page you can also request access to the test environment to initiate the new integration work. -For technical changes of the integration please visit the [migration guide](https://developer.vippsmobilepay.com/docs/vipps-developers/mp-migration-guide/#point-of-sale-vs-epayment). As soon as we have more information on the documentation for the new version, we will update these page. - -:::info Prepare for launch - -::: - -## FAQ -### What will happen to the merchants signed up for MobilePay PoS? -To make the transition as smooth as possible, we will migrate all merchants and their data to the new platform. They will be signed up for ePayments which is the replacement for PoS. As an integrator your responsibility is to implement the new solution and make it available for your merchants. - -### What will happen if we use the MobilePay PoS API after launch of the new platform? -It will take a while before we close the old platform so it will be possible to initiate payments on the old MobilePay PoS API after we launch our new platform. But it will not be possible for any users to accept these payments because we have moved all users to our new platform. This means that you will not receive any API errors when attempting to initiate payments (or make any other requests to the API). But the payments will stay in status initiated and no user will be able to interact with the payments. - -### Is it possible to reuse the existing QR codes? -Yes it is possible to register the existing MobilePay PoS QR codes on the new platform. Please visit the [migration guide](https://developer.vippsmobilepay.com/docs/mp-migration-guide/pos/#checkout-neither-has-qr-scanners-nor-customer-facing-screens) for more information. - -### What happens if a user scan a MobilePay PoS QR code after the launch of the new platform? -User will get a new app on the day of the launch. If you have [migrated the QR code](https://developer.vippsmobilepay.com/docs/mp-migration-guide/pos/#checkout-neither-has-qr-scanners-nor-customer-facing-screens) to the new platform then it can be used for ePayments and users can scan it with the new. If you have not migrated the QR code (and it therefore does not exist on the new platform) then the user will see an error in the app stating that we cannot recognize the QR code. It is therefore important that you migrate the QR codes or remove them.