How to use our APIs?¶

PSU Prerequisites¶

Client subscription:

In a Corporate context, access to account or payments initiation data is subject to client subscription of the services they wish to use with their TPPs. This subscription is made via the e-banking contract, by amendment to an existing contract or by subscription if it is a new contract. According to PSD2 regulations these services are totally free for clients. The aim is to ensure that the legal representative of the company is aware of the TPP usage.

All Societe Generale accounts implemented in the e-banking subscription and belonging to the geographical scope covered are automatically accessible to the subscribed service(s).

Strong Authentication:

Strong authentication is requested to access the services related to PSD2 APIs. As a consequence, it is necessary to ensure that the client subscription is in strong authentication or to make subscribed this option to clients in their e-banking contract. Note that 90% of our clients are already equipped with an enhanced security means (Secure Access and/or 3SKey) and that all clients will be equipped until March 2020.

User Access:

As with any e-banking service, access to both services (account aggregation and/or payment initiation) is granted to users by the Administrator of the subscription. A user authorized by the Administrator to access account aggregation and/or payment initiation services will do so according to the rights given to him/her by the Administrator in Global Cash subscription regarding:

access to accounts,
access to the relevant reporting services (for account aggregation services),
access to payment entry and validation services within the limits of his/her rights in Global Cash (caps, single or double signatures, signatory groups).

Authentication for PSD2 APIs¶

All our APIs use an OpenID Connect / OAuth2 compatible authentication server to secure both Production and Sandbox environments.

This page describes the OpenID Connect standard used to secure the APIs.

Please note that following the regulation requirements you must have a qualified EIDAS QWAC certificate in order to call the APIs.

Autorization code flow is used to make API calls on behalf of the user (PSU).

In order to call an API, you must follow the steps below:

Ask the user to authenticate on SG Markets (as with e-banking services)

The user is redirected to SG Markets, enters his credentials (if needed) and is redirected back to your application
Retrieve the authorization code at the end of user authentication

When the user is redirected to your application, SG Markets will add a query parameter called authorization code with a temporary code.
Get an access and refresh tokens from the authorization code

Using the authorization code and your EIDAS QWAC certificate, call a dedicated API to get an access token and a refresh token.
Get a new access token from the refresh token

When user is no more present and the access token has expired, call a dedicated API using the refresh token and your EIDAS QWAC certificate to get a valid access token.
Call the API

Call PSD2 APIs by connecting with your EIDAS QWAC certificate and passing the access token.

Ask the user to authenticate on SG Markets:

Retrieve the URL of the authorization endpoint.

Retrieve the root of the authorization endpoint from the configuration document located at the following address https://sso.sgmarkets.com/sgconnect/oauth2/.well-known/openid-configuration

The following key should be used in the JSON file to locate the authorization endpoint: “authorization_endpoint”

Build an authorization URL.

The format of the URL is as follows:

[authorization_endpoint]?response_type=code&acr_values=L1&client_id=[client_id]&scope=[scopes]&redirect_uri=[redirect_uri]

where

[authorization_endpoint] the root of the authorization endpoint previously retrieved from configuration at step 1

[client_id] the client_id you received from SG Markets on onboarding

[scopes] OAuth2 scopes defining the APIs you which to call with this token. Please see the documentation of each API for specific scopes. Multiple scopes can be provided by separating by space. The resulting string must be url-encoded. See example below.

[redirect_uri] SG Markets will redirect the user to this page once the authentication is done. The URI must me url-encoded. See example below. Please note that the provided URI must be one of the URIs you provided when onboarding your application. Otherwise the authentication will fail.

Example:

https://sso.sgmarkets.com/sgconnect/oauth2/authorize?response_type=code&acr_values=L1&client_id=adf3e4aa-c431-4a80-a2ac-31e9fa7efcf4&scope=openid%20api1.v1%20api2.v1&redirect_uri=https%3A%2F%2Fmysite.com%2Fpost-authentication

