Authorize

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

Environment	Link to configuration data
Sandbox	Denmark - Finland
Production	Denmark - Finland

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

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

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. fragment - Parameters are encoded in the URL fragment added to the redirect_uri when redirecting back to the client.	form_post or fragment	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	ID received in zip file from Developer Support	Yes
redirect_url	MobilePay 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.com	Yes
scope	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	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	A challenge for PKCE. The challenge is verified in the access token request, it will be used in combination with the next call. Read more here	The value should be a SHA-256 hash of a crypto random byte array.	Yes
code_challenge_method	The method that was used to derive code challenge.	S256	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 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 here	Unique random value	Yes
merchant_vat	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 merchant	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, 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 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.

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