Step 1: Initiate consent

The 1st step is forming an authorization request with the appropriate URI parameters at the authorization endpoint

  • You can find detailed information about this request in the OpenID Connect specification here
  • Specification of parameters are found here 
    • Sandbox Authorization Endpoint DK:
    • Sandbox Authorization Endpoint FI:
    • Production Authorization Endpoint DK:
    • Production Authorization Endpoint FI:
OpenID Connect Discovery
  • The OpenID Connect protocol requires the use of multiple endpoints for authenticating users, and for requesting resources including tokens. 
  • To simplify implementations and increase simplicity, OIDC allows the use of a "Discovery document"  OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL, typically
  • This URL returns a JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, public keys used to sign the tokens, and other details. The clients can use this information to construct a request to the OpenID server. The field names and values are defined in the OpenID Connect Discovery Specification.
  • Find the links for the discovery document below. It will be used by you to download the necessary configuration data.  This should not be attempted without a solid grasp of the OAuth2 and Open ID Connect standards. All endpoints needed for integration can be found in our openid connect discovery endpoint. These endpoints should be fetched dynamically by your application, since they are prone for change.
  • The metadata is a simple JavaScript Object Notation (JSON) document.  

Here is an example of data returned:

"issuer": "",
"jwks_uri": "",


OpenID Connect Discovery

Environment Link to configuration data 


Step 1: Call /authorize to initiate user login and consent

Before a client can access a protected resource, it must first obtain an authorization grant from the resource owner, and then exchange the authorization grant for an access token. You should retrieve the base URI from the Discovery document using the authorization endpoint. The next step is forming an authorization request with the appropriate URI parameters at the authorization endpoint, which can be done by

  • HTTP GET - using query string serialization as described  here
Sample raw request using GET:



Explanation of mandatory parameters 

Parameters Description Value Required

OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used. 


code id_token Yes

form_post sends the token response as a form post instead of a fragment encoded redirect . In this mode, Authorization Response parameters are encoded as HTML form values that are auto-submitted in the User Agent, and thus are transmitted via the HTTP POST method to the Client, with the result parameters being encoded in the body using the application/x-www-form-urlencoded format.  

fragment - Parameters are encoded in the URL fragment added to the redirect_uri when redirecting back to the client.





The client_id that you received by zip file. This is not the same as the MerchantID or the e-mail log-in to


The client-id given in the zip file Yes

The HTTPS endpoint on your server, that will receive the redirect/response from MobilePay. It needs to be whitelisted by MobilePay before it can be used.


Customer redirect uri as registered

A space list of scopes. For this flow, the full list of possible scopes is openid offline_access subscriptions invoice transactionreporting merchantpayments webhooks.

The scopes openid offline_access is required, the rest is product specific. It is a space-separated list.  

openid offline_access subscriptions 
invoice transactionreporting 

merchantpayments webhooks




State is used to maintain state between the request and the callback. You generate a new value for each request, and we return it in response for you to validate.


Unique random value  Yes

Documentation can be found hereA challenge for PKCE. The challenge is verified in the access token request, it will be used in combination with the next call.


The value should be a SHA-256 hash
of a crypto random byte array.

The method that was used to derive code challenge.

S256 Yes

​String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the authentication request to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. Should be a new random value for each request. We invalidate a nonce once our back-end has received it, so next time we get a request with the same nonce, we then reject it.

Unique random value  Yes

A string value equal to the VAT number for the merchant. This is used to identify which merchant that should be given consent to if a user has multiple merchants assigned. We support FI and DK VAT numbers. The VAT number consists of country prefix (either FI or DK) and 8 digits. 


Note: merchant_vat is required when granting consent to a specific merchant

Country prefix + VAT number of


By using the value, that you used when creating the code_challenge, we have a way for MobilePay to verify the call. You execute the Authorization call once, and you also make the code_challenge once with one code_verifier. But you need to save your code_verifier so you can use it, every time you utilize your refresh_token. This means that you’ll not need to go through the Authorize call again, but that you simply need to utilize the code_verifier from the the original authorization call. 

Consent screen

When the Merchant is logged in, the MobilePay Portal presents the Merchant with a consent screen, that describes the information that the Merchant is granting to. For example, when the user wants to have MobilePay Subscriptions, the consent screen asks to give access to Subscriptions. The request access to this information using the scope parameter, which you include in the authorize request. You can also use scopes to request access to other MobilePay API's. When the Merchant clicks yes (gives consent), the Merchant is redirected back to the integrators website/environment).

Integrator has been provided with a test merchant to our MobilePay Portal - Sandbox. Integrator should use the e-mail and password provided in the invitational e-mail to log-on to it.

Once the user authenticates successfully, the application will be redirected to the redirect_uri, with a code as part of the URL: https://redirect_url#code=xxx. You can exchange this code with an Access Token using the token endpoint  

Unauthorized and error response 

You might see this page when trying to obtain an authorization_code. If you see this page, it is most often due to an invalid request. The request is missing a required parameter, includes an invalid parameter value or a redirect_uri, that hasn't been whitelisted. MobilePay does not provide additional information, used to assist the client developer with additional information about the error, in order to mitigate against cross-site request forgery. Ensure that all required parameters are present and valid. 



How do I ? 

 See the following table for error description   

Error Description
invalid_client  Client authentication failed, such as if the request contains an invalid client ID or secret.
unauthorized_client  This client is not authorized to use the requested grant type. 
invalid_grant The authorization code is invalid or expired. This is also the error you would return if the redirect URL given in the authorization grant does not match the URL provided in this access token request.
invalid_scope  This error indicates an invalid scope value in the request
Step 2 - Get Code

The purpose of Step 2 is to have Authorization Code returned to your Redirect URI. You need to wait for the response by listening on the redirect URI and get the Authorization Code. .