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: https://sandprod-admin.mobilepay.dk/account/connect/authorize
    • Sandbox Authorization Endpoint FI: https://sandprod-admin.mobilepay.fi/account/connect/authorize
    • Production Authorization Endpoint DK: https://admin.mobilepay.dk/account/connect/authorize
    • Production Authorization Endpoint FI: https://admin.mobilepay.fi/account/connect/authorize
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. 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",
"revocation_endpoint":"https://api.mobilepay.dk/merchant-authentication-openidconnect/connect/revocation",
"introspection_endpoint":"https://api.mobilepay.dk/merchant-authentication-openidconnect/connect/introspect",
"frontchannel_logout_supported":true,
"frontchannel_logout_session_supported":true,

 

OpenID Connect Discovery

Environment Link to configuration data 
Sandbox
Production
Step 1: Call /connect/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 -If you're using it, the request parameters are added to the HTTP request entity-body using the application/x-www-form-urlencoded. Read more 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
&state=228eaa0b1a2819a77f055171edb7d9d6
&code_challenge=Ge5p0wzlM_2SrxcCy9WAplP_CupB2xu2uiwFq_BBUmY
&code_challenge_method=S256
&nonce=28b32545bee64100a6e92eddbc13f562

Explanation of mandatory parameters 

Parameters Description Value Required
response_type

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
response_mode

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.  

 

form_post Yes
client_id

the 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.dk

 

The client-id given in the zip file Yes
redirect_uri

the HTTPS endpoint on your server, that will receive the response from MobilePay. It needs to be whitelisted by MobilePay.

 

Customer redirect uri as registered by developer@mobilepay.dk Yes
scope

A space list of scopes. For this flow, the full list of possible scopes is subscriptions invoice openid transaction_reporting offline_access. It is a space-separated list.  

subscriptions invoice openid transaction_reporting offline_access

 

 

Yes
state

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
code_challenge

Dcoumentation 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. Yes
nonce

​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 invalid 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

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. 

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, then the consent screen asks to give acess 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), then the Merchant is redirected back to the integrators website/environment).

Integrator has been provided with a testmerchant to our MobilePay Portal - Sandbox. Integrator should 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://YOUR_APP/callback?code=BPPLN3Z4qCTvSNOy. 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 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. 

 

 

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. 

Step 2