Skip to main content

Authorize

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

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 https://admin.mobilepay.dk/account/.well-known/openid-configuration
  • 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": "https://api.mobilepay.dk/merchant",
"jwks_uri": "https://api.mobilepay.dk/merchant-authentication-openidconnect/.well-known/openid-configuration/jwks",
"authorization_endpoint":"https://admin.mobilepay.dk/account/connect/authorize",
"token_endpoint":"https://api.mobilepay.dk/merchant-authentication-openidconnect/connect/token",
"end_session_endpoint":"https://admin.mobilepay.dk/account/connect/endsession",
"introspection_endpoint":"https://api.mobilepay.dk/merchant-authentication-openidconnect/connect/introspect",
"frontchannel_logout_supported":true,
"frontchannel_logout_session_supported":true,
}

OpenID Connect Discovery

EnvironmentLink to configuration data
SandboxDenmark - Finland
ProductionDenmark - Finland

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
GET https://sandprod-admin.mobilepay.dk/account/connect/authorize
{
&response_type=code%20id_token
&response_mode=form_post
&client_id=some.test.client.usually.your.company.name.in.small.letters
&redirect_uri=https%3A%2F%2Fmyredirect%40uri.com
&scope=openid%20invoice%20subscriptions%20offline_access%20transactionreporting
&state=228eaa0b1a2819a77f055171edb7d9d6
&code_challenge=Ge5p0wzlM_2SrxcCy9WAplP_CupB2xu2uiwFq_BBUmY
&code_challenge_method=S256
&nonce=28b32545bee64100a6e92eddbc13f562
&merchant_vat=DK12345678
}

Explanation of mandatory parameters

ParametersDescriptionValueRequired
response_typeOAuth 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_tokenYes
response_modeform_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.form_post or fragmentYes
client_idThe client_id that you received by zip file. This is not the same as the MerchantID or the e-mail log-in to https://sandprod-admin.mobilepay.dkID received in zip file from Developer SupportYes
redirect_urlMobilePay will redirect users to a registered redirect_uri, in order to prevent redirection attacks where an authorization code or access token can be obtained by an attacker. The redirect_uri must be an https endpoint to prevent tokens from being intercepted during the authorization process. We allow the use of localhost redirects in the sandbox environment.Merchant redirect uri as registered by developer@vippsmobilepay.comYes
scopeA 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 webhooksYes
stateState 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 valueYes
code_challengeA challenge for PKCE. The challenge is verified in the access token request, it will be used in combination with the next call. Read more hereThe value should be a SHA-256 hash of a crypto random byte array.Yes
code_challenge_methodThe method that was used to derive code challenge.S256Yes
nonceString 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. Read more hereUnique random valueYes
merchant_vatA 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 merchantCountry prefix + VAT number of merchantYes
note

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.

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.

Sandprod admin screen

PoS confirmation screen

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 https://api.sandbox.mobilepay.dk/merchant-authentication-openidconnect/connect/token

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.

Sandprod consent screen

ErrorDescription
invalid_clientClient authentication failed, such as if the request contains an invalid client ID or secret.
unauthorized_clientThis client is not authorized to use the requested grant type.
invalid_grantThe 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_scopeThis error indicates an invalid scope value in the request