API guideline for developers

Interoperability standards

As a minimum requirement, APIs provided by Societe Generale are compliant with REST architecture standards and adopt the 2-level Richardson model (included the HAL convention).

Interface contract: Swagger v2.0

Developments: HTTP 1.1, REST Richardson L2, HAL, JSON format and UTF-8 encoding

Security: TLS 1.2, OpenID Connect

Development bases

Common language

English is the common language for API publications. In particular for contract descriptions and API urls (path + parameters).

The API structure

Only one resource type (and its sub-resources) is exposed by each API provided by Societe Generale.
Example: /agencies

The API documentation

Each API, resource and operation provides a functional rendering overview. Filters, paging, sorting, and counting elements can also be referred.

API description contains a history table of all supported versions. As well as contact details of a technical manager. API specifications are available in Swagger modeling file, which can be downloaded from the API description.

Explore our APIs

HTTP methods configuration

No other HTTP methods than those described below will be available for APIs provided by Societe Generale:

POST: used to create a new resource. This method can also be used for operations that do not correspond to any other method (eg. functions, calculation...)

GET: used to retrieve one or more resources

PUT: used to update one or more resources (potentially with replacement)

PATCH: used instead of PUT method to make changes on a resource (without replacement)

DELETE: used to remove a unique resource

Idempotency

All the APIs provided by Societe Generale are stateless.

Idempotency is also guaranteed on the APIs. Regardless of the number of identical API calls on a resource, the result will always be the same on server side (the answer could be different).

Framework for API request

Authentication and security

"SG SIGNIN" module allows you to authenticate to the "SOCIETE GENERALE | SG OPEN API" platform using your developer account credentials (login and password).

API access is done by the transfer of an access Token (to be included on your request "Authorization" header). The recovery mode of this access Token could be different depending on APIs you want to use. Moreover for some APIs you may be required to import a certificate when registering your application.

Versioning

Versions relate to APIs provided by Societe Generale, not for resources. There are two release levels for these APIs: 'major' and 'minor'. Only the major version has to be indicated on the API path.

Only the latest two major API releases are supported and available. These major releases may not be backward compatible (minor releases are backward compatible).

Using parameters

HTTP Headers are only used for metadata.

Path and query parameters use the 'camelCase' convention for all APIs provided by Societe Generale.

Path parameters are used for resources which include identity elements.
Example: /agencies/{agencyId}/

All others have to be used as query parameters.

Framework for API response

Collections paging

Paging will be enabled in most cases for a query returning a collection. 'offset' and 'limit' parameters are then included on the HTTP response header.

Available HTTP response codes

Only codes below will be available to the HTTP response:

20x: Success

200: Request succeeded for a GET, POST, DELETE, or PATCH call that completed synchronously, or a PUT call that synchronously updated an existing resource

201: Request succeeded for a POST, or PUT call that synchronously created a new resource

202: Request accepted for a POST, PUT, DELETE, or PATCH call that will be processed asynchronously

204: The server successfully processed the request and is not returning any content

206: Request succeeded on GET, but only a partial response returned

40x: Client error

400: General error for any request (if it doesn’t fit in any other)

401: Unauthorized - Request failed because user/client app is not authenticated

403: Forbidden - Request failed because user does not have authorization to access a specific resource

404: Not found - The resource you’re requesting doesn’t exist

422: Unprocessable Entity - Your request was understood, but contained invalid parameters

429: Too many requests

50x: Server error

500: Internal server error - Something went wrong on the server, check status site and/or report the issue

APIs Security

Our APIs are secured through SG Signin OAuth 2 & OIDC server. Full documentation may be found here : https://sg-signin.societegenerale.fr/apidoc/oauth2

Strong Customer Authentication using APIs

Contingency Mechanism

In case of dedicated interface (DSP2 APIs) malfunction, SOCIETE GENERALE will make use a contingency mechanism referred to in Article 32 from COMMISSION DELEGATED REGULATION (EU) 2018/389.
Therefore, SOCIETE GENERALE will provide as contingency mechanism to authorized service providers, a secured  access  to the interfaces made available to the payment service users for the authentication and communication with their account servicing payment service provider, until the dedicated interface is restored to the level of availability and performance provided for in Article 32. 
This contingency mechanism, available trough website links provided hereafter, will be secured by TLS protocol with mutual authentication and will need from service providers the use of eIDAS DSP2 QWAC (Qualified Website Authentication Certificate). 

URL for contingency mechanism (coming soon):

Strong Customer Authentication using contingency mechanism