Redirect the user to the authorization URL.

Redirect the user’s browser to the authorization URL for authentication.

Retrieve the authorization code at the end of user authentication:

After authentication the user will be redirected to the redirect_uri you have provided in the previous step.
When redirecting, SG Markets will append a number of query string parameters to your page.

Example:

https://mysite.com/post-authentication?code=4EaaUd1nfrgpxw6ZzaezQNj9EYI&iss=https%3A%2F%2Fsso.sgmarkets.com%3A443%2Fsgconnect%2Foauth2&session_state=2d7fe152b485c7e49231352afa2f23eb22baf09be93be0e72e02e8658f78b3c0&client_id=adf3e4aa-c431-4a80-a2ac-31e9fa7efcf4

Retrieve the code parameter from the URL. It is the authorization code you will need later.

Get access and refresh tokens from the authorization code:

Use your EIDAS QWAC certificate to establish connection with the server.

You must use your qualified EIDAS QWAC client certificate to establish secure TLS connection with the server. The certificate allows SG Markets to authenticate yourself (as Client in terms of OAuth2).

This specification described the overall standard used for securing access.

The secure connection will be used to make the access_token call below.

Call the access_token endpoint.

Make a POST call to “https://sso-cert.sgmarkets.com/sgconnect/oauth2/access_token” passing the following parameters in the body of the request:

grant_type=authorization_code&client_id=[client_id]&code=[authorization_code]&redirect_uri=[redirect_uri]

where

[client_id] the client_id you received from SG Markets on onboarding

[authorization_code] the authorization code you retrieved previously

[redirect_uri] the exact same redirect URI used for authenticating user on SG Markets. See redirect_uri parameter in authorization endpoint.

Example:

http

POST /sgconnect/oauth2/access_token HTTP/1.1
Host: sso-cert.sgmarkets.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=adf3e4aa-c431-4a80-a2ac-31e9fa7efcf4&code=4EaaUd1nfrgpxw6ZzaezQNj9EYI&redirect_uri=https%3A%2F%2Fmysite.com%2Fpost-authentication

curl

curl -i -X POST https://sso-cert.sgmarkets.com/sgconnect/oauth2/access_token -H "Content-Type: application/x-www-form-urlencoded" --data-raw 'grant_type=authorization_code&client_id=adf3e4aa-c431-4a80-a2ac-31e9fa7efcf4&code=4EaaUd1nfrgpxw6ZzaezQNj9EYI&redirect_uri=https%3A%2F%2Fmysite.com%2Fpost-authentication'

python-requests

requests.post('https://sso-cert.sgmarkets.com/sgconnect/oauth2/access_token', headers={'Content-Type': 'application/x-www-form-urlencoded'}, data='grant_type=authorization_code&client_id=adf3e4aa-c431-4a80-a2ac-31e9fa7efcf4&code=4EaaUd1nfrgpxw6ZzaezQNj9EYI&redirect_uri=https%3A%2F%2Fmysite.com%2Fpost-authentication')

Get the access and refresh tokens.

The response of the previous call is a JSON document, which will contain the following information:

access token corresponding to the “access_token” key in JSON

refresh token corresponding to the “refresh_token” key in JSON

validity of the access token in seconds corresponding to the “expires_in” key in JSON

granted scopes corresponding to the “scope” key in JSON

Example:

{
  "access_token":"eyJ0eXAiOiJKV1QiLCJraWQiO...yuP_Hv8V4jFMwQoaMdg",
  "refresh_token":"eyJ0eXAiOiJKV1QiLCJraWQiO...oK6SVRSqRgAKNfg",
  "scope":"openid api1.v1 api2.v1",
  "id_token":"xxxxxxxxx",
  "token_type":"Bearer",
  "expires_in":599
}

Retrieve the access token and refresh token values from the response.

Get a new access token from the refresh token:

By default the access token has a short validity period (10 minutes). On the other hand, the refresh token is long lasting and can be persisted for later use. If you need to make an API call when the access token has expired, you should proceed to renewing your access and refresh tokens using previously retrieved refresh token.

Use your EIDAS QWAC certificate to establish connection with the server.

This specification described the overall standard used for securing access.

The secure connection will be used to make the access_token call below.

Call the access_token endpoint.

Make a POST call to “https://sso-cert.sgmarkets.com/sgconnect/oauth2/access_token” passing the following parameters in the body of the request:

grant_type=refresh_token&client_id=[client_id]&refresh_token=[refresh_token]

where

[client_id] the client_id you received from SG Markets on onboarding

[refresh_token] the refresh token you retrieved previously during “Get access and refresh tokens from the authorization code” step

Example:

http

POST /sgconnect/oauth2/access_token HTTP/1.1
Host: sso-cert.sgmarkets.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=adf3e4aa-c431-4a80-a2ac-31e9fa7efcf4&refresh_token=eyJ0eXAiOiJKV1QiLCJraWQiO...oK6SVRSqRgAKNfg

curl

curl -i -X POST https://sso-cert.sgmarkets.com/sgconnect/oauth2/access_token -H "Content-Type: application/x-www-form-urlencoded" --data-raw 'grant_type=refresh_token&client_id=adf3e4aa-c431-4a80-a2ac-31e9fa7efcf4&refresh_token=eyJ0eXAiOiJKV1QiLCJraWQiO...oK6SVRSqRgAKNfg'

python-requests

requests.post('https://sso-cert.sgmarkets.com/sgconnect/oauth2/access_token', headers={'Content-Type': 'application/x-www-form-urlencoded'}, data='grant_type=refresh_token&client_id=adf3e4aa-c431-4a80-a2ac-31e9fa7efcf4&refresh_token=eyJ0eXAiOiJKV1QiLCJraWQiO...oK6SVRSqRgAKNfg')

Get the access_token.

The response of the previous call is a JSON document, which will contain the following information:

access token corresponding to the “access_token” key in JSON

refresh token corresponding to the “refresh_token” key in JSON

validity of the access token in seconds corresponding to the “expires_in” key in JSON

scopes granted corresponding to the “scope” key in JSON

Example:

{
  "access_token":"eyJ0eXAiOiJKV1QiLCJraWQiO...yuP_Hv8V4jFMwQoaMdg",
  "refresh_token":"eyJ0eXAiOiJKV1QiLCJraWQiO...oK6SVRSqRgAKNfg",
  "scope":"openid api1.v1 api2.v1",
  "id_token":"xxxxxxxxx",
  "token_type":"Bearer",
  "expires_in":599
}

Retrieve the access token and refresh token values from the response. Please note that once used, the refresh token is disabled. On next refresh, the new refresh token issued alongside with the access token must be used.

Call the API¶

Use your EIDAS QWAC certificate to establish connection with the server

This specification described the overall standard used for securing access.

The secure connection will be used to make the API call below.

Call the API

Call the API through secure channel while appending the following header with the value of the access token. Authorization: Bearer [access_token]

where

[access_token] access token retrieved in the previous step

Example:

http

GET /api/v1/data HTTP/1.1
Host: my-api.sgmarkets.com
Authorization: Bearer c86d53a9-4b24-4888-aa99-bb196698c669

curl

curl -i -X GET https://my-api.sgmarkets.com/api/v1/data -H "Authorization: Bearer c86d53a9-4b24-4888-aa99-bb196698c669"

python-requests

requests.get('https://my-api.sgmarkets.com/api/v1/data', headers={'Authorization': 'Bearer c86d53a9-4b24-4888-aa99-bb196698c669'})

Strong Customer Authentication in our PSD2 APIs¶

As of September 13, 2019

This section presents the SCA journeys with our 2 means of authentication and strengthen validation (Secure Access and 3SKEY) for the following PSD2 use cases